Deployment
Environment Reference
Canonical reference for runtime, build, bootstrap, storage, email, frontend, and testing environment variables.
Last updated
This is the canonical environment-variable reference for deployment and local operation.
The backend and worker runtime schema is validated from:
packages/config/src/index.ts
Use this page as the source of truth, then use the smaller env excerpts shown on each deployment page as practical starting points.
Reading this page
| Column | Meaning |
|---|---|
| Required | Yes means the variable is required for that deployment context |
| Default | Value used when the application or compose file provides one |
| Scope | Where the variable matters |
Compose bootstrap variables
These variables are used mainly by the compose deployment variants.
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
POSTGRES_USER | Usually yes for compose-managed Postgres | remoteeaze | Compose infra | Database superuser / app DB owner for the bundled Postgres service |
POSTGRES_PASSWORD | Yes for compose-managed Postgres | None | Compose infra | Password for the bundled Postgres service |
POSTGRES_DB | Usually yes for compose-managed Postgres | remote_eaze | Compose infra | Database name created by the bundled Postgres service |
REDIS_PASSWORD | Yes for compose-managed Redis | None | Compose infra | Password for the bundled Redis service |
API_PORT | Optional | 3000 | Compose, manual runtime | Public or mapped API port |
WEB_PORT | Optional | 5173 | Compose | Public or mapped web port |
DOCS_PORT | Optional | 3001 | Compose docs | Public or mapped docs port |
IMAGE_TAG | Optional | latest | Dokploy, registry images | Image tag for GHCR runtime images |
SKIP_INFISICAL | Optional | false | Registry/source/manual | Bypasses the Infisical entrypoint wrapper when set to true |
Infisical bootstrap variables
These variables are needed when you use Infisical-backed startup.
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
INFISICAL_PROJECT_ID | Yes when using Infisical | None | Compose, manual runtime | Identifies the Infisical project to read secrets from |
INFISICAL_ENV | Yes when using Infisical | dev or prod depending on compose file | Compose, manual runtime | Infisical environment slug |
INFISICAL_API_URL | Optional | https://app.infisical.com | Compose, manual runtime | Infisical API base URL |
INFISICAL_TOKEN_API | Yes when using Infisical compose | None | Dokploy, source, registry | Token used by the API container |
INFISICAL_TOKEN_WORKER | Yes when using Infisical compose | None | Dokploy, source, registry | Token used by the worker container |
INFISICAL_TOKEN_MIGRATE | Yes when using Infisical compose | None | Dokploy, source, registry | Token used by the migration container |
INFISICAL_TOKEN_TOOLS | Required only when using the tools profile with Infisical | None | Dokploy, source, registry | Token used by the tools container |
Infisical versus raw envs
If you use Infisical, these bootstrap variables get the containers to the point where they can fetch the real app configuration. If you do not use Infisical, you must provide the full runtime env set directly and use SKIP_INFISICAL=true where supported. The Dokploy compose variant is intentionally Infisical-backed; use the source-build, registry-images, or manual-runtime paths if you want a raw-env deployment.
Core runtime variables
These are the main backend and worker runtime variables.
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
NODE_ENV | Optional | development | All app services | Runtime mode |
DATABASE_URL | Yes | None | API, worker, tools, migrate | PostgreSQL connection string |
REDIS_URL | Yes | None | API, worker, tools | Redis connection string |
LOG_LEVEL | Optional | info | API, worker, tools | Structured log verbosity |
Auth and security variables
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
BETTER_AUTH_SECRET | Yes | None | API, auth flows, tools | Better Auth signing and internal security secret |
BETTER_AUTH_URL | Yes | None | API, auth flows | Public backend auth base URL |
ENCRYPTION_KEY | Yes | None | API, worker | Application encryption key |
ENCRYPTION_SALT | Yes | None | API, worker | Application encryption salt |
LICENSE_SECRET_KEY | Yes | None | API, worker | License signing / verification secret |
FRONTEND_URL | Yes | None | API, worker, email | Public web app URL used in links and trusted-origins resolution |
ADDITIONAL_TRUSTED_ORIGINS | Optional | Empty | API/auth | Extra comma-separated request origins allowed for auth and browser-like clients |
FRONTEND_NATIVE_URLS | Optional | Empty | API/auth | Extra comma-separated native-shell origins trusted by auth/session logic |
Notes on trusted origins
Typical use cases for ADDITIONAL_TRUSTED_ORIGINS or FRONTEND_NATIVE_URLS:
- Android emulator traffic
- Capacitor shells
- embedded/native wrappers that call auth endpoints directly
Examples:
ADDITIONAL_TRUSTED_ORIGINS=http://10.0.2.2
FRONTEND_NATIVE_URLS=capacitor://localhostEmail and notification variables
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
RESEND_API_KEY | Yes in the current runtime schema | None | API, worker, tools | Resend API authentication |
RESEND_FROM_EMAIL | Yes in the current runtime schema | None | API, worker, tools | Sender address used for outbound emails |
REMOTE_EAZE_DISABLE_OUTBOUND_EMAIL | Optional | false | API, worker, tools | Disables actual outbound email delivery while keeping the code paths intact |
Email disable flag does not remove the env requirement
The current env schema still requires RESEND_API_KEY and RESEND_FROM_EMAIL even when REMOTE_EAZE_DISABLE_OUTBOUND_EMAIL=true.
Worker and scheduler variables
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
WORKER_CONCURRENCY | Optional | 15 | Worker | Max parallel jobs processed across queues |
WORKER_SHUTDOWN_TIMEOUT_MS | Optional | 30000 | Worker | Graceful worker shutdown timeout |
SYSTEM_SESSION_TIMEOUT | Optional | 900 | API, worker | SYSTEM tenant inactivity timeout in seconds |
SESSION_CLEANUP_INTERVAL_MS | Optional | 120000 | Worker | How often the session cleanup job runs |
FDT_DUE_SCAN_INTERVAL_MS | Optional | 60000 | Worker | How often the forward-dated due-scan runs |
COB_SCHEDULER_INTERVAL_MS | Optional | 60000 | Worker | How often the COB scheduler scans for due runs |
HOLIDAY_CHANGE_BUFFER_DAYS | Optional | 1 | API | Prevents adding public holidays too close to the current working day |
WORKBENCH_OFFLINE_SESSION_TIMEOUT | Optional | 86400 | API, worker | Offline field-agent session timeout in seconds |
Storage variables
The storage plugin is startup-critical. If these values are wrong, the API can fail early.
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
STORAGE_ENDPOINT | Yes | None | API, worker, web build | S3-compatible endpoint URL |
STORAGE_REGION | Optional | us-east-1 | API, worker | S3 region string |
STORAGE_BUCKET | Yes | None | API, worker | Bucket name |
STORAGE_ACCESS_KEY | Yes | None | API, worker | Storage access key |
STORAGE_SECRET_KEY | Yes | None | API, worker | Storage secret key |
STORAGE_PRESIGN_UPLOAD_EXPIRY_SECONDS | Optional | 300 | API | Presigned upload URL lifetime |
STORAGE_PRESIGN_DOWNLOAD_EXPIRY_SECONDS | Optional | 900 | API | Presigned download URL lifetime |
STORAGE_MAX_FILE_SIZE_BYTES | Optional | 52428800 | API | Maximum accepted upload size in bytes |
Frontend and browser variables
These are read by the web app or by the web build.
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
VITE_APP_VERSION | Optional | None | Web build/runtime | Frontend release identifier for cache resets and diagnostics |
VITE_BACKEND_URL | Optional | None | Native / special web setups | Explicit backend base URL when not using same-origin routing |
VITE_API_BASE_URL | Optional, deprecated | None | Native / special web setups | Older alias for VITE_BACKEND_URL |
REMOTE_EAZE_DISABLE_PWA | Optional | false | Web build | Disables PWA generation when set to true |
VITE_WORKBENCH_OFFLINE_ACCESS_TTL_MS | Optional | 86400000 | Web runtime | Offline access envelope TTL |
VITE_WORKBENCH_NATIVE_LOCAL_REENTRY_TTL_MS | Optional | 172800000 | Web/native runtime | Native local re-entry TTL |
VITE_WORKBENCH_WEB_LOCAL_REENTRY_TTL_MS | Optional | 86400000 | Web runtime | Browser local re-entry TTL |
VITE_ENABLE_AGENT_GEO_MAP | Optional | true | Web runtime | Enables the geo-lock map picker |
VITE_AGENT_GEO_MAP_STYLE_URL | Optional | OpenFreeMap Bright | Web runtime | Map style URL |
VITE_AGENT_GEO_SEARCH_URL | Optional | Photon | Web runtime | Search endpoint for map places |
VITE_AGENT_GEO_SEARCH_LIMIT | Optional | 5 | Web runtime | Max search results |
VITE_AGENT_GEO_SEARCH_DEBOUNCE_MS | Optional | 350 | Web runtime | Search debounce |
VITE_DEFAULT_MAP_LAT | Optional | -1.2921 | Web runtime | Default map latitude |
VITE_DEFAULT_MAP_LNG | Optional | 36.8219 | Web runtime | Default map longitude |
VITE_PWA_INSTALL_PROMPT_AGENT_TTL_HOURS | Optional | 48 | Web runtime | Agent reminder cooldown |
VITE_PWA_INSTALL_PROMPT_ADMIN_TTL_HOURS | Optional | 336 | Web runtime | Admin reminder cooldown |
VITE_WORKBENCH_RECONNECT_DEBOUNCE_MS | Optional | 5000 | Web runtime | Workbench reconnect debounce |
VITE_WORKBENCH_SYNC_MAX_CONCURRENCY | Optional | 2 | Web runtime | Sync concurrency |
VITE_WORKBENCH_SYNC_MAX_RETRY_ATTEMPTS | Optional | 5 | Web runtime | Sync retry attempts |
VITE_WORKBENCH_SYNC_BACKOFF_BASE_MS | Optional | 2000 | Web runtime | Sync backoff base |
VITE_WORKBENCH_SYNC_BACKOFF_MAX_MS | Optional | 60000 | Web runtime | Sync backoff max |
VITE_WORKBENCH_SYNC_LOCK_TIMEOUT_MS | Optional | 120000 | Web runtime | Sync lock timeout |
Telemetry variables
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | Optional but strongly recommended when using telemetry | http://127.0.0.1:4317 | API, worker | OTLP gRPC traces and metrics endpoint |
OTEL_SAMPLING_RATIO | Optional | 1.0 | API | API trace sampling ratio |
The worker exports traces and metrics to the same OTLP endpoint, but currently does not expose a separate sampling-ratio control in its bootstrap code.
Testing-only variables
These are for integration-style and API E2E test harnesses, not normal runtime.
| Variable | Required | Default | Scope | Purpose |
|---|---|---|---|---|
INTEGRATION_DATABASE_URL | Required for integration-style suites | None | Test harness | Separate test database connection string |
INTEGRATION_REDIS_URL | Required for integration-style suites | None | Test harness | Separate Redis connection string or logical DB |
Minimal envs by scenario
Infisical-backed Dokploy bootstrap
POSTGRES_PASSWORD=change-me
REDIS_PASSWORD=change-me
INFISICAL_PROJECT_ID=your-project-id
INFISICAL_ENV=prod
INFISICAL_TOKEN_API=...
INFISICAL_TOKEN_WORKER=...
INFISICAL_TOKEN_MIGRATE=...
INFISICAL_TOKEN_TOOLS=...All normal application secrets and URLs live in Infisical for this path.
Non-Infisical compose bootstrap
SKIP_INFISICAL=true
POSTGRES_PASSWORD=change-me
REDIS_PASSWORD=change-me
DATABASE_URL=postgresql://remoteeaze:change-me@postgres:5432/remote_eaze
REDIS_URL=redis://:change-me@redis:6379
BETTER_AUTH_SECRET=change-me-minimum-32-chars
BETTER_AUTH_URL=https://api.example.com
ENCRYPTION_KEY=change-me-minimum-32-chars
ENCRYPTION_SALT=change-me-minimum-16-chars
LICENSE_SECRET_KEY=change-me-minimum-32-chars
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=noreply@example.com
FRONTEND_URL=https://remote-eaze.example.com
STORAGE_ENDPOINT=https://storage.example.com
STORAGE_BUCKET=remote-eaze
STORAGE_ACCESS_KEY=...
STORAGE_SECRET_KEY=...This is only the smallest practical starting point. In a real raw-env deployment, the api, worker, tools, and migrate services all rely on the same broader runtime configuration documented on this page.
Use the deployment-mode pages for the smaller, path-specific excerpts.