Skip to main content

Configuration reference

An on-premises install of Nadigit IMS is described by its .env file, which the installer (install.sh or install.ps1) writes from .env.template. This page describes its 69 variables: what each one does, where its value comes from, which services read it, and what happens when it is wrong.

Each variable has a kind, which says who decides its value:

KindWho sets the valueChanging it
Asked at installthe operator, during the installre-run the installer and answer differently
Derivedthe installer, from the asked valuesnever by hand: re-run the installer
Generated secretthe installer, oncenever: see the warning below
Fixed by the releasethe installed releaseonly when Nadigit support says so
Database passwords are not changed in .env

PostgreSQL initialises a volume only once. A new value for POSTGRES_NADIGIT_IMS_PASSWORD or POSTGRES_KC_PASSWORD is not applied to the existing database: the application or Keycloak is locked out of its own data. The installer always reuses the secrets already in .env.

When the install bundle provides the diagnosis, install.sh --doctor (or install.ps1 -Doctor) compares the live .env with this reference; every check it reports is explained in TROUBLESHOOTING.md, shipped with the install.

Contents​

Primitives​

PUBLIC_PROTOCOL​

  • Kind: Asked at install
  • Where: .env
  • Read by: keycloak, the installer

What it does. Scheme browsers use to reach this install: https, or http only behind a TLS terminator the customer runs.

When it is wrong. Every derived URL is built from it. Wrong here, Keycloak redirects and the issuer check fail together and no one can log in.

PUBLIC_HOST​

  • Kind: Asked at install
  • Where: .env
  • Read by: keycloak, the installer, nginx (vhost)

What it does. Hostname (optionally host:port) browsers use to reach the install. Must resolve to this host from client machines.

When it is wrong. The most coupled value there is: issuer, JWKS, CORS, the console API host, the nginx server_name and the certificate path all derive from it. A mismatch surfaces as UserInfo 401 at login, nowhere near the cause.

TZ​

  • Kind: Asked at install
  • Where: .env
  • Read by: certbot, keycloak, nadigit-ims-console, nadigit-ims-services, postgres_kc_db, postgres_nadigit_ims_db, reverse-proxy

What it does. IANA timezone applied to every container, for example Africa/Casablanca.

When it is wrong. Document dates, report periods and scheduled jobs shift by the offset. Token validation is unaffected; it runs in UTC.

Several installs on one host​

IMS_INSTANCE​

  • Kind: Asked at install
  • Where: .env
  • Optional: yes, an empty value is valid
  • Read by: certbot, keycloak, nadigit-ims-console, nadigit-ims-services, postgres_kc_db, postgres_nadigit_ims_db, reverse-proxy, the installer

What it does. Short name of this install when several share one host (lowercase letters and digits, starting with a letter). Prefixes every container name and the two database volume names. Empty on a single install.

When it is wrong. Changed on an existing install, Compose creates new empty database volumes and the application starts on a blank database. Two installs with the same value on one host share their databases.

IMS_HTTP_PORT​

  • Kind: Asked at install
  • Where: .env
  • Read by: reverse-proxy, the installer

What it does. Host side of the reverse proxy's HTTP port: 80 on a single install, a loopback address and port such as 127.0.0.1:8081 behind the edge proxy.

When it is wrong. Already taken, the stack does not start. Not reachable from the edge proxy, certificate issuance and renewal fail for this install.

IMS_HTTPS_PORT​

  • Kind: Asked at install
  • Where: .env
  • Read by: reverse-proxy, the installer

What it does. Host side of the reverse proxy's HTTPS port: 443 on a single install, a loopback address and port such as 127.0.0.1:8444 behind the edge proxy.

When it is wrong. Already taken, the stack does not start. Published on all addresses behind the edge proxy, clients can bypass the edge and reach a listener that expects the PROXY protocol, and get a broken connection.

IMS_BEHIND_EDGE​

  • Kind: Asked at install
  • Where: .env
  • Read by: the installer, nginx (vhost)

What it does. true when the host's edge proxy (deploy/edge) owns ports 80 and 443 and forwards this install's hostname to it. The HTTPS listener then expects the PROXY protocol.

When it is wrong. true without the edge proxy in front, every HTTPS connection fails. false behind it, every HTTPS connection fails as well, and the admin allowlist sees the edge's address instead of the client's.

IMS_KEYCLOAK_CPUS​

  • Kind: Derived
  • Derived from: the host's CPU count, capped at 1.5
  • Where: .env
  • Read by: keycloak, the installer

