Configuration
nimap is configured with environment variables, set in the environment section of compose.yaml (see Installation). After changing them, apply the change with docker compose up -d.
| Variable | Default | Description |
|---|---|---|
SERVICE_DATABASE_URL |
required | PostgreSQL connection string |
SERVICE_ENV |
production |
Runtime environment |
SERVICE_PORT |
8080 |
HTTP port inside the container |
SERVICE_MEDIA_DIR |
./data/media |
Directory for uploaded files |
SERVICE_AUTO_MIGRATE |
true |
Update the database schema on start |
SERVICE_LOG_LEVEL |
info |
How much to log |
SERVICE_LOG_FORMAT |
text |
Log format |
SERVICE_BASE_URL |
— | Public URL of the instance |
SERVICE_OIDC_ISSUER |
— | OIDC provider; empty disables single sign-on |
SERVICE_OIDC_CLIENT_ID |
— | OIDC client ID |
SERVICE_OIDC_CLIENT_SECRET |
— | OIDC client secret |
SERVICE_OIDC_NAME |
SSO |
Name on the login button |
SERVICE_OIDC_SCOPES |
openid,email,profile |
Scopes requested from the provider |
SERVICE_OIDC_ALLOWED_DOMAINS |
— | Email domains allowed to sign up |
SERVICE_OIDC_LINK_BY_EMAIL |
true |
Link a first login to an existing user by email |
SERVICE_DATABASE_URL
Section titled “SERVICE_DATABASE_URL”Connection string for PostgreSQL 18 with PostGIS, in the form postgres://user:password@host:port/database?sslmode=disable. nimap does not start without it. Special characters in the password must be URL-encoded.
Use sslmode=require when the database runs on another machine.
SERVICE_ENV
Section titled “SERVICE_ENV”production or development. Default: production.
In production the session cookie is marked as secure and browsers only send it over HTTPS. Over plain HTTP the browser drops the session cookie, so signing in does not work. http://localhost is the exception, because browsers treat it as secure.
Use development only for trying nimap out on a local network without HTTPS.
SERVICE_PORT
Section titled “SERVICE_PORT”Port nimap listens on inside the container, 1–65535. Default: 8080.
To expose nimap on a different port on the host, change only the left side of ports in compose.yaml, for example "80:8080". If you change SERVICE_PORT, update the right side of ports and the port in the healthcheck too.
SERVICE_MEDIA_DIR
Section titled “SERVICE_MEDIA_DIR”Directory for uploaded photos, documents and generated thumbnails. Default: ./data/media. In the Compose installation it is /data/media, backed by the media volume.
The directory must be writable by the container user (1001). If it is not, nimap stops on start with media directory is not writable. A new Docker volume gets the right owner automatically; a directory mounted from the host has to be owned by 1001.
Back it up together with the database, as the database only references the files.
SERVICE_AUTO_MIGRATE
Section titled “SERVICE_AUTO_MIGRATE”true or false. Default: true.
When enabled, nimap brings the database schema up to date on every start, including after an update to a newer image. Turn it off only if you want to run migrations manually with /nimap migrate up.
SERVICE_LOG_LEVEL
Section titled “SERVICE_LOG_LEVEL”debug, info, warn or error. Default: info.
SERVICE_LOG_FORMAT
Section titled “SERVICE_LOG_FORMAT”text or json. Default: text. Use json when logs are collected by a log aggregator.
SERVICE_BASE_URL
Section titled “SERVICE_BASE_URL”The address users open nimap at, for example https://nimap.example.com. Required when single sign-on is enabled, optional otherwise.
It has to be an absolute URL without a query or fragment. It has to use https, unless SERVICE_ENV is development. A trailing slash does not matter. If nimap runs under a path, include it: https://example.com/nimap.
The OIDC redirect URI is derived from it as SERVICE_BASE_URL + /api/auth/oidc/callback. Behind a reverse proxy use the public address, not the internal one.
Single sign-on
Section titled “Single sign-on”The SERVICE_OIDC_* variables connect nimap to an OpenID Connect provider such as Authentik, Keycloak, Microsoft Entra ID or Google. Setting up the provider and how accounts are linked is described in Single sign-on.
If any of them is invalid, nimap does not start and says which one. If the provider cannot be reached on start, nimap starts anyway with password login only and logs single sign-on disabled.
SERVICE_OIDC_ISSUER
Section titled “SERVICE_OIDC_ISSUER”Issuer URL of the provider, for example https://auth.example.com/application/o/nimap/. nimap reads /.well-known/openid-configuration under it. It has to match the issuer the provider publishes there exactly, trailing slash included.
Empty, the default, disables single sign-on. It has to use https, unless SERVICE_ENV is development.
SERVICE_OIDC_CLIENT_ID
Section titled “SERVICE_OIDC_CLIENT_ID”Client ID of the application registered at the provider. Required when SERVICE_OIDC_ISSUER is set.
SERVICE_OIDC_CLIENT_SECRET
Section titled “SERVICE_OIDC_CLIENT_SECRET”Client secret of that application. Required when SERVICE_OIDC_ISSUER is set. nimap is a confidential client, so the provider has to issue a secret.
SERVICE_OIDC_NAME
Section titled “SERVICE_OIDC_NAME”Text on the login button, which reads “Log in with …”. Default: SSO. Use the name your users know, for example Authentik or Company account.
SERVICE_OIDC_SCOPES
Section titled “SERVICE_OIDC_SCOPES”Comma-separated scopes requested from the provider. Default: openid,email,profile. It has to include openid. nimap needs the email, so keep email unless the provider sends it some other way.
SERVICE_OIDC_ALLOWED_DOMAINS
Section titled “SERVICE_OIDC_ALLOWED_DOMAINS”Comma-separated email domains whose users may get a new account on their first login, for example example.com,example.org. Case does not matter, but each domain is matched exactly: example.com does not allow sub.example.com.
Empty, the default, allows anyone the provider lets in. The list only limits new accounts; users who are already linked, or get linked by email, log in regardless of their domain.
SERVICE_OIDC_LINK_BY_EMAIL
Section titled “SERVICE_OIDC_LINK_BY_EMAIL”true or false. Default: true.
When enabled, the first single sign-on login of someone whose email already belongs to a nimap user is linked to that user, but only if the provider marks the email as verified (email_verified). When disabled, or when the email is not verified, such a login is refused.
Only enable it if you trust the provider’s emails: whoever controls an email at the provider gets into the nimap account with that email.