Production boot checks

The configuration problems that make the application refuse to start in production, and how to fix each one.

For: Administrators troubleshooting a deployment that will not start · Last updated

When the app container starts with WI_ENV=prod (which the compose file sets), it checks its own configuration before it serves anything. If any check fails, it stops with the message Refusing to boot with invalid configuration: followed by every problem it found. The container then restarts and fails again until you fix .env.

Read the message with:

sudo docker compose -p wi-prod logs app

What it checks#

Problem reported What to do
WI_MASTER_KEY is unset Provide the master key in .env. If this is an existing deployment, restore the original value. See Master key custody. This check applies in every environment.
WI_MASTER_KEY is not valid base64, or WI_MASTER_KEY must decode to 16, 24 or 32 bytes The key is malformed. Restore the original value from your backup. A new key is openssl rand -base64 32, but only use one by following Rotate the master key. The same checks apply to WI_MASTER_KEY_OLD. This check applies in every environment.
WI_MASTER_KEY_OLD is set but WI_MASTER_KEY is not During a rotation WI_MASTER_KEY holds the new key and WI_MASTER_KEY_OLD the previous one. Set both, or remove WI_MASTER_KEY_OLD if you are not rotating.
WI_MASTER_KEY_OLD is the same key as WI_MASTER_KEY Set WI_MASTER_KEY to the new key, or remove WI_MASTER_KEY_OLD if no rotation is in progress.
WI_DOMAIN is unset Add WI_DOMAIN=<your domain> to .env. Every public address (the web origin, emailed-link, webhook, and deployed-App URLs, and the Dokku SSH host) is derived from it. With no domain, set WI_ALLOWED_ORIGIN=http://<your-ip> instead.
WI_CENTRAL_URL ... must use https WI_CENTRAL_URL is the address of the Radial documentation and relay service. It is optional and defaults to https://workforceintelligenceinc.com. In production it must be an https:// address. Remove the line from .env to use the default, or set a valid https:// address.

The production checks also reject test-only settings: the fake drivers for inference, infrastructure, deployment, updates, email, trigger scheduling, crawling, SharePoint, outside-system sign-in (WI_OAUTH_PROVIDER_DRIVER) and outside-system tools (WI_CONNECTION_BROKER_DRIVER), and the ephemeral identity signing mode. The compose file does not select any of them, so you meet these checks only if you add such a variable to .env. Remove it.

Key mismatch with the database#

After the configuration checks pass, the application unlocks your company's data key with WI_MASTER_KEY (or, during a rotation, WI_MASTER_KEY_OLD). In production it stops when neither key matches. The log says that the data key was wrapped by a master key with a given fingerprint and lists the fingerprints of the keys you configured. Set WI_MASTER_KEY to the key with the stored fingerprint, or during a rotation set that key as WI_MASTER_KEY_OLD, then run cd /opt/wi && sudo docker compose -f docker-compose.prod.yml up -d. Never generate a fresh key to get past this error. See Master key custody.

The same check runs on the first boot of a company that already holds stored credentials but has no data key yet, such as the first start of an existing installation on this version, or a database restored from a snapshot taken before that. Before it creates the data key, the application tries to open an existing stored credential with WI_MASTER_KEY and with WI_MASTER_KEY_OLD. If none opens, production stops with an error naming the fingerprints of the configured keys, and nothing is written to the database. Set WI_MASTER_KEY to the key the credentials were stored under, or set that key as WI_MASTER_KEY_OLD, and start again.

Once the data key exists, a stored credential that neither configured key can open does not stop the application. Settings, Administration, Secrets, Manage, Encryption keys reports "WI_MASTER_KEY is correct, but some stored credentials can't be opened." and lists the credentials that need to be entered again.

Compose's own checks#

Docker Compose also refuses to start the stack, before any container runs, when WI_MASTER_KEY, or WI_SESSION_SECRET is missing. The error names the variable. The usual cause is running docker compose from a directory that does not contain .env, or a .env that lacks the line.

See Configuration reference for every value.