Skip to main content

Environment Variable Reference

Complete reference for all environment variables used in Easy AppServer deployment.

Required Secrets​

These must be set with strong values (32+ characters) in production:

VariableLengthDescription
POSTGRES_PASSWORD16+Database password
KRATOS_SECRETS_COOKIE32Kratos session cookie encryption
KRATOS_SECRETS_CIPHER32Kratos data encryption
KRATOS_WEBHOOK_SECRET32+Webhook signature verification
HYDRA_SYSTEM_SECRET32+Hydra system encryption
HYDRA_PAIRWISE_SALT32+OIDC pairwise subject salt
APPSERVER_SETTINGS_ENCRYPTION_KEY32App settings AES-256 encryption
APPSERVER_DB_PASSWORD16+AppServer database password

Generate secrets:

# 32-character key
openssl rand -hex 16 | cut -c1-32

# Random password
openssl rand -base64 24

Configuration Files​

There are two environment files:

  • docker/.env - Infrastructure services
  • web/v2/packages/shell/.env - Shell frontend

Some variables must match between them (noted below).

General Settings​

VariableDefaultDescription
LOG_LEVELinfoGlobal log level: debug, info, warn, error
NODE_ENVdevelopmentNode.js environment: development, production
DEPLOYMENT_ENVIRONMENTdevelopmentDeployment label for telemetry

AppServer Configuration​

Server Ports​

VariableDefaultDescription
APPSERVER_HTTP_PORT8080HTTP/GraphQL server port
APPSERVER_GRPC_PORT9091gRPC server port
APPSERVER_ENVdevelopmentEnvironment mode: development, production
APPSERVER_CONFIG_FILE-Optional YAML config file path

Security (gRPC TLS/mTLS)​

VariableDev DefaultProd DefaultDescription
APPSERVER_GRPC_TLS_ENABLEDfalsetrueEnable TLS for gRPC
APPSERVER_GRPC_TLS_CERT_FILE--Server TLS certificate path
APPSERVER_GRPC_TLS_KEY_FILE--Server TLS private key path
APPSERVER_GRPC_MTLS_ENABLEDfalsefalseEnable mutual TLS
APPSERVER_GRPC_MTLS_CA_FILE--CA certificate for client verification

Developer Tools​

VariableDev DefaultProd DefaultDescription
APPSERVER_GRPC_REFLECTION_ENABLEDtruefalsegRPC reflection for tools
APPSERVER_GRAPHQL_PLAYGROUND_ENABLEDtruefalseGraphQL Playground at /graphql
APPSERVER_AUTH_ALLOW_BOOTSTRAP_REGISTRATIONtruefalseAllow app registration without DB entry

Disable all in production!

Database Configuration​

VariableDefaultDescription
APPSERVER_DB_HOSTpostgresPostgreSQL host
APPSERVER_DB_PORT5432PostgreSQL port
APPSERVER_DB_NAMEpartnerDatabase name (contains appserver schema)
APPSERVER_DB_USERpartnerDatabase user
APPSERVER_DB_PASSWORD-Database password (REQUIRED)
APPSERVER_DB_SSLMODEdisableSSL mode: disable, require, verify-full

Note: The AppServer tables are stored in the appserver schema within the partner database. The partner database contains multiple schemas for different services.

Cache Configuration​

VariableDefaultDescription
APPSERVER_REDIS_URLredis://redis:6379Redis connection URL
APPSERVER_CACHE_TTL300Local cache TTL in seconds

Event Bus Configuration​

VariableDefaultDescription
APPSERVER_EVENTBUS_ENABLEDtrueEnable RabbitMQ event bus
APPSERVER_RABBITMQ_URLamqp://guest:guest@rabbitmq:5672/RabbitMQ connection URL
APPSERVER_RABBITMQ_MAX_RETRIES5Max connection retry attempts
APPSERVER_RABBITMQ_PREFETCH_COUNT10Prefetch count for consumers

Telemetry Configuration​

