Environment variable reference

This reference covers all 155 entries in the application's .env.example, plus relevant runtime and compatibility settings. It was checked against the repository configuration and readers on 1 November 2026. Older deployed images may not support every setting, including the recently added branding options.

These variables belong to your Open Inventory application, not to this documentation website. See Configure your instance for a short introduction and the example environment file for a starting point.

Reading this referenceCopy Anchor Link

• Default means the behavior when the variable is absent, not necessarily the value supplied by .env.example or a deployment template. Differences are called out below.
• Required means required by the production startup script. Conditional means required only for the named feature. Other settings are optional.
• Secret marks credentials or sensitive configuration. Do not commit their real values or expose them through NEXT_PUBLIC_ variables. An unmarked value may still contain private infrastructure information.
• Unless a section says Build, Compose or Tool, settings are Runtime settings. Restart the application process after changing them; recreate containers to load a changed container environment. Some settings are initialized only at startup.
• Use true or false for booleans. Numeric timeouts are milliseconds unless the name or table explicitly says seconds, minutes, hours or days. Limits described as clamped are restricted to the stated range.
• An empty string is not universally equivalent to an absent variable: numeric readers can interpret it as zero. Omit optional numeric overrides to retain their defaults, or provide an explicit valid number.

Load settings and apply changesCopy Anchor Link

For local development, put values in .env.local in the application repository root and restart npm run dev. Next.js prioritizes the process environment, then environment-specific local files, .env.local, environment-specific files and .env. .env.local is excluded in test mode.

For Docker Compose, .env supplies values for Compose interpolation. It does not automatically pass every variable into the container. Verify that the application service forwards the setting under environment, or add a mapping:

services:
  app:
    environment:
      APP_NAME: ${APP_NAME:-}
      APP_LOGO_URL: ${APP_LOGO_URL:-}

The root Compose service is named app; the Dokploy and Coolify templates use inventory. The templates forward different subsets of settings. In particular, a setting described here may require an additional mapping in an older or custom deployment definition.

After runtime changes, recreate the application using the same Compose files used to deploy it. For the repository's local port override:

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --force-recreate app

In Dokploy or Coolify, save the environment and Compose mappings, then redeploy. docker restart alone does not change the container's environment. Build-time map settings require a new application build; see Maps.

Keep bcrypt hashes in single quotes in Compose .env files so their dollar signs are preserved. Base64 is an encoding, not encryption.

Core application and brandingCopy Anchor Link

All settings in this table are Runtime.

Branding examples · Production startup validation

Password login and bootstrapCopy Anchor Link

Runtime. Bootstrap configuration creates the first database-backed administrator only while no users exist; it is not a password-reset mechanism for existing users. Prefer database-managed users after initialization.

The production entrypoint removes plaintext bootstrap values from the app process after hashing; it cannot remove them from the saved deployment environment. Remove them there yourself after initialization.

External sign-inCopy Anchor Link

Runtime. These providers require pre-existing active application users and organization memberships; they do not replace application authorization. Supply a complete provider configuration. Partial configurations fail production startup. See Sign-in and access and the detailed provider guide.

Auth0Copy Anchor Link

Register https://inventory.example.com/api/auth/callback/auth0, replacing the origin with your instance.

Generic OpenID ConnectCopy Anchor Link

Register /api/auth/callback/<provider-id> on your application origin. The provider must supply a verified email matching the existing user.

Dedicated Supabase OAuthCopy Anchor Link

This is separate from generic OIDC and supports self-hosted gateways. Register /api/auth/callback/supabase with client_secret_basic. Supply all four connection values together.

Organizations and public demoCopy Anchor Link

Runtime. These settings affect the deployment, not just one organization's preferences.

Disabling demo access hides the entry point; it does not delete demo data. Follow the demo deployment guide for removal.

Storage and upload limitsCopy Anchor Link

Runtime. Paths are resolved inside the app process/container. Mount persistent storage where the process can write; the standard container uses UID/GID 1001.

Raising an application limit does not change reverse-proxy limits or endpoint-specific checks. The Next.js Server Actions body limit is configured separately in code.

MapsCopy Anchor Link

Build. All three map variables are public client-bundle settings. Set them before next build; the Dockerfile accepts them as build arguments. Changing the runtime environment of a prebuilt image does not update maps. Never place private credentials in these variables.

For a source-based Docker deployment, set the values in .env and rebuild with the same Compose files used for installation, adding --build to up -d. For an image-based platform template, publish/use an image built with the intended values.

AI providers, models and timeoutsCopy Anchor Link

Runtime. AI is optional; setting a model does not configure credentials or grant access to that model. IDs below are application defaults, not a guarantee of provider availability for your account. Credentials stay on the server.

Saved organization settings under Settings → AI take precedence over the environment defaults for inventory analysis, research and output language. Changing those Env defaults does not overwrite saved organization settings.

Cover-image generationCopy Anchor Link

Example of a restricted catalog:

IMAGE_EDIT_MODELS=openai:gpt-image-1,google:gemini-2.5-flash-image
IMAGE_EDIT_DEFAULT_MODEL=openai:gpt-image-1

Paid-AI request limitsCopy Anchor Link

Per-identity request limits are separate from provider billing limits. Integers from 0 to 1,000,000 are accepted. Zero disables the operation. A malformed explicit value also disables it.

For analysis, research, recognition and counting, precedence is: operation-specific value → AI_RATE_LIMIT_PER_MINUTE → built-in operation default. Blank overrides are skipped. The example file and root Compose template explicitly set the legacy limit to 10, so research inherits 10, rather than its built-in default of 5, unless overridden.

