example.env

# ==============================================
# API CONFIGURATION
# ==============================================

# API root path prefix (e.g., "/test" or "" for root)
# If empty or not set, the API will be available at the root path
# This is useful when deploying the API behind a reverse proxy at a subpath
ROOT_PATH=

# ==============================================
# ORGANIZATION
# ==============================================

ORGANIZATION="ORGANIZATION-DEMO"
EP_NAME="EP-DEMO"

# Whether this Endpoint is listed on the platform. It decides whether the
# periodic metrics are posted to METRICS_ENDPOINT: with False they are
# collected and logged, and nothing leaves the Endpoint. An Endpoint not
# registered with the Federation should set it to False (the installer does).
IS_PUBLIC=True

# ==============================================
# METRICS CONFIGURATION
# ==============================================

# Interval in seconds between metrics reports (default: 3300 seconds = 55
# minutes). The first report is sent at startup, by one worker only; a failed
# post is logged and not retried. Full contract:
# docs/architecture/federation-and-metrics.md
METRICS_INTERVAL_SECONDS=3300

# Endpoint the periodic metrics report is POSTed to (only when IS_PUBLIC=True).
# The installer sets it to <federation-url>/metrics/ for the Federation it was
# pointed at; the default below is the production Federation.
METRICS_ENDPOINT=https://federation.ndp.utah.edu/metrics/

# Optional deployment metadata included in the metrics report, so the platform
# can see this Endpoint's NetBird connectivity. All optional; empty means not
# reported. Only a boolean saying whether a CKAN API key is configured is
# reported — never the key itself.
NETBIRD_ENABLED=False
NETBIRD_IP=
NETBIRD_GROUP=
# ==============================================
# ACCESS CONTROL (Optional)
# ==============================================
# Every write (POST, PUT, PATCH, DELETE) requires a writer-tier role
# (ndp_writer, ndp_editor, ndp_admin, or group:<group>:writer|editor|admin,
# where <group> is a GROUP_NAMES entry or AFFINITIES_EP_UUID), whether or not
# group-based access is on. Not every GET is public: /status/*, /user/info,
# /pelican/* and /s3/* need a token. See README.md and
# docs/roles-and-permissions.md.
#
# With ENABLE_GROUP_BASED_ACCESS=True the user must ALSO belong to a group in
# GROUP_NAMES, or to the group named AFFINITIES_EP_UUID, or hold ndp_admin.
# This gate applies to writes, to the viewer-tier /pelican/* routes and to
# /user/info, so a user who fails it cannot enter the UI.
#
# Groups come from AUTH_API_URL's answer for the token. Matching is
# case-insensitive (e.g., "Admins" matches "admins") and ignores a leading "/".

# Enable group-based access control (True/False)
ENABLE_GROUP_BASED_ACCESS=False

# Comma-separated list of groups that give access to this Endpoint
# Example: GROUP_NAMES=admins,developers,data-managers
# The first entry is also the group access requests are approved into.
# If empty and ENABLE_GROUP_BASED_ACCESS=True, only ndp_admin holders and
# members of the AFFINITIES_EP_UUID group get in.
GROUP_NAMES=

# ==============================================
# ACCESS REQUESTS (Optional)
# ==============================================
# Self-service workflow: a user requests access, an admin approves/rejects.
# Requires MongoDB reachable via MONGODB_CONNECTION_STRING (see below),
# whatever the catalog backend. Approval grants membership (and, for writer or
# admin, the role) on the first GROUP_NAMES entry, falling back to
# AFFINITIES_EP_UUID. With False the access-request routes answer 503.
ENABLE_ACCESS_REQUESTS=False

# MongoDB collection used to store access requests
ACCESS_REQUESTS_COLLECTION=access_requests

# ==============================================
# LOCAL CATALOG CONFIGURATION
# ==============================================

# Backend for local catalog: "ckan", "mongodb" or "none"
# Global and Pre-CKAN always use CKAN regardless of this setting
#
# "none" is an Endpoint with no local catalog: nothing is stored locally and
# no MongoDB or CKAN is needed. It still authenticates users, searches the
# platform's global catalog and reports to the Federation. The routes that
# write to a local catalog are not mounted with "none", whatever
# CKAN_LOCAL_ENABLED says; set it to False alongside it for consistency.
LOCAL_CATALOG_BACKEND=mongodb

# ==============================================
# LOCAL CATALOG CONFIGURATION
# ==============================================