What it does. CPU share Keycloak may use. Docker refuses a value above the host's CPU count, so the installer writes the host's count capped at 1.5.

When it is wrong. Higher than the host's CPU count, Keycloak cannot be created at all and the stack fails to start. Very low, and logins slow down under load.

IMS_SERVICES_MEM​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services, the installer

What it does. Memory ceiling for the application container. The heap is a percentage of it (IMS_JAVA_OPTS), so lowering this lowers the heap with it. 1536m suits one install on a 4 GB host; 1024m is the floor for a shared host.

When it is wrong. Too low, the JVM is killed mid-request and the container restarts. Too high on a shared host, the kernel kills another install's database instead.

IMS_KEYCLOAK_MEM​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: keycloak, the installer

What it does. Memory ceiling for Keycloak. 768m suits one install; 512m works on a shared host, with slower first boots.

When it is wrong. Too low, Keycloak is killed during its first boot and no one can log in.

IMS_POSTGRES_MEM​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: postgres_kc_db, postgres_nadigit_ims_db, the installer

What it does. Memory ceiling for each of the two databases. 512m suits one install; 256m works on a shared host with this data size.

When it is wrong. Too low, the database is killed under a large report or import and the application loses its connection.

IMS_CONSOLE_MEM​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-console, the installer

What it does. Memory ceiling for the console's web server. It serves static files; 64m is enough on a shared host.

When it is wrong. Too low, the console answers 502 while the application is healthy.

Images​

IMS_SERVICES_IMAGE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services, the installer

What it does. Application image tag. Stamped to the bundle version by make-bundle.sh; never edited by hand, never :latest.

When it is wrong. A tag the host does not have fails the first start. An untagged name makes rollback impossible and lets docker load replace a running version silently.

IMS_CONSOLE_IMAGE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-console, the installer

What it does. Console image tag. Stamped to the bundle version by make-bundle.sh; never edited by hand, never :latest.

When it is wrong. Same as the application image: a missing tag fails the first start, an untagged one makes rollback impossible.

KEYCLOAK_IMAGE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: keycloak

What it does. Keycloak image, pinned.

When it is wrong. Keycloak refuses to start against a database migrated by a newer version, so raising this is one-way without a backup.

NGINX_IMAGE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: reverse-proxy

What it does. Reverse proxy image, pinned.

When it is wrong. Low. A different nginx major can change directive behaviour the vhost relies on.

CERTBOT_IMAGE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: certbot

What it does. Certificate renewal image, pinned.

When it is wrong. If its container cannot start, renewals stop silently and the certificate expires 90 days after issue (doctor TLS-05).

Web console​

ANGULAR_API_PROTOCOL​

  • Kind: Derived
  • Derived from: PUBLIC_PROTOCOL
  • Where: .env
  • Read by: nadigit-ims-console, nadigit-ims-services

What it does. Scheme the console uses for API calls.

When it is wrong. Mixed-content blocking: the console loads but the browser refuses every API call.

ANGULAR_API_HOST​

  • Kind: Derived
  • Derived from: PUBLIC_HOST
  • Where: .env
  • Read by: nadigit-ims-console, nadigit-ims-services

What it does. Host the browser uses to reach the API. Must be reachable from client machines; localhost only works when the browser runs on the server.

When it is wrong. Console loads but every API call fails.

ANGULAR_API_PORT​

  • Kind: Derived
  • Derived from: 443 when PUBLIC_PROTOCOL is https, otherwise 80
  • Where: .env
  • Read by: nadigit-ims-console, nadigit-ims-services

What it does. Port the console uses for API calls. Keep it explicit behind a proxy.

When it is wrong. An EMPTY value becomes 8090 through the console entrypoint default, so the console calls https://host:8090/api and nothing answers.

ANGULAR_KC_HOST​

  • Kind: Derived
  • Derived from: PUBLIC_HOST
  • Where: .env
  • Read by: nadigit-ims-console

What it does. Host the console sends users to for login.

When it is wrong. Login redirects to a host users cannot reach.

ANGULAR_KC_PORT​

  • Kind: Derived
  • Derived from: 443 when PUBLIC_PROTOCOL is https, otherwise 80
  • Where: .env
  • Read by: nadigit-ims-console

What it does. Port the console sends users to for login.

When it is wrong. Login redirects to a port nothing listens on.

Keycloak​