Rate-limit policy source

Replicate photo countingCopy Anchor Link

Runtime. A Replicate key is required for hosted counting models. Models must be pinned as owner/model:version, where the version is a 64-character hexadecimal identifier; an unversioned model path is rejected. The four built-in pins are listed separately below.

Built-in pins at the time of this reference:

REPLICATE_GROUNDING_DINO_MODEL=adirik/grounding-dino:efd10a8ddc57ea28773327e881ce95e20cc1d734c589f7dd01d2036921ed78aa
REPLICATE_YOLO_WORLD_MODEL=ultralytics/yolov8s-worldv2:5e89b91b497fa7329dc88dbf820923190236ef7bc5a9b4aa1b7192b206656650
REPLICATE_SAM2_MODEL=meta/sam-2:fe97b453a6455861e3bac769b441ca1f1086110da7466dbb65cf1eecfd60dc83
REPLICATE_COUNT_MODEL=yodagg/sam3-image-seg:29c8e52db92a11c64f8939244d6b3a047ce2af24412b7971309008b9a61e2f6e

Experimental local 3D estimationCopy Anchor Link

Runtime. This feature requires a separate Python/GPU installation and model weights; the standard app image does not include them. Setting the flag alone is insufficient. See the 3D runtime setup.

In the table, ROOT means the resolved BULK_3D_DATA_PATH, not a separate variable to set.

Translation workerCopy Anchor Link

Runtime. Durable jobs are stored in PostgreSQL and processed by the application worker. Disable it only if another running worker is responsible for those jobs.

NotificationsCopy Anchor Link

Runtime. The in-app inbox works independently of external delivery. Configuring an external channel does not opt users into it; preferences still apply.

Worker and encryptionCopy Anchor Link

EmailCopy Anchor Link

Email requires SMTP_HOST and NOTIFICATION_EMAIL_FROM. Supply credentials if your mail server requires authentication.

Web PushCopy Anchor Link

All three VAPID values and NOTIFICATION_ENCRYPTION_KEY are required. Generate the VAPID pair with npx web-push generate-vapid-keys.

Team delivery targetsCopy Anchor Link

These notification targets are separate from the outgoing event-webhook system below.

Outgoing event webhooksCopy Anchor Link

Runtime. Configure subscriptions in Settings → Webhooks. Their signing secrets are encrypted at rest. The database-backed worker can run on multiple app replicas.

WooCommerce and connection encryptionCopy Anchor Link

Runtime. Configure actual store connections and credentials under Settings → WooCommerce.

The distinction above reflects the current WooCommerce implementation; the mere presence of a variable in a Compose template does not make it an active feature setting.

MCP endpointCopy Anchor Link

Runtime. Enable the optional endpoint at POST /mcp. It accepts Inventory API bearer tokens scoped to their issuing organization, not browser sessions or X-Organization-ID overrides.

For client setup, tool schemas, write confirmation, retries and troubleshooting, see the MCP integration guide.

Unlike AI limits, an MCP limit of zero does not disable an operation: it falls back to the default. Use endpoint configuration and token permissions to restrict access.

QZ Tray signingCopy Anchor Link

Runtime. Supply both a certificate and private key to enable signing. File paths take precedence over Base64 values for each item. Mount files where the app user can read them. This configuration does not install QZ Tray or configure the printer on the user's computer.

The certificate must be trusted on the printing computer. Without signing, QZ's approval prompts remain part of the workflow. See Labels and printing.

Docker Compose and platform inputsCopy Anchor Link

Compose/platform, not general application readers. These variables configure database credentials, port publishing or platform-generated values. The full root Compose file and platform templates remain authoritative for the selected installation method.

POSTGRES_DB and POSTGRES_USER are set in the database service itself; the root template fixes both to inventory. The Dokploy import template generates its own password/secret inputs and maps them into the application environment.

Optional SSH database tunnelCopy Anchor Link

Tool. These settings are consumed by npm run db:tunnel on the machine opening the tunnel, not by the production app. Restart the tunnel after changes. The helper loads .env.tunnel.local, .env.local and .env in that order without replacing already set process values.

Use exactly one remote target: host, Docker container or Docker Swarm service. The local listener must remain on loopback.

Point the local app's DATABASE_URL at the forwarded host/port when using the tunnel. Tunnel settings alone do not change the application's database connection.

Compatibility settings and scopeCopy Anchor Link

This page does not catalog test-only SMOKE_* inputs, benchmark controls, native mobile build credentials or Next.js internal variables such as NEXT_PHASE and NEXT_RUNTIME. They are not production application configuration.

Secrets and verificationCopy Anchor Link

Generate a new value separately for each encryption purpose. For variables requiring 32 random bytes as 64 hexadecimal characters:

openssl rand -hex 32

Preserve encryption keys together with protected deployment backups. Replacing WEBHOOK_ENCRYPTION_KEY, INTEGRATION_ENCRYPTION_KEY or NOTIFICATION_ENCRYPTION_KEY without a migration/re-enrollment plan can make existing encrypted data unreadable. Changing signing secrets can invalidate sessions or pending signed jobs.

After applying changes, check /api/health and the feature you configured. A healthy database/storage check does not verify SMTP credentials, model access, OAuth callbacks or a remote logo. Review application logs for validation errors without publishing environment dumps or rendered Compose secrets.

When updating this reference, compare .env.example, the relevant code readers and the deployment mappings. Keep example values distinct from built-in defaults, and verify newly added settings against the version you deploy.