Environment Variables
Complete reference for all environment variables supported by Strata Server. Variables marked as Required must be set for the application to start. All others have sensible defaults and can be configured as needed.
Environment Template
Preferred: generate a ready-to-edit .env with Strata secrets created locally:
curl -fsSL https://strata.do/self-hosting/env.sh | bash -s -- ./.env
Secret Generation Reference
For manual and cloud deployments, generate the Strata encryption secrets before deployment.
Expected formats:
STRATA_SECRET_KEY_BASE: hex string, 128 characters (openssl rand -hex 64)STRATA_ENCRYPTION_PRIMARY_KEY: hex string, 32 characters (openssl rand -hex 16)STRATA_ENCRYPTION_DETERMINISTIC_KEY: hex string, 32 characters (openssl rand -hex 16)STRATA_ENCRYPTION_KEY_DERIVATION_SALT: hex string, 32 characters (openssl rand -hex 16)
Generate all four at once:
STRATA_SECRET_KEY_BASE=$(openssl rand -hex 64)
STRATA_ENCRYPTION_PRIMARY_KEY=$(openssl rand -hex 16)
STRATA_ENCRYPTION_DETERMINISTIC_KEY=$(openssl rand -hex 16)
STRATA_ENCRYPTION_KEY_DERIVATION_SALT=$(openssl rand -hex 16)
Database (Required)
These connect Strata to your PostgreSQL instance. Strata uses four databases (primary, queue, cache, cable) and all share the same connection credentials.
| Variable | Required | Default | Description |
|---|---|---|---|
DB_HOST | Yes | localhost | PostgreSQL hostname or IP address |
DB_PORT | No | 5432 | PostgreSQL port |
DB_USERNAME | No | postgres | PostgreSQL username |
DB_PASSWORD | No | postgres | PostgreSQL password |
The database user needs CREATEDB privilege for Strata to auto-create its four databases on first start. If your user cannot create databases, create them manually — see Manual Host Deployment.
License (Required)
| Variable | Required | Default | Description |
|---|---|---|---|
LICENSE_KEY | Yes | — | Your Strata license key (JWT token issued for your organization). Without a valid license, the application displays a "License Required" page. |
Application
| Variable | Required | Default | Description |
|---|---|---|---|
PORT | No | 3000 | Host port for the web UI (mapped to container STRATA_CONTAINER_PORT) |
STRATA_CONTAINER_PORT | No | 80 | Container HTTP listen port for Strata runtime. Set to 8080 on ECS Fargate — non-root containers cannot bind to ports below 1024. |
APP_HOST | No | localhost | Application hostname, used in email links and URL generation |
APP_PROTOCOL | No | https | Protocol for generated URLs (http or https) |
STRATA_SECRET_KEY_BASE | Yes | Generated by env.sh / installer (if missing) | Strata application secret for encrypting sessions, cookies, and signed tokens. All nodes must share the same value in multi-node deployments. Generate with openssl rand -hex 64. |
STRATA_ENCRYPTION_PRIMARY_KEY | Yes | Generated by env.sh / installer (if missing) | Primary key used for Strata data-at-rest encryption (for example datasource credentials). Generate with openssl rand -hex 16. |
STRATA_ENCRYPTION_DETERMINISTIC_KEY | Yes | Generated by env.sh / installer (if missing) | Deterministic key used by Strata encryption for deterministic encrypted attributes. Generate with openssl rand -hex 16. |
STRATA_ENCRYPTION_KEY_DERIVATION_SALT | Yes | Generated by env.sh / installer (if missing) | Salt used by Strata encryption key derivation. Generate with openssl rand -hex 16. |
STRATA_VERSION | No | latest | Docker image tag to use. Set to a specific version (e.g., 1.0.0) to pin releases. |
SSL
Configure these based on your reverse proxy setup. See SSL & Reverse Proxy for detailed setup instructions.
| Variable | Required | Default | Description |
|---|---|---|---|
ASSUME_SSL | No | false | Trust X-Forwarded-Proto header from your reverse proxy. Set to true when behind an SSL-terminating proxy. |
FORCE_SSL | No | false | Redirect HTTP requests to HTTPS. Set to true when using SSL. |
Once you have a reverse proxy terminating SSL, set both ASSUME_SSL=true and FORCE_SSL=true.
Storage
By default, Strata stores uploaded files on the local filesystem (Docker volume). For production ECS deployments, mount an EFS volume for persistent shared storage. For cloud object storage, configure one of the supported backends: Amazon S3, Google Cloud Storage, or Azure Blob Storage.
EFS (ECS Deployments)
When an EFS volume is mounted at /mnt/efs, Strata automatically detects it and uses it for file storage. No environment variables are needed — just mount the volume. See AWS ECS Deployment for setup instructions.
Common
| Variable | Required | Default | Description |
|---|---|---|---|
STORAGE_BACKEND | No | local | File storage service: local (Docker volume or EFS if mounted at /mnt/efs), amazon (S3-compatible), google (GCS), or microsoft (Azure Blob) |
Amazon S3 / S3-Compatible
| Variable | Required | Default | Description |
|---|---|---|---|
AWS_ACCESS_KEY_ID | Yes | — | AWS access key ID (or compatible provider credentials) |
AWS_SECRET_ACCESS_KEY | Yes | — | AWS secret access key |
AWS_REGION | No | us-east-1 | AWS region |
S3_BUCKET | Yes | — | S3 bucket name |
S3_ENDPOINT | No | — | Custom endpoint for S3-compatible services (MinIO, DigitalOcean Spaces, Backblaze B2, etc.) |
Google Cloud Storage
| Variable | Required | Default | Description |
|---|---|---|---|
GCS_PROJECT | Yes | — | Google Cloud project ID |
GCS_CREDENTIALS | Yes | — | Service account JSON key (inline JSON string or file path) |
GCS_BUCKET | Yes | — | GCS bucket name |
Azure Blob Storage
| Variable | Required | Default | Description |
|---|---|---|---|
AZURE_STORAGE_ACCOUNT | Yes | — | Azure storage account name |
AZURE_STORAGE_ACCESS_KEY | Yes | — | Azure storage access key |
AZURE_STORAGE_CONTAINER | Yes | — | Azure blob container name |
Example: AWS S3
STORAGE_BACKEND=amazon
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1
S3_BUCKET=strata-uploads
Example: MinIO
STORAGE_BACKEND=amazon
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_REGION=us-east-1
S3_BUCKET=strata
S3_ENDPOINT=http://minio.internal:9000
Example: Google Cloud Storage
STORAGE_BACKEND=google
GCS_PROJECT=my-gcp-project
GCS_CREDENTIALS=/path/to/service-account.json
GCS_BUCKET=strata-uploads
Example: Azure Blob Storage
STORAGE_BACKEND=microsoft
AZURE_STORAGE_ACCOUNT=stratastorage
AZURE_STORAGE_ACCESS_KEY=your_access_key
AZURE_STORAGE_CONTAINER=strata-uploads
Performance
Web container
| Variable | Required | Default | Description |
|---|---|---|---|
WEB_CONCURRENCY | No | 2 in production, single process in dev | Puma worker processes per web container. Ignored in development (single-process Puma). Use 2 on 4 vCPU / 8 GB production tasks. |
WEB_THREADS | No | 5 | Puma threads per worker process. Request capacity ≈ WEB_CONCURRENCY × WEB_THREADS in production. Also sets the database pool when DB_POOL_SIZE is unset (see below). |
DB_POOL_SIZE | No | falls back to WEB_THREADS, then 5 | Active Record pool in config/database.yml per Ruby process. Omit in normal deployments so pool tracks WEB_THREADS. |
STRATA_RUN_DB_PREPARE | No | true | Set to false on job containers so only web runs migrations on boot. |
STRATA_LOG_LEVEL | No | info | Log verbosity: debug, info, warn, error, fatal. Maps to config.log_level in production. |
Job container
| Variable | Required | Default | Description |
|---|---|---|---|
JOB_CONCURRENCY | No | 1 | Solid Queue worker processes per job container (config/queue.yml). Enterprise Compose defaults to 4. |
JOB_THREADS | No | 3 | Solid Queue threads per process in config/queue.yml. Job capacity ≈ JOB_CONCURRENCY × JOB_THREADS. |
STRATA_RUN_DB_PREPARE | No | true | Must be false on the job service. |
Database connection pool (database.yml)
Each Puma worker and each Solid Queue process in the job service is a separate Ruby process with its own connection pool. The pool size is resolved at boot:
DB_POOL_SIZE— optional override (advanced)- else
WEB_THREADS - else
RAILS_MAX_THREADS(Rails convention, rarely needed) - else
5
Rule of thumb: leave DB_POOL_SIZE unset and set only WEB_THREADS on web. Pool should match threads per process (pool ≥ concurrent request threads in that process). Set DB_POOL_SIZE explicitly only after profiling (never lower than thread count).
On job containers, pool uses the same fallback; default pool 5 is enough for default JOB_THREADS=3.
Sizing notes
- Postgres connections scale with replicas: each web task uses up to
WEB_CONCURRENCY ×(effective pool size) connections per database role when pools are active. Strata uses four databases (primary, queue, cache, cable) — plan headroom accordingly. - Scale web task count for HTTP RPS; scale job task count and
JOB_CONCURRENCYfor job throughput. - See Performance and scaling for capacity formulas and load-test guidance.
For a server with 4+ CPU cores and 8+ GB RAM, a good starting point is WEB_CONCURRENCY=2 and WEB_THREADS=5 on web, plus a separate job service with JOB_CONCURRENCY=4 and JOB_THREADS=3.
Advanced: single-container (monolith) production
Enterprise installs use web and job services; you do not need to configure Solid Queue for Puma. With RAILS_ENV=production, jobs are not processed inside the web container unless you opt in.
| Variable | When to set |
|---|---|
HANDLE_JOBS_IN_WEB_SERVER | Set to true on the web container only for a single-container (monolith) deployment with no job service. Set to false to force jobs out of Puma in non-production (unusual). |