Configuration and secrets

Your settings are kept in the private .env file. For basic Docker Compose, .env and compose.yaml sit together in lunarpaper. The HTTPS guide keeps its Compose files in lunarpaper/release. If you used docker run, they are in the block of settings you saved during installation. For what each variable does, see Environment variables.

Keep secrets safe

• Back up .env together with your data. Several of its keys decrypt stored data, and without them that data cannot be read.
• Never commit .env, paste it into a support request, or share the output of docker compose config, which prints every secret.
• Never change a generated value after the first start.

Changing a value

The commands below use the basic HTTP installation. For HTTPS, replace docker compose with docker compose --project-name lunarpaper --env-file .env -f release/compose.yaml -f release/compose.https.yaml. After you edit .env, run docker compose up -d --wait. A plain restart does not read .env again. With docker run, remove the container and run its command again.

Some values have side effects when you change them:

• SESSION_SECRET: everyone is signed out.
• ENCRYPTION_KEY, DATA_SOURCE_ENCRYPTION_KEY, MFA_ENCRYPTION_KEY: data already encrypted with the old key can no longer be read.
• AI_, SSO_, EMAIL_, ADDRESS_PROVIDER_, WORKFLOW_CREDENTIAL_ and PUBLISHER_CREDENTIAL_ENCRYPTION_KEY: you have to enter the credentials they protect again.
• FORM_FILE_ENCRYPTION_KEYS: add a new key ID instead of replacing v1, and keep old IDs until their files are gone.
• PGPASSWORD, APP_PLATFORM_PASSWORD, APP_INTAKE_PASSWORD: changing them in .env does not change the password in the database, so Lunar Paper can no longer connect.
• REDIS_PASSWORD and INTERNAL_API_TOKEN: every service must get the new value at the same time.

Generate a value

On Linux or macOS, run openssl rand -hex 32. In PowerShell, run:

$b = New-Object byte[] 32; [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); ([BitConverter]::ToString($b) -replace '-', '').ToLower()

Both commands produce hexadecimal values. Use hexadecimal for database and Redis passwords, because characters such as @, :, / and # break the connection addresses.

If an upgrade reports that a setting “is missing a value”, the new version has added a variable. Generate a value, add it to .env, and run docker compose up -d --wait.

Setup key

You need SETUP_KEY to unlock initial guided setup and database upgrades. Keep a copy in your password manager.

On the maintenance screen, select Administrator? Unlock setup and enter the key. Setup stays unlocked for one hour, and it only works at the exact APP_URL address. See Complete the database upgrade.

If you lose the key, generate a new value, put it in SETUP_KEY, and run docker compose up -d --wait. This does not affect any passwords or encryption keys.

Address and cookies

APP_URL must match the address in the browser exactly, including http:// or https://, the host name and the port. It must not include a path or end with a slash.

• With an https:// address, Lunar Paper marks its cookies as Secure. With http://, it does not.
• Microsoft and Google sign-in build their callback addresses from APP_URL, so set it before you connect them.
• If Lunar Paper is behind your own proxy, set TRUST_PROXY_HOPS to the number of proxies in front of it. See Use your own reverse proxy.

More than one instance on the same server address

Browsers share cookies between ports on the same address. If you run a second installation on the same host name or IP address:

• add a unique COOKIE_NAMESPACE to its .env, such as COOKIE_NAMESPACE=paper_test (1 to 32 letters, numbers, _ or -). Keep it stable, because changing it signs everyone out;
• give it its own folder, ports, and Compose project name, such as --project-name lunarpaper-test. Keep that name on every command.

Database sizing

Each Lunar Paper container opens two pools of up to DB_POOL_MAX database connections. The defaults are 40 connections per pool and max_connections=200 in PostgreSQL, which leaves room for upgrades and administrator sessions. A separate worker container opens two more pools. See Scaling with process roles.

Outbound proxy that inspects TLS

If your network sends outbound traffic through a proxy that inspects TLS, Lunar Paper needs to trust that proxy’s certificate. Mount the proxy’s PEM root certificate into the lunarpaper container, and set NODE_EXTRA_CA_CERTS to the certificate’s path inside the container. See Network proxy administration.

If an external publisher calls back to a main application on a private network, set Form Publisher callbacks → Direct in Administration → Network → Proxy Configuration, unless the forward proxy is configured to reach that private address. This per-service setting also applies in All services mode. See External publisher callbacks on a private network for setup and troubleshooting.

Address lookup

Address autocomplete in the form builder is off by default. To turn it on, choose a provider on each address field:

Provider	What it needs
None	Nothing. The default.
Self-hosted	Your own Nominatim or Photon server
Google Places	An API key under Administration → Integrations → Address Providers
Mapbox	An access token in the same place

For self-hosted lookup, add ADDRESS_SELF_HOSTED_NOMINATIM_URL: ${ADDRESS_SELF_HOSTED_NOMINATIM_URL} to the lunarpaper service’s environment in your Compose file, set the value in .env (for example http://nominatim:8080), and run docker compose up -d --wait. If the server is on a private network, also allow its host under Administration → Network → Private Targets.

The Nominatim (OpenStreetMap) option uses the public OpenStreetMap server. Its usage policy forbids production use, so use it only for testing.

Results based on OpenStreetMap are published under the Open Database License, and Lunar Paper shows the required credit. Lunar Paper does not request any map tiles.