Configuration
"Configuration" throughout the documentation and codebase refers to these variables which are statically set when the process launches. Changing them requires a restart, however they don't need to be changed much once set.
Configuration is done via environment variables. The following variables are available:
Core parameters
These settings are necessary to customise for pretty much all production installations.
PRODUCTION
default:
false
Used for logging and switching some behaviour to use mocks instead of real services.
When true:
- logs will be output in JSON.
- emails will be sent instead of logged.
- SMS messages will be sent instead of logged.
DATABASE_URL
default: a SQLite file located at
./data/data.db
This specifies the primary database Storyden will persist all its main data in. It can accept Postgres or SQLite URL-style strings.
LISTEN_ADDR
default:
0.0.0.0:8000
The interface bind address. Usually you won't ever need to change this.
PUBLIC_API_ADDRESS
default:
http://localhost:8000
This is important as it affects the ability for users to authenticate. It's used for both cookies and WebAuthn.
The hostname part of this URL is used to set the Domain attribute on cookies. This is important for security and privacy reasons. If you're running Storyden on a subdomain, you should set this to the full domain including the subdomain.
Warning: Changing this will break WebAuthn/Passkey sessions. There's a planned workaround coming but currently it's not recommended you switch domains if you allow users to authenticate with WebAuthn/Passkey.
PUBLIC_WEB_ADDRESS
default:
http://localhost:3000
The public address for the frontend application. Change this to your production frontend URL with which you access the web application from via a browser. In production it should not have a port number and should use https.
SESSION_KEY
default:
0000000000000000
An encryption key for secure cookies. Do not leave this as the default value for production installations. Changing this value will invalidate all active sessions.
Changing the session key will invalidate all existing sessions and force all users to log in again. It's best to set this once and only change it if you believe the key has been compromised.
Optional
ASSET_STORAGE_TYPE
default: empty string - local filesystem storage
When unset, all persistent storage of files (avatars, uploads, assets, etc) will use the local filesystem.
When set to s3, the other S3_ prefixed variables are required and all persistent storage of files will use S3.
ASSET_STORAGE_LOCAL_PATH
When ASSET_STORAGE_TYPE specifies local file storage, this variable controls where the files are stored.
S3 Configuration
The following variables are required when ASSET_STORAGE_TYPE is set to s3.
S3_ENDPOINTS3_BUCKETS3_REGIONS3_ACCESS_KEYS3_SECRET_KEY
Internal
These are often used during development of Storyden itself, plugins or frontends and rarely need to be set by end-users.
LOG_LEVEL
default:
info
See zapcore.Level (opens in a new tab).
RUN_FRONTEND
default: (empty)
Internal or advanced use only. A directory path that, when non-empty, be used to run the frontend Next.js app from.
The all-in-one Docker image uses this to ensure the frontend process is a child process of the backend process and they start/stop together. If you're self-hosting outside of Docker, you should not need to use this because it's simpler to use your preferred job management solution (such as systemd) to manage both processes independently.