KEYCLOAK_REALM_NAME​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-console, the installer

What it does. Realm the application authenticates against. Created on first boot when missing.

When it is wrong. Changed after install, the application looks at an empty realm and every existing user disappears from its view.

KEYCLOAK_CLIENT_ID​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-console

What it does. Public client the console logs in through. Provisioned by the bootstrap.

When it is wrong. Login fails with client not found.

KEYCLOAK_ADMIN​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: keycloak, nadigit-ims-services, the installer

What it does. Keycloak master-realm administrator name: kcadmin, unless an existing .env already names another, which the launcher keeps.

When it is wrong. Changed after first boot it does not rename the existing administrator, so the bootstrap loses Admin API access.

KEYCLOAK_ADMIN_PASSWORD​

  • Kind: Generated secret
  • Where: .env
  • Read by: keycloak, nadigit-ims-services, the installer

What it does. Keycloak master-realm administrator password. Generated once and reused on every re-run.

When it is wrong. Changing it in .env alone does not change it in Keycloak: the bootstrap can no longer reach the Admin API.

KEYCLOAK_ISSUER_URI​

  • Kind: Derived
  • Derived from: PUBLIC_PROTOCOL://PUBLIC_HOST/realms/KEYCLOAK_REALM_NAME
  • Where: .env
  • Read by: nadigit-ims-services, the installer

What it does. Token issuer as the BROWSER sees it. The API validates the iss claim of every token against it.

When it is wrong. Any mismatch with what Keycloak advertises rejects every login: the classic UserInfo 401 (doctor KC-01, CFG-07).

KEYCLOAK_JWKS_URI​

  • Kind: Derived
  • Derived from: PUBLIC_PROTOCOL://PUBLIC_HOST/realms/KEYCLOAK_REALM_NAME/protocol/openid-connect/certs
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Where the API fetches Keycloak signing keys, from inside its own container.

When it is wrong. If the public hostname does not resolve from inside the container (split-horizon DNS, NAT without hairpin), key retrieval fails and every authenticated call answers 401 while pages still render. The local e2e stack points it at http://keycloak:8080 for that reason.

First-boot Keycloak provisioning​

IMS_KEYCLOAK_BOOTSTRAP_ENABLED​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Master switch for first-boot Keycloak provisioning: realm, clients, user profile, first administrator.

When it is wrong. Off on a fresh install: no realm, no clients, nobody can log in.

IMS_KEYCLOAK_USER_PROVISIONING_ENABLED​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Lets the application create Keycloak users when staff are added in the console.

When it is wrong. Off: staff created in the console cannot log in.

IMS_KEYCLOAK_BOOTSTRAP_FORCE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Re-runs every bootstrap phase regardless of its applied marker. Leave false once provisioned.

When it is wrong. Left true, every restart re-applies clients, theme and user profile over changes made in the Keycloak admin console.

IMS_KEYCLOAK_BOOTSTRAP_REALM_CREATE_IF_MISSING​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Creates the realm named by the issuer when Keycloak has none.

When it is wrong. Off on a fresh install: the bootstrap stops at its first phase.

IMS_KEYCLOAK_ADMIN_CLIENT_ID​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Confidential client the application uses to call the Keycloak Admin API.

When it is wrong. User provisioning and role management fail with 401 from Keycloak.

KEYCLOAK_IMS_ADMIN_CLIENT_SECRET​

  • Kind: Generated secret
  • Where: .env
  • Read by: nadigit-ims-services, the installer

What it does. Secret of the confidential admin client. Generated once and reused on every re-run.

When it is wrong. Out of step with Keycloak, user provisioning and role management fail.

IMS_KEYCLOAK_BOOTSTRAP_USER_PROFILE_ENABLED​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Applies the declarative user profile, including the custom attributes the application reads.

When it is wrong. Off: Keycloak rejects the user attributes the application writes.

IMS_KEYCLOAK_BOOTSTRAP_USER_PROFILE_APPLY_ONCE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Applies the user profile only while its marker is absent.

When it is wrong. False: every restart re-applies it over manual edits.

IMS_KEYCLOAK_BOOTSTRAP_LOGIN_THEME_ENABLED​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Applies the branded login theme to the realm.

When it is wrong. Off: users see the stock Keycloak login page.

IMS_KEYCLOAK_BOOTSTRAP_LOGIN_THEME_NAME​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Name of the theme directory shipped in keycloak-theme/.