VariableDefaultDescription
APPSERVER_LOG_LEVELdebugAppServer log level
APPSERVER_METRICS_ENABLEDtrueEnable Prometheus metrics
APPSERVER_TRACING_ENABLEDfalseEnable distributed tracing

Authentication & Authorization​

VariableDefaultDescription
APPSERVER_SESSION_COOKIE_NAMEory_kratos_sessionKratos session cookie name
APPSERVER_KRATOS_TIMEOUT5sTimeout for Kratos API calls
APPSERVER_OPENFGA_TIMEOUT5sTimeout for OpenFGA API calls
APPSERVER_SIGNATURE_REPLAY_WINDOW5mApp signature replay protection
APPSERVER_CLOCK_SKEW_TOLERANCE30sClock skew tolerance

External Service URLs​

VariableDefaultDescription
APPSERVER_KRATOS_PUBLIC_URLhttp://kratos:4433Kratos public API URL
APPSERVER_KRATOS_ADMIN_URLhttp://kratos:4434Kratos admin API URL
APPSERVER_HYDRA_PUBLIC_URLhttp://hydra:4444Hydra public API URL
APPSERVER_HYDRA_ADMIN_URLhttp://hydra:4445Hydra admin API URL
APPSERVER_OPENFGA_API_URLhttp://openfga:8089OpenFGA API URL (via nginx proxy)
APPSERVER_OPENFGA_STORE_ID-OpenFGA store ID (REQUIRED)
APPSERVER_OPENFGA_MODEL_ID-OpenFGA model ID (REQUIRED)

Settings Encryption​

VariableDefaultDescription
APPSERVER_SETTINGS_ENCRYPTION_KEY-REQUIRED: Exactly 32 characters
APPSERVER_SETTINGS_CACHE_TTL60Settings cache TTL in seconds

UI Asset Serving​

VariableDefaultDescription
APPSERVER_UI_COMPRESSION_MIN_SIZE1024Min size for compression (bytes)
APPSERVER_UI_COMPRESSION_LEVEL6Compression level (1-9)
APPSERVER_UI_CACHE_TTL300Asset cache TTL in seconds
APPSERVER_UI_MAX_CACHE_SIZE104857600Max cache size (100MB)

Docker Orchestration (Optional)​

VariableDefaultDescription
APPSERVER_DOCKER_ENABLEDfalseEnable Docker orchestration
APPSERVER_DOCKER_SOCKET_PATH/var/run/docker.sockDocker socket path
APPSERVER_DOCKER_REGISTRY_URLregistry.eacore6.deContainer registry URL
APPSERVER_DOCKER_REGISTRY_USERNAME-Registry authentication username
APPSERVER_DOCKER_REGISTRY_PASSWORD-Registry authentication password
APPSERVER_DOCKER_NETWORK_NAMEappserver-networkDocker network name
APPSERVER_DOCKER_NETWORK_SUBNET172.20.0.0/16Docker network subnet
APPSERVER_DOCKER_DEFAULT_IMAGE_STAGElatestImage tag: latest, pre-release, testing
APPSERVER_DOCKER_DEFAULT_CPU_SHARES1024Default CPU shares per container
APPSERVER_DOCKER_DEFAULT_MEMORY_MB512Default memory limit per container (MB)
APPSERVER_DOCKER_PULL_TIMEOUT10mImage pull timeout
APPSERVER_DOCKER_START_TIMEOUT2mContainer start timeout
APPSERVER_DOCKER_STOP_TIMEOUT10sContainer stop timeout
APPSERVER_DOCKER_HEALTH_CHECK_INTERVAL30sHealth check interval
APPSERVER_DOCKER_HEALTH_CHECK_TIMEOUT5sHealth check timeout
APPSERVER_DOCKER_HEALTH_CHECK_RETRIES3Health check retry count
APPSERVER_DOCKER_MAX_RESTARTS3Max container restarts before giving up
APPSERVER_DOCKER_RECONCILE_TIMEOUT2mStartup reconciliation timeout

Infrastructure Services​

PostgreSQL​

