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 Engine (v20.10 or newer)
- Docker Compose (Compose V2 recommended)
Method 1: Docker Compose (Recommended)
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:
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:
# 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
- Open your browser and navigate to
http://localhost:8080(or your configuredAPP_URL). - Log in using your initial administrator username (
INIT_ADMIN_USERNAME) and password (INIT_ADMIN_PASSWORD). - Upon first login, you will be prompted immediately to change your password for security.
- 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:
-
Set
APP_URLto your full public HTTPS URL, for example:APP_URL=https://inventory.example.com. -
Ensure your reverse proxy forwards standard HTTP headers:
Host: $hostX-Forwarded-For: $proxy_add_x_forwarded_forX-Forwarded-Proto: https
The proxy must set
X-Forwarded-Protoitself and not pass on a value sent by the client. Caddy and Traefik do this by default; with Nginx, useproxy_set_header X-Forwarded-Proto $scheme;.From v1.5.0, when
APP_URLand every entry ofAPP_URLSusehttps://, OpenInvento sends the session and CSRF cookies with theSecureflag and takes the scheme fromX-Forwarded-Proto(the Nginx inside the container passes it on). See URL & Host Configuration. -
Configure trusted proxy IP ranges and the proxy hop count for rate limiting. See Rate Limiting and Trusted Proxies.