Skip to content

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

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.

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.

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.

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.

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.

debug, info, warn or error. Default: info.

text or json. Default: text. Use json when logs are collected by a log aggregator.

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.

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.

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.

Client ID of the application registered at the provider. Required when SERVICE_OIDC_ISSUER is set.

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.

Text on the login button, which reads “Log in with …”. Default: SSO. Use the name your users know, for example Authentik or Company account.

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.

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.

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.