# Enable or disable local catalog operations (True/False, default False)
# IMPORTANT: This setting is the master switch that mounts the registration,
# update, delete and resource routes (POST/PUT/PATCH/DELETE, /resource,
# /resources/search) for ANY local catalog backend (CKAN or MongoDB). Searching
# the local catalog (GET /search?server=local) also requires it.
#
# Set to True to enable:
# - Creating organizations, datasets, resources
# - Updating and deleting catalog entries
# - Publishing datasets to Pre-CKAN
#
# Set to False to leave those routes unmounted. With LOCAL_CATALOG_BACKEND
# "none" they are unmounted regardless: there is no catalog to write to.
#
# Note: The variable name contains "CKAN" for historical reasons, but it applies
# to all local catalog backends (CKAN, MongoDB, etc.)
CKAN_LOCAL_ENABLED=True

# ==============================================
# CKAN-SPECIFIC CONFIGURATION (only if LOCAL_CATALOG_BACKEND=ckan)
# ==============================================
# Leave the two fields below EMPTY when LOCAL_CATALOG_BACKEND=mongodb — they
# are only read by the CKAN backend. Note that CKAN_LOCAL_ENABLED above is the
# master switch for local catalog writes for ANY backend, so it stays True even
# on MongoDB; it is not a "use CKAN" flag despite the name.

# Base URL of your local CKAN instance (Required only for CKAN backend)
CKAN_URL=

# API Key for CKAN authentication (Required only for CKAN backend)
CKAN_API_KEY=

# Verify the local CKAN TLS certificate (True/False, default: True)
# Set to False when CKAN_URL points to an instance with a self-signed
# or otherwise untrusted certificate (e.g. local/dev clusters). Disabling
# verification reduces security, so keep it True in production.
CKAN_VERIFY_SSL=True

# ==============================================
# MongoDB Configuration (if LOCAL_CATALOG_BACKEND=mongodb)
# ==============================================

# MongoDB connection string (also used for access requests, whatever the
# catalog backend)
# From the API container with the compose 'mongodb' profile: the service name
# 'mongodb' and the credentials that profile starts MongoDB with (as below).
# From the host, the bundled MongoDB is published on port 27018.
MONGODB_CONNECTION_STRING=mongodb://admin:admin123@mongodb:27017

# Root password the bundled MongoDB (compose 'mongodb' profile) is created
# with; the connection string above must carry the same one. The installer
# generates one per installation and keeps it in .env.install-state; admin123
# is only the demo default.
MONGODB_ROOT_PASSWORD=admin123

# MongoDB database name for local catalog
MONGODB_DATABASE=ndp_local_catalog

# ==============================================
# Pre-CKAN Configuration
# ==============================================

# Enable or disable the Pre-CKAN instance (True/False)
PRE_CKAN_ENABLED=False

# URL of the Pre-CKAN instance (Optional)
PRE_CKAN_URL=

# API key for Pre-CKAN authentication (Optional)
PRE_CKAN_API_KEY=

# Verify the Pre-CKAN TLS certificate (True/False, default: True)
# Same semantics as CKAN_VERIFY_SSL but for the Pre-CKAN instance defined above.
PRE_CKAN_VERIFY_SSL=True

# Organization name for Pre-CKAN (Optional)
# When set, this organization will be used for all datasets published to PRE-CKAN,
# overriding the original owner_org from the local catalog.
# This is required when your PRE-CKAN credentials are tied to a specific organization.
PRE_CKAN_ORGANIZATION=

# ==============================================
# Streaming Configuration
# ==============================================

# Enable or disable Kafka connectivity (True/False)
KAFKA_CONNECTION=True

# Kafka broker hostname or IP address. The API uses it, and also returns it
# unchanged to streaming clients (GET /status/kafka-details), so clients
# outside the compose network need an address they can reach.
# With the compose 'kafka' profile, from the API container: service name 'kafka'
KAFKA_HOST=kafka

# Kafka broker port number
# The compose 'kafka' profile's broker listens on 9093 inside the compose
# network (kafka:9093) and on 9092 advertised as localhost:9092; those are
# published on host ports 9095 and 9094 respectively.
KAFKA_PORT=9093

# Per-user derived-stream quota. Leave blank for unlimited streams.
MAX_STREAMS=10

# ==============================================
# Test Token Credentials
# ==============================================

# A Bearer token equal to this value is accepted as a user with the ndp_admin
# role, without contacting AUTH_API_URL. For development only.
# Leave blank in production.
TEST_TOKEN=testing_token

# ==============================================
# Authentication Configuration
# ==============================================

