Skip to main content

Docker Installation

The recommended and simplest way to run OpenInvento is using Docker and Docker Compose. All backend services, database migrations, and static frontend assets are bundled into a single optimized container image hosted on GitHub Container Registry (ghcr.io/openinvento/openinvento).


Prerequisites​

Before starting, ensure you have installed:


Docker Compose allows you to define your configuration cleanly in version-controlled files.

1. Create a Project Directory​

Create a directory for your OpenInvento deployment:

mkdir openinvento && cd openinvento

2. Create docker-compose.yml​

Create a docker-compose.yml file with the following contents:

docker-compose.yml
services:
openinvento:
image: ghcr.io/openinvento/openinvento:latest
container_name: openinvento
restart: unless-stopped
ports:
- "8080:80"
volumes:
- openinvento-data:/data
env_file:
- .env

volumes:
openinvento-data:
driver: local

3. Create .env​

Create a .env file in the same directory to configure your instance:

.env
# The public URL where OpenInvento will be accessed
APP_URL=http://localhost:8080

# Secret key for Django session and security signing (replace with a long random string)
SECRET_KEY=change-this-to-a-very-long-and-secure-random-secret-key

# Storage path inside the container
DATA_DIRECTORY=/data

# Initial Administrator Credentials (used only on first startup)
CREATE_INIT_ADMIN=true
INIT_ADMIN_USERNAME=admin
# Keep the single quotes: Compose would otherwise replace $... in the password with variables.
# Choose a password without single quotes.
INIT_ADMIN_PASSWORD='<set your own password before the first start>'

# Feature Flags
ENABLE_SIGNUP=false
ENABLE_UPDATE_CHECKER=true
ALLOW_INVENTORY_USER_INVITES=true

:::tip Generating a Secret Key You can generate a secure random secret key with OpenSSL:

openssl rand -hex 32

:::

4. Start the Application​

Launch OpenInvento in the background:

docker compose up -d

View the startup logs to ensure everything initialized properly:

docker compose logs -f

Method 2: Manual Docker Run​

If you prefer using pure Docker commands without Compose, you can run OpenInvento directly:

1. Create a Persistent Data Volume​

docker volume create openinvento-data

2. Run the Container​

docker run -d \
--name openinvento \
--restart unless-stopped \
-v openinvento-data:/data \
-p 8080:80 \
-e DATA_DIRECTORY=/data \
-e APP_URL=http://localhost:8080 \
-e INIT_ADMIN_USERNAME=admin \
-e INIT_ADMIN_PASSWORD='<set your own password before the first start>' \
-e CREATE_INIT_ADMIN=true \
-e ENABLE_SIGNUP=false \
-e ENABLE_UPDATE_CHECKER=true \
-e ALLOW_INVENTORY_USER_INVITES=true \
-e SECRET_KEY=replace-with-a-long-random-secret \
ghcr.io/openinvento/openinvento:latest

First Login & Initial Setup​

  1. Open your browser and navigate to http://localhost:8080 (or your configured APP_URL).
  2. Log in using your initial administrator username (INIT_ADMIN_USERNAME) and password (INIT_ADMIN_PASSWORD).
  3. Upon first login, you will be prompted immediately to change your password for security.
  4. Once completed, your default inventory is created and ready for use.

:::info Initial Admin Auto-Creation The initial administrator account is created only when the database contains no users. If the database already contains users, CREATE_INIT_ADMIN is ignored and will not overwrite existing credentials. :::


Running Behind a Reverse Proxy (Nginx, Traefik, Caddy)​

When exposing OpenInvento publicly with HTTPS:

  1. Set APP_URL to your full public HTTPS URL, for example: APP_URL=https://inventory.example.com.

  2. Ensure your reverse proxy forwards standard HTTP headers:

    • Host: $host
    • X-Forwarded-For: $proxy_add_x_forwarded_for
    • X-Forwarded-Proto: https

    The proxy must set X-Forwarded-Proto itself and not pass on a value sent by the client. Caddy and Traefik do this by default; with Nginx, use proxy_set_header X-Forwarded-Proto $scheme;.

    From v1.5.0, when APP_URL and every entry of APP_URLS use https://, OpenInvento sends the session and CSRF cookies with the Secure flag and takes the scheme from X-Forwarded-Proto (the Nginx inside the container passes it on). See URL & Host Configuration.

  3. Configure trusted proxy IP ranges and the proxy hop count for rate limiting. See Rate Limiting and Trusted Proxies.