> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/installation-methods/docker-installation.md).

# Running OCS Inventory Server with Docker

This guide explains how to deploy OCS Inventory (backend API + web console) using Docker Compose. It uses the official `ocsinventory-server` Docker stack, which brings up four containers:

| Service                 | Image                                | Role                                                        |
| ----------------------- | ------------------------------------ | ----------------------------------------------------------- |
| `ocsinventory-backend`  | `ocsinventory/ocsinventory-backend`  | Django REST API (served over uWSGI)                         |
| `ocsinventory-proxy`    | `nginx`                              | Reverse proxy in front of the backend, exposes ports 80/443 |
| `ocsinventory-db`       | `postgres:15.15`                     | PostgreSQL database used by the backend                     |
| `ocsinventory-frontend` | `ocsinventory/ocsinventory-frontend` | Web console, exposed on port 8080                           |

### 1. Requirements

* Docker Engine (20.10 or newer)
* Docker Compose plugin (`docker compose`)
* Ports `80`, `443` and `8080` available on the host (or adjust them, see [Changing exposed ports](#id-8.-changing-exposed-ports))

### 2. Get the stack

Download the `docker-compose.yml` and the `files/` directory for the version you want to deploy:

```bash
mkdir ocsinventory-server && cd ocsinventory-server
curl -O https://raw.githubusercontent.com/OCSInventory-NG/OCSInventory-Server-Packages/main/ocsinventory-server/docker/3.0.0-rc1/docker-compose.yml
mkdir -p files/nginx
curl -o files/nginx/ocsinventory-backend.conf \
  https://raw.githubusercontent.com/OCSInventory-NG/OCSInventory-Server-Packages/main/ocsinventory-server/docker/3.0.0-rc1/files/nginx/ocsinventory-backend.conf
```

{% hint style="info" %}
The `files/nginx/ocsinventory-backend.conf` file is required: it is mounted into the `ocsinventory-proxy` container and tells nginx how to forward requests to the backend over its UNIX socket.
{% endhint %}

### 3. Configure the stack

Before starting the stack for the first time, review and adjust the environment variables in `docker-compose.yml`.

#### Database credentials

The `ocsinventory-db` and `ocsinventory-backend` services must agree on the same PostgreSQL credentials:

```yaml
services:
  ocsinventory-backend:
    environment:
      DB_NAME_ENV: "ocsdb"
      DB_USER_ENV: "ocsuser"
      DB_PASSWORD_ENV: "ocsuser"

  ocsinventory-db:
    environment:
      POSTGRES_USER: ocsuser
      POSTGRES_PASSWORD: ocsuser
      POSTGRES_DB: ocsdb
```

{% hint style="warning" %}
Change `DB_PASSWORD_ENV` / `POSTGRES_PASSWORD` (and ideally `DB_USER_ENV` / `POSTGRES_USER`, `DB_NAME_ENV` / `POSTGRES_DB`) before deploying to production. The default values are only meant to get you started quickly in a local/test environment.
{% endhint %}

#### Public URLs

Two variables need to match how you will actually reach the stack from a browser:

* `ocsinventory-backend.FRONTEND_REDIRECT_ENV` - URL where the web console is reachable (used by the backend, e.g. for redirects).
* `ocsinventory-frontend.BACKEND_API_ROUTE_ENV` - URL where the backend API is reachable (used by the console to call the API).

By default they are set for a local deployment:

```yaml
    FRONTEND_REDIRECT_ENV: "http://localhost:8080"   # backend -> frontend
    BACKEND_API_ROUTE_ENV: "http://localhost/"        # frontend -> backend
```

If you deploy behind a domain name (e.g. `ocsinventory.example.com`), update both accordingly, for instance:

```yaml
    FRONTEND_REDIRECT_ENV: "https://ocsinventory.example.com:8080"
    BACKEND_API_ROUTE_ENV: "https://ocsinventory.example.com/"
```

#### Backend debug mode

`DEBUG_ENV` controls Django's debug mode. Keep it set to `"False"` in production; only set it to `"True"` for troubleshooting, as debug mode can leak sensitive information.

### 4. Start the stack

```bash
docker compose up -d
```

On first startup:

* `ocsinventory-db` initializes its data directory and runs a healthcheck before the backend starts.
* `ocsinventory-backend` generates its configuration (`.env`) from the environment variables above, generates a Django secret key, and runs database migrations automatically.
* `ocsinventory-proxy` starts once the backend is up, exposing the API on ports 80/443.
* `ocsinventory-frontend` starts and serves the web console on port 8080.

Check that every container is healthy:

```bash
docker compose ps
```

Follow the logs (useful the first time, to confirm migrations succeeded):

```bash
docker compose logs -f ocsinventory-backend
```

### 5. Access OCS Inventory

* Web console: `http://localhost:8080` (or the host/port you configured)
* Backend API: `http://localhost/` (or the host/port you configured)

### 6. Data persistence

The stack uses named Docker volumes so data survives container restarts and recreations:

| Volume                             | Contents                                     |
| ---------------------------------- | -------------------------------------------- |
| `ocsinventory-db`                  | PostgreSQL data files                        |
| `ocsinventory-backend-socket`      | UNIX socket shared between backend and proxy |
| `ocsinventory-frontend-config`     | Web console configuration                    |
| `ocsinventory-frontend-extensions` | Web console extensions/plugins               |

List them:

```bash
docker volume ls | grep ocsinventory
```

{% hint style="warning" %}
Removing these volumes (e.g. via `docker compose down -v`) permanently deletes your inventory data. Only do this if you really want to reset the deployment.
{% endhint %}

### 7. Common operations

#### Stop the stack (keep data)

```bash
docker compose down
```

#### Stop the stack and delete all data

```bash
docker compose down -v
```

#### Update to a newer version

1. Update the `image:` tags in `docker-compose.yml` to the new version (backend and frontend versions should generally match).
2. Pull the new images and recreate the containers:

   ```bash
   docker compose pull
   docker compose up -d
   ```

   Database migrations are applied automatically by the backend's entrypoint on startup.

#### Back up the database

```bash
docker compose exec ocsinventory-db pg_dump -U ocsuser ocsdb > ocsdb-backup.sql
```

#### Restore the database

```bash
cat ocsdb-backup.sql | docker compose exec -T ocsinventory-db psql -U ocsuser -d ocsdb
```

### 8. Changing exposed ports

If ports 80, 443 or 8080 are already in use on the host, change the left side of the `ports:` mapping in `docker-compose.yml`, for example:

```yaml
  ocsinventory-proxy:
    ports:
      - 8081:80
      - 8443:443

  ocsinventory-frontend:
    ports:
      - "8082:80"
```

Remember to update `FRONTEND_REDIRECT_ENV` and `BACKEND_API_ROUTE_ENV` (see [Public URLs](#public-urls)) so they reflect the ports you actually expose.

### 9. Enabling HTTPS

The `ocsinventory-proxy` service exposes port 443, but TLS termination is not configured out of the box. To enable HTTPS:

1. Provide a certificate and key on the host (e.g. via Let's Encrypt).
2. Mount them into the `ocsinventory-proxy` container and extend `files/nginx/ocsinventory-backend.conf` with a `server` block listening on `443 ssl` that references those files, redirecting plain HTTP to HTTPS if desired.
3. Update `FRONTEND_REDIRECT_ENV` and `BACKEND_API_ROUTE_ENV` to use `https://`.

### 10. Troubleshooting

* **Backend keeps restarting** - check `docker compose logs ocsinventory-backend`. This is usually a database connectivity issue (wrong credentials, or `ocsinventory-db` not yet healthy) or a failed migration.
* **502/504 errors from the proxy** - the backend is not ready yet, or crashed. Check its logs, and confirm `ocsinventory-backend-socket` is correctly shared between the `ocsinventory-backend` and `ocsinventory-proxy` containers.
* **Console cannot reach the API** - confirm `BACKEND_API_ROUTE_ENV` on the frontend matches the URL actually used to reach the backend from the browser (not from inside the Docker network).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/installation-methods/docker-installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.