VariableDefaultDescription
POSTGRES_USERpartnerPostgreSQL superuser
POSTGRES_PASSWORD-PostgreSQL password (REQUIRED)
POSTGRES_DBpartnerDefault database
POSTGRES_PORT5432PostgreSQL port

Redis​

VariableDefaultDescription
REDIS_PORT6379Redis port

RabbitMQ​

VariableDefaultDescription
RABBITMQ_PORT5672AMQP port
RABBITMQ_MANAGEMENT_PORT15672Management UI port
RABBITMQ_USERguestRabbitMQ user
RABBITMQ_PASSWORDguestRabbitMQ password

Auth Services​

Kratos (Identity)​

VariableDefaultDescription
KRATOS_PUBLIC_PORT4433Public API port
KRATOS_ADMIN_PORT4434Admin API port
KRATOS_SECRETS_COOKIE-REQUIRED: 32 characters
KRATOS_SECRETS_CIPHER-REQUIRED: 32 characters
KRATOS_WEBHOOK_SECRET-REQUIRED: 32+ characters

Note: KRATOS_WEBHOOK_SECRET must match in both docker/.env and shell/.env.

Hydra (OAuth2/OIDC)​

VariableDefaultDescription
HYDRA_PUBLIC_PORT4444Public API port
HYDRA_ADMIN_PORT4445Admin API port
HYDRA_ISSUER_URLhttp://localhost:4444OAuth2 issuer URL
HYDRA_CONSENT_URLhttp://localhost:3000/consentConsent UI URL
HYDRA_LOGIN_URLhttp://localhost:3000/loginLogin UI URL
HYDRA_LOGOUT_URLhttp://localhost:3000/logoutLogout UI URL
HYDRA_SYSTEM_SECRET-REQUIRED: System secret
HYDRA_PAIRWISE_SALT-REQUIRED: Pairwise salt

OpenFGA (Authorization)​

VariableDefaultDescription
OPENFGA_PORT8090HTTP API port
OPENFGA_GRPC_PORT8091gRPC port
OPENFGA_PLAYGROUND_ENABLEDtrueEnable playground UI
OPENFGA_PLAYGROUND_PORT8092Playground port
OPENFGA_STORE_ID-Store ID (from setup script or manual API call)
OPENFGA_MODEL_ID-Model ID (from setup script or manual API call)

Setup Script: docker/scripts/setup-openfga-roles.sh (Docker-exclusive)

For non-Docker deployments, see Manual Setup.

Note: Store ID and Model ID must match in both docker/.env and AppServer config.

Shell Frontend​

These go in web/v2/packages/shell/.env:

VariableDefaultDescription
KRATOS_PUBLIC_URLhttp://localhost:4433Kratos public URL
KRATOS_ADMIN_URLhttp://localhost:4434Kratos admin URL
KRATOS_WEBHOOK_SECRET-REQUIRED: Must match docker/.env
HYDRA_PUBLIC_URLhttp://localhost:4444Hydra public URL
HYDRA_ADMIN_URLhttp://localhost:4445Hydra admin URL
OPENFGA_API_URLhttp://localhost:8090OpenFGA URL
OPENFGA_STORE_ID-REQUIRED: Must match docker/.env
DATABASE_URL-PostgreSQL connection string
C5_BASE_URL-REQUIRED: Legacy backend URL
C5_SESSION_COOKIE_NAMElegacy_sessionLegacy session cookie
TELEMETRY_ENABLEDtrueEnable telemetry
TELEMETRY_SERVICE_NAMEcore6-shellService name for traces
OTEL_EXPORTER_OTLP_ENDPOINThttp://otel-collector:4318OTLP endpoint
LOG_LEVELinfoLog level

Observability Stack​

OpenTelemetry Collector​

VariableDefaultDescription
OTEL_GRPC_PORT4317OTLP gRPC receiver
OTEL_HTTP_PORT4318OTLP HTTP receiver
OTEL_METRICS_PORT8888Collector metrics
OTEL_PROM_EXPORTER_PORT8889Prometheus exporter
OTEL_LOG_LEVELinfoCollector log level

OpenTelemetry SDK (Applications)​