When it is wrong. A name with no matching directory makes Keycloak fall back to its default theme.

IMS_KEYCLOAK_BOOTSTRAP_SPA_CLIENT_ENABLED​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Provisions the console public client with its redirect URIs and web origins.

When it is wrong. Off on a fresh install: login fails with an invalid redirect URI.

IMS_KEYCLOAK_BOOTSTRAP_SPA_CLIENT_ORIGINS​

  • Kind: Fixed by the release
  • Where: .env
  • Optional: yes, an empty value is valid
  • Read by: nadigit-ims-services

What it does. Extra origins for the console client. Empty means CORS_ALLOWED_ORIGINS; set it only to widen, for example a second hostname during a DNS migration.

When it is wrong. A served hostname missing from both this list and CORS_ALLOWED_ORIGINS cannot log in. An extra origin nobody serves is harmless.

IMS_KEYCLOAK_BOOTSTRAP_SPA_CLIENT_APPLY_ONCE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Applies the console client only while its marker is absent.

When it is wrong. False: every restart resets redirect URIs edited in the admin console.

IMS_KEYCLOAK_BOOTSTRAP_SPA_CLIENT_FORCE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Re-applies the console client for one start even when its marker exists.

When it is wrong. Left true, it overwrites redirect URIs on every restart.

IMS_KEYCLOAK_BOOTSTRAP_INITIAL_ADMIN_ENABLED​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Creates the first application administrator when none exists.

When it is wrong. Off on a fresh install: the realm has no user who can log in to the console.

IMS_BOOTSTRAP_ADMIN_USERNAME​

  • Kind: Asked at install
  • Where: .env
  • Optional: yes, an empty value is valid
  • Read by: nadigit-ims-services, the installer

What it does. Username of the first administrator. Blank skips creation, and an install that already has an administrator is never touched.

When it is wrong. Blank on a fresh install, no one can log in until a user is created in the Keycloak admin console.

IMS_BOOTSTRAP_ADMIN_EMAIL​

  • Kind: Asked at install
  • Where: .env
  • Optional: yes, an empty value is valid
  • Read by: nadigit-ims-services

What it does. E-mail of the first administrator.

When it is wrong. Invalid, Keycloak rejects the user and the first administrator is not created.

IMS_BOOTSTRAP_ADMIN_FIRST_NAME​

  • Kind: Asked at install
  • Where: .env
  • Optional: yes, an empty value is valid
  • Read by: nadigit-ims-services

What it does. First name of the first administrator.

When it is wrong. Cosmetic.

IMS_BOOTSTRAP_ADMIN_LAST_NAME​

  • Kind: Asked at install
  • Where: .env
  • Optional: yes, an empty value is valid
  • Read by: nadigit-ims-services

What it does. Last name of the first administrator.

When it is wrong. Cosmetic.

IMS_BOOTSTRAP_ADMIN_PASSWORD​

  • Kind: Generated secret
  • Where: .env
  • Read by: nadigit-ims-services, the installer

What it does. Temporary password of the first administrator, printed to install-summary.txt. Keycloak forces a change at first login.

When it is wrong. None after that first login. Before it, losing install-summary.txt means resetting the password in Keycloak.

IMS_BOOTSTRAP_ADMIN_ROLES​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Realm roles granted to the first administrator.

When it is wrong. Without ADMIN, the first user logs in to a console that shows nothing.

IMS_KEYCLOAK_ADMIN_AUGMENT_USER_ATTRIBUTES​

  • Kind: Fixed by the release
  • Where: not in .env; docker-compose.prod.yml defaults it to false
  • Read by: nadigit-ims-services

What it does. Merges extra user attributes through the Admin API when users log in.

When it is wrong. true adds an Admin API call per login. Harmless, but slower.

IMS_KEYCLOAK_BOOTSTRAP_LOGIN_THEME_APPLY_ONCE​

  • Kind: Fixed by the release
  • Where: not in .env; docker-compose.prod.yml defaults it to true
  • Read by: nadigit-ims-services

What it does. Applies the login theme only while its marker is absent.

When it is wrong. false re-applies the theme on every restart, overwriting a theme chosen in the admin console.

IMS_KEYCLOAK_BOOTSTRAP_LOGIN_THEME_FORCE​

  • Kind: Fixed by the release
  • Where: not in .env; docker-compose.prod.yml defaults it to false
  • Read by: nadigit-ims-services

What it does. Re-applies the login theme even when its marker exists.

