Environment Variables
Environment variables are now reserved for container wiring, process bootstrap, and backward compatibility. For a current self-hosted installation, put application settings in config/config.json or edit supported settings in the Admin Panel.
The official ​Docker Compose [Recommended] deployment does not require a user-created
.envfile.
Configuration sources
Use ​Configuration as the primary guide.
-
config/config.jsonis the recommended source for server, mail, storage, indexer, and other application settings. -
Settings saved in the Admin Panel are stored in the database.
-
Environment aliases are read during process startup. They are retained for compatibility, but should not be the primary application configuration source.
Database connection
DATABASE_URL is the supported database bootstrap variable:
The official Compose file sets it internally, so normal users do not need to configure it.
For a custom deployment:
-
Provide the complete
DATABASE_URLto the application and migration processes. -
URL-encode special characters in the username or password.
-
Do not also configure
db.datasourceUrlwith a different value. Native and Node processes can otherwise connect to different databases. -
Do not change the database connection from the Admin Panel. It is a startup dependency and requires a controlled restart/migration procedure.
The following are obsolete Compose-template variables, not AFFiNE server configuration:
| Obsolete variable | Current replacement |
|---|---|
| DB_USERNAME | Put the username in DATABASE_URL for a custom deployment |
| DB_PASSWORD | Put a URL-encoded password in DATABASE_URL for a custom deployment |
| DB_DATABASE | Put the database name in DATABASE_URL for a custom deployment |
Redis connection
The following variables remain supported for custom infrastructure deployments. The official Compose file supplies the required Redis host internally.
| Variable | Default | Description |
|---|---|---|
| REDIS_SERVER_HOST | localhost | Redis host |
| REDIS_SERVER_PORT | 6379 | Redis port |
| REDIS_SERVER_USERNAME | empty | Redis username |
| REDIS_SERVER_PASSWORD | empty | Redis password |
| REDIS_SERVER_DATABASE | 0 | First Redis database index; AFFiNE uses this index and the next four |
For a long-lived deployment, prefer the equivalent redis section in config.json unless the orchestration platform owns these connection values.
Process networking
These variables control where the server process listens. They do not replace the public URL configuration.
| Variable | Default | Description |
|---|---|---|
| LISTEN_ADDR | 0.0.0.0 | Address the server process listens on |
| AFFINE_SERVER_PORT | 3010 | Port inside the application container |
Set the public URL with server.externalUrl in config.json. Do not use AFFINE_SERVER_PORT to change only the host-side Docker port; edit the Compose port mapping instead.
Compatibility aliases
These aliases are still parsed by the Node configuration layer, but new self-hosted deployments should use the listed config.json keys.
Server and mail
| Environment alias | config.json key |
|---|---|
| AFFINE_SERVER_EXTERNAL_URL | server.externalUrl |
| AFFINE_SERVER_HTTPS | server.https |
| AFFINE_SERVER_HOST | server.host |
| AFFINE_SERVER_SUB_PATH | server.path |
| MAILER_SERVERNAME | mailer.SMTP.name |
| MAILER_HOST | mailer.SMTP.host |
| MAILER_PORT | mailer.SMTP.port |
| MAILER_USER | mailer.SMTP.username |
| MAILER_PASSWORD | mailer.SMTP.password |
| MAILER_SENDER | mailer.SMTP.sender |
| MAILER_IGNORE_TLS | mailer.SMTP.ignoreTLS |
Indexer and managed services
| Environment alias | config.json key |
|---|---|
| AFFINE_INDEXER_ENABLED | indexer.enabled |
| AFFINE_INDEXER_SEARCH_PROVIDER | indexer.provider.type |
| AFFINE_INDEXER_SEARCH_ENDPOINT | indexer.provider.endpoint |
| AFFINE_INDEXER_SEARCH_API_KEY | indexer.provider.apiKey |
| AFFINE_INDEXER_SEARCH_USERNAME | indexer.provider.username |
| AFFINE_INDEXER_SEARCH_PASSWORD | indexer.provider.password |
| DOC_SERVICE_ENDPOINT | docService.endpoint |
| GA4_MEASUREMENT_ID | telemetry.ga4.measurementId |
| GA4_API_SECRET | telemetry.ga4.apiSecret |
Changes made through environment aliases require a container restart.
Removed legacy Compose variables
The current official Compose file no longer reads these variables:
| Removed variable | Current behavior |
|---|---|
| AFFINE_REVISION | The release Compose file specifies the image tag directly |
| PORT | Edit the Compose host port mapping if needed |
| DB_DATA_LOCATION | PostgreSQL data is stored at ./data/postgres |
| UPLOAD_LOCATION | Uploaded files are stored at ./data/storage |
| CONFIG_LOCATION | Configuration is stored at ./config |
| DB_USERNAME, DB_PASSWORD, DB_DATABASE | The Compose network uses its internal database connection; custom deployments use DATABASE_URL |
Do not copy these variables into a new .env file. Existing installations that still use an older Compose file should keep their matching legacy .env until they complete a backed-up migration.
Private key
Do not normally set AFFINE_PRIVATE_KEY. The self-host pre-deploy step creates and persists config/private.key automatically. Keep that file backed up and private; replacing it can invalidate encrypted or signed data.
Environment variables not documented on this page may be internal build, test, or managed-deployment controls and are not a stable self-host configuration interface.