VariableDefaultDescription
OTEL_EXPORTER_OTLP_ENDPOINThttp://otel-collector:4317Collector endpoint
OTEL_EXPORTER_OTLP_PROTOCOLgrpcProtocol: grpc, http
OTEL_SERVICE_NAMEappserverService name
OTEL_RESOURCE_ATTRIBUTES-Resource attributes

Prometheus​

VariableDefaultDescription
PROMETHEUS_PORT9090Server port
PROMETHEUS_RETENTION15dRetention period
PROMETHEUS_RETENTION_SIZE10GBMax storage size

Loki​

VariableDefaultDescription
LOKI_PORT3100API port

Tempo​

VariableDefaultDescription
TEMPO_PORT3200API port

Grafana​

VariableDefaultDescription
GRAFANA_PORT3000Web UI port
GRAFANA_ADMIN_USERadminAdmin username
GRAFANA_ADMIN_PASSWORDadminAdmin password (CHANGE!)
GRAFANA_ROOT_URLhttp://localhost:3000Root URL
GRAFANA_LOG_LEVELinfoLog level

Documentation​

VariableDefaultDescription
DOCS_PORT3030Documentation port
DOCS_TARGETdevelopmentBuild target
DOCUSAURUS_URLhttps://localhostBase URL
DOCUSAURUS_BASE_URL/Base path

Environment Profiles​

Development​

# docker/.env
APPSERVER_ENV=development
APPSERVER_LOG_LEVEL=debug
APPSERVER_GRPC_TLS_ENABLED=false
APPSERVER_GRPC_REFLECTION_ENABLED=true
APPSERVER_GRAPHQL_PLAYGROUND_ENABLED=true
APPSERVER_AUTH_ALLOW_BOOTSTRAP_REGISTRATION=true
APPSERVER_DB_SSLMODE=disable

# URLs (local)
APPSERVER_KRATOS_PUBLIC_URL=http://localhost:4433
APPSERVER_OPENFGA_API_URL=http://localhost:8089

Production​

# docker/.env
APPSERVER_ENV=production
APPSERVER_LOG_LEVEL=warn
APPSERVER_GRPC_TLS_ENABLED=true
APPSERVER_GRPC_REFLECTION_ENABLED=false
APPSERVER_GRAPHQL_PLAYGROUND_ENABLED=false
APPSERVER_AUTH_ALLOW_BOOTSTRAP_REGISTRATION=false
APPSERVER_DB_SSLMODE=verify-full
APPSERVER_TRACING_ENABLED=true

# URLs (internal network)
APPSERVER_KRATOS_PUBLIC_URL=http://kratos:4433
APPSERVER_OPENFGA_API_URL=http://openfga:8089

Security Checklist​

Secrets to Change​

  • POSTGRES_PASSWORD - Strong database password
  • KRATOS_SECRETS_COOKIE - Exactly 32 characters
  • KRATOS_SECRETS_CIPHER - Exactly 32 characters
  • KRATOS_WEBHOOK_SECRET - At least 32 characters
  • HYDRA_SYSTEM_SECRET - Strong secret
  • HYDRA_PAIRWISE_SALT - Strong salt
  • APPSERVER_SETTINGS_ENCRYPTION_KEY - Exactly 32 characters
  • RABBITMQ_USER and RABBITMQ_PASSWORD - Change from defaults
  • GRAFANA_ADMIN_PASSWORD - Change from default

Settings to Verify​

  • APPSERVER_GRPC_TLS_ENABLED=true
  • APPSERVER_DB_SSLMODE=verify-full
  • APPSERVER_GRPC_REFLECTION_ENABLED=false
  • APPSERVER_GRAPHQL_PLAYGROUND_ENABLED=false
  • APPSERVER_AUTH_ALLOW_BOOTSTRAP_REGISTRATION=false

Variables That Must Match​

Variabledocker/.envshell/.env
KRATOS_WEBHOOK_SECRETYesYes
OPENFGA_STORE_IDYesYes
POSTGRES_PASSWORDYesIn DATABASE_URL