When it is wrong. Left true, it overwrites the realm theme on every restart.

IMS_KEYCLOAK_BOOTSTRAP_USER_PROFILE_FORCE​

  • Kind: Fixed by the release
  • Where: not in .env; docker-compose.prod.yml defaults it to false
  • Read by: nadigit-ims-services

What it does. Re-applies the user profile even when its marker exists.

When it is wrong. Left true, it overwrites user-profile edits on every restart.

Databases​

POSTGRES_NADIGIT_IMS_HOST​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services, postgres_nadigit_ims_db, the installer

What it does. Application database container on the internal network. No published port, by design.

When it is wrong. The application cannot reach its database and never becomes healthy.

POSTGRES_NADIGIT_IMS_USER​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services, postgres_nadigit_ims_db, the installer

What it does. Application database user, fixed when the volume is first initialised.

When it is wrong. initdb does not re-run, so changing it after first boot locks the application out of its own data.

POSTGRES_NADIGIT_IMS_PASSWORD​

  • Kind: Generated secret
  • Where: .env
  • Read by: nadigit-ims-services, postgres_nadigit_ims_db, the installer

What it does. Application database password. Generated once and never rotated by the launcher.

When it is wrong. initdb does not re-run on a populated volume, so a new value locks the application out of its own data.

POSTGRES_NADIGIT_IMS_DB​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services, postgres_nadigit_ims_db, the installer

What it does. Application database name.

When it is wrong. Fixed at first initialisation, like the user.

POSTGRES_KC_HOST​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: keycloak, postgres_kc_db, the installer

What it does. Keycloak database container on the internal network.

When it is wrong. Keycloak cannot start, so nobody can log in.

POSTGRES_KC_USER​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: keycloak, postgres_kc_db

What it does. Keycloak database user, fixed when its volume is first initialised.

When it is wrong. Changed after first boot, Keycloak is locked out of its data. An older demo volume was initialised with postgres, not kc_user: check before adopting one.

POSTGRES_KC_PASSWORD​

  • Kind: Generated secret
  • Where: .env
  • Read by: keycloak, postgres_kc_db, the installer

What it does. Keycloak database password. Generated once and never rotated by the launcher.

When it is wrong. The same trap as the application database: a new value locks Keycloak out of its data.

POSTGRES_KC_DB​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: keycloak, postgres_kc_db

What it does. Keycloak database name.

When it is wrong. Fixed at first initialisation.

Application​

NADIGIT_IMS_SERVICES_HOST​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services, the installer

What it does. Application container name on the internal network. nginx and the launcher address it by this name.

When it is wrong. nginx proxies nowhere and every /api/ call answers 502.

NADIGIT_IMS_SERVICES_PORT​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services, the installer, nginx (vhost)

What it does. Port the application listens on inside its container. Rendered into the nginx vhost.

When it is wrong. nginx proxies to a closed port: 502 on every API call.

SPRING_PROFILES_ACTIVE​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Spring profile. prod on every customer install.

When it is wrong. A development profile enables settings that are not meant for production.

IMS_JAVA_OPTS​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. JVM options. The heap is a share of the container limit so it follows mem_limit, and ExitOnOutOfMemoryError restarts the container instead of leaving it wedged.

When it is wrong. A fixed heap larger than mem_limit gets the container OOM-killed in a loop; too little metaspace fails as pages are first visited.

CORS_ALLOWED_ORIGINS​

  • Kind: Derived
  • Derived from: PUBLIC_PROTOCOL://PUBLIC_HOST
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Browser origins allowed to call the API. Browser origins only: the licence server is not one.

When it is wrong. The console loads, then the browser blocks every API call (doctor API-02).

Licensing​

LICENSE_REMOTE_URL​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. Online licence verification endpoint.

When it is wrong. Unreachable, online verification fails and the instance falls back to offline validation of the signed licence.

IMS_LICENSE_ENFORCE_AT_STARTUP​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. true refuses to boot without a licence. false starts in a restricted mode where only /api/license answers, so a licence can be activated from the console.

When it is wrong. true without a licence: the application exits at boot, and the licence can no longer be activated from the console.

IMS_LICENSE_RESEED​

  • Kind: Fixed by the release
  • Where: .env
  • Read by: nadigit-ims-services

What it does. true for ONE start overwrites the active licence from config/license.json.

When it is wrong. Left true, every restart re-seeds the licence and discards a renewal activated in the console.