# URL for the authentication API to retrieve user information
# This endpoint is used to validate tokens and fetch user details
AUTH_API_URL=https://idp.nationaldataplatform.org/temp/information

# ----------------------------------------------
# Identity provider sign-in (Optional · OFF by default)
# ----------------------------------------------
# Adds a button to the UI login screen that sends the user to the identity
# provider's own login page. This is what makes the federated providers
# configured on the realm (e.g. CILogon, EarthScope, ORCID) usable: those
# users have no password in the realm, so the username/password form cannot
# work for them and pasting an access token by hand is their only alternative.
#
# This is an ADDITIONAL way in. The access token and username/password forms
# stay exactly as they are, whether this is on or off.

# Master switch. False (the default) means the login screen behaves exactly as
# it did before and none of the values below are read.
OIDC_ENABLED=False

# The realm URL. Everything else (authorization, token and userinfo endpoints)
# is read from its OpenID discovery document, so no provider-specific URL is
# ever hardcoded and pointing this at a different Keycloak is all that a move
# from a local instance to production requires.
# Required when OIDC_ENABLED=True.
# OIDC_ISSUER=https://idp.nationaldataplatform.org/realms/NDP

# The client id registered for THIS Endpoint. Required when OIDC_ENABLED=True.
# OIDC_CLIENT_ID=ndp-ep-ui

# Optional. Defaults to "openid profile email" when empty.
# OIDC_SCOPE=

# Optional wording. The defaults are provider-neutral because only the
# deployment knows which providers its realm actually offers. Leave
# OIDC_HELP_TEXT empty to show no second line.
# Default: "Sign in with your identity provider"
# OIDC_BUTTON_LABEL=Sign in with National Data Platform
# OIDC_HELP_TEXT=Use your institutional credentials, EarthScope or ORCID.

# ----------------------------------------------
# What the identity provider administrator must register
# ----------------------------------------------
# 1. A PUBLIC client with PKCE (S256) enabled. Public rather than confidential
#    so that no client secret has to be shipped with the Endpoint, which is
#    self-hosted by many institutions.
#
# 2. This deployment's callback URL as a valid redirect URI on that client:
#      <scheme>://<host>[:<port>]<ROOT_PATH>/ui/auth/callback
#    e.g. https://my-endpoint.example.org/ep-api/ui/auth/callback
#    The Endpoint derives this from the browser's address and ROOT_PATH, so it
#    is never configured here — but it must match what is registered.
#
# 3. The client MUST issue the `sub` claim in its access tokens. AUTH_API_URL
#    looks the user up by `sub`; a token without it fails validation and the
#    UI reports that the Endpoint could not validate the token, even though
#    the sign-in itself succeeded.
#    Since Keycloak 24 that claim comes from the built-in `basic` client
#    scope. A realm imported from an older export may not have `basic` among
#    its default scopes, in which case a newly created client silently mints
#    tokens with no `sub` — assign the scope to the client explicitly.
#
# 4. OIDC_ISSUER and AUTH_API_URL must point at the SAME identity provider.
#    The token is minted by one and validated by the other; if they disagree,
#    the user's `sub` will not exist on the validating side and sign-in fails.
#
# 5. Serve the UI over https. Browsers only expose the crypto API that PKCE
#    needs in secure contexts, so on a plain-http/bare-IP deployment the
#    button is shown disabled with an explanation (`localhost` counts as
#    secure, so an SSH tunnel works for testing).

# ==============================================
# External Service Integrations
# ==============================================

# Enable or disable JupyterLab integration (True/False)
USE_JUPYTERLAB=True

# URL to your JupyterLab instance. The API does not connect to it: it returns
# it to clients (GET /status/jupyter, the UI) and reports it in the metrics,
# so it must be an address users can open. The compose 'jupyter' profile
# publishes JupyterLab on host port 8888; 'jupyterlab' is its service name
# inside the compose network only.
JUPYTER_URL=http://jupyterlab:8888

# ==============================================
# S3 Storage Configuration
# ==============================================

# Enable or disable S3 storage (True/False)
S3_ENABLED=True

# S3 endpoint (host:port) - use your S3-compatible service endpoint
# With the compose 's3' profile, from the API container: 'minio:9000'
# (published on host port 9002, console on 9003). The credentials below are
# the ones that profile starts the service with; the installer generates them
# per installation, and minioadmin/minioadmin123 are only the demo default.
S3_ENDPOINT=minio:9000

# S3 access credentials
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin123

# Use secure connection (True for HTTPS, False for HTTP)
S3_SECURE=False

# Default region
S3_REGION=us-east-1

# ==============================================
# Pelican Federation Configuration
# ==============================================

# Enable or disable Pelican federation access (True/False)
# Set to True to mount the /pelican/* routes (all need a Bearer token with the
# viewer tier; import-metadata needs writer):
# - Browsing external Pelican federations (OSDF, etc.)
# - Downloading and reading files from federated data repositories
# - Subscribing to Pelican file events
# - Importing external files as resources of a local dataset
PELICAN_ENABLED=True

# Default Pelican federation URL
# Leave empty to use OSDF (Open Science Data Federation) by default
# Format: pelican://federation-host (e.g., pelican://osg-htc.org)
PELICAN_FEDERATION_URL=

# Enable direct reads from Origins (bypassing caches)
# Set to True to read directly from origin servers
# Set to False to use caching infrastructure (recommended for better performance)
PELICAN_DIRECT_READS=False

# Largest object /pelican/read will return inline, in bytes
# The read endpoint returns file contents in the response body, so this caps
# how much can be pulled into the API's memory by a single request
# Anything larger must be fetched with /pelican/download instead
# Default: 10485760 (10 MiB)
PELICAN_MAX_READ_BYTES=10485760

# Pelican file-event subscriptions (GET /pelican/subscribe)
# The event server notifies subscribers when an object appears in a namespace
# Leave the URL empty to use the default event server
PELICAN_EVENT_SERVER_URL=

# Identifies this Endpoint to the event server. MUST be unique: two subscribers
# sharing an id compete for the same events instead of both receiving them
# Must not contain "/". Falls back to AFFINITIES_EP_UUID when left empty
PELICAN_EVENT_CLIENT_ID=

# Event server credentials, checked against its own store
# Unrelated to the Endpoint token; set both or neither
# Temporary: they will be replaced by an access token issued for NDP
PELICAN_EVENT_USERNAME=
PELICAN_EVENT_PASSWORD=

# STOMP virtual host on the event server
PELICAN_EVENT_VIRTUAL_HOST=playground

# Liveness interval in milliseconds, minimum 1000
PELICAN_EVENT_HEARTBEAT_MS=10000

# ==============================================
# Rexec Deployment API Configuration
# ==============================================

# Enable or disable Remote Execution Deployment API connectivity (True/False)
REXEC_CONNECTION=False

# Remote Execution Deployment API URL
REXEC_DEPLOYMENT_API_URL=

# ==============================================
# Affinities Integration Configuration
# ==============================================

# Enable or disable NDP Affinities integration (True/False)
# When enabled, datasets and services created in this endpoint will be
# automatically registered in the Affinities system.
AFFINITIES_ENABLED=False

# Base URL of the Affinities API
# Example: http://affinities-api:8000 or https://affinities.example.com
AFFINITIES_URL=

# UUID of this endpoint in Affinities
# This UUID is obtained when you manually register this endpoint
# in the Affinities system via POST /endpoints
# Example: 550e8400-e29b-41d4-a716-446655440000
# Also used for access control even with AFFINITIES_ENABLED=False: members of
# the group with this name pass the group-based access gate, and
# group:<AFFINITIES_EP_UUID>:<tier> roles count like those of a GROUP_NAMES
# group. Passed to the UI as affinitiesEpUuid.
AFFINITIES_EP_UUID=

# Request timeout in seconds (default: 30)
AFFINITIES_TIMEOUT=30

# ==============================================
# SEVERAL ENDPOINTS ON ONE HOST
# ==============================================
# Written by `install.sh --instance <name>` (issue #355); leave them unset for a
# single Endpoint. EP_INSTANCE prefixes every container name (unset: ndp, as in
# ndp-ep-api) and COMPOSE_PROJECT_NAME keeps each Endpoint's containers,
# network and volumes apart. Do not change either on an installed Endpoint:
# Compose would start a new project with new, empty volumes.
# EP_INSTANCE=ndp
# COMPOSE_PROJECT_NAME=ndp-ep-<name>
# Host ports published by the bundled services (unset: the values below).
# The API's own port is EP_API_PORT, passed on the docker compose command line.
# MONGODB_HOST_PORT=27018
# MINIO_HOST_PORT=9002
# MINIO_CONSOLE_HOST_PORT=9003
# KAFKA_HOST_PORT=9094
# KAFKA_INTERNAL_HOST_PORT=9095
# KAFKA_UI_HOST_PORT=8081