> 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/developer-docs/setup-development-environment/docker.md). # Docker The [OCSInventory-Server-Packages](https://github.com/OCSInventory-NG/OCSInventory-Server-Packages) repository holds the deployment files, packaging, and Docker configurations used to build and install the OCS Inventory 3.X stack. This guide covers one specific part of it: the `ocsinventory-server/docker/dev` folder, which provides a ready-to-use Docker Compose stack for running the full OCS Inventory 3.X server (backend + frontend + database) locally, built directly from source instead of a published release image. {% hint style="warning" %} This stack is for **development and CI use only**. It uses hardcoded, weak database credentials and is not hardened for production. Never expose it to the internet or use it to store real inventory data. {% endhint %} ### Getting the Repository {% hint style="info" %} If you plan to contribute back to the project (bug fixes, features, pull requests), fork the repository on GitHub first and clone your fork instead of the main repository. This lets you push branches and open pull requests without needing write access to the original repo. {% endhint %} ```bash git clone https://github.com/OCSInventory-NG/OCSInventory-Server-Packages.git cd OCSInventory-Server-Packages ``` The default branch for active development is `main`. Everything below assumes your terminal is at the root of this checkout. ### What This Stack Does Instead of pulling a pre-built release image, this stack builds the backend and frontend Docker images itself, from a given branch, tag, or commit of their respective repositories: * [OCSInventory-Server-Backend-Rework](https://github.com/OCSInventory-NG/OCSInventory-Server-Backend-Rework) * [OCSInventory-Server-Frontend-Rework](https://github.com/OCSInventory-NG/OCSInventory-Server-Frontend-Rework) This is useful to test an unreleased feature branch, a pull request, or a specific commit, in a full working stack, without manually setting up Python, Node, and a database on your machine. Two variants are provided, one per supported database: | File | Database used | | ----------------------------- | ---------------- | | `docker-compose.mysql.yml` | MySQL 8.4 | | `docker-compose.postgres.yml` | PostgreSQL 15.15 | Both files are otherwise identical in structure. ### Prerequisites * **Docker** and **Docker Compose** (the `docker compose` plugin, not the legacy standalone `docker-compose` binary - the usage comments in these files assume the plugin syntax). * **Git** - to clone the repository. {% hint style="danger" %} The compose files reference sibling folders by relative path ( `../../../ocsinventory-backend/docker/dev` and `../../../ocsinventory-frontend/docker/dev` ) used as the backend and frontend build contexts. Both must exist in your checkout for the build to work, so don't move `docker-compose.mysql.yml` / `docker-compose.postgres.yml` out of the repository structure on their own. {% endhint %} ### Starting the Stack From the root of the `OCSInventory-Server-Packages` repository, run one of the following, depending on the database you want to test against: ```bash # MySQL docker compose -f ocsinventory-server/docker/dev/docker-compose.mysql.yml up -d --build # PostgreSQL docker compose -f ocsinventory-server/docker/dev/docker-compose.postgres.yml up -d --build ``` The `--build` flag is important the first time (and after pulling new commits), since these images aren't pulled from a registry - they're built locally from source. Once the stack is up: * The web console is available at `http://localhost:8081` (or your configured `DEV_FRONTEND_PORT`). * The backend API is reachable at `http://localhost:8880` (or your configured `DEV_HTTP_PORT`), through the Nginx proxy. ### Building a Specific Branch, Tag, or Commit By default, the stack builds the `dev` branch of both the backend and frontend repositories. Override this with environment variables when starting the stack: ```bash BACKEND_REF=my-backend-branch FRONTEND_REF=my-frontend-branch \ docker compose -f ocsinventory-server/docker/dev/docker-compose.mysql.yml up -d --build ``` | Variable | Default | Purpose | | --------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `BACKEND_REPO` | `https://github.com/OCSInventory-NG/OCSInventory-Server-Backend-Rework.git` | Git URL the backend image is built from. Override to build from a fork. | | `BACKEND_REF` | `dev` | Branch, tag, or commit SHA of the backend repo to build. | | `FRONTEND_REPO` | `https://github.com/OCSInventory-NG/OCSInventory-Server-Frontend-Rework.git` | Git URL the frontend image is built from. Override to build from a fork. | | `FRONTEND_REF` | `dev` | Branch, tag, or commit SHA of the frontend repo to build. | This is the main use case for this stack: point `BACKEND_REF` or `FRONTEND_REF` at your own feature branch (or someone else's pull request branch) and get a full working environment to test it in, without touching your local setup for the other repositories. ### Configuring Ports By default, the stack exposes these ports on your machine. All are overridable through environment variables: | Variable | Default | Exposes | | ------------------- | ------- | --------------------------------------------- | | `DEV_HTTP_PORT` | `8880` | Backend API over HTTP (via the Nginx proxy). | | `DEV_HTTPS_PORT` | `8843` | Backend API over HTTPS (via the Nginx proxy). | | `DEV_FRONTEND_PORT` | `8081` | The web console. | For example, to avoid a port conflict with something already running on `8880`: ```bash DEV_HTTP_PORT=9880 docker compose -f ocsinventory-server/docker/dev/docker-compose.mysql.yml up -d --build ``` {% hint style="info" %} `DEV_FRONTEND_PORT` is used in two places: to expose the frontend container, and to build the backend's `FRONTEND_REDIRECT_ENV`. If you change it, both automatically stay in sync since they read from the same variable. {% endhint %} ### Services in the Stack | Service | Image | Role | | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ocsinventory-backend` | Built locally from the backend repo | The Django REST API. Listens internally on port `8000`; not exposed directly on the host. | | `ocsinventory-proxy` | `nginx` (official image) | Reverse proxy in front of the backend, exposed on `DEV_HTTP_PORT` / `DEV_HTTPS_PORT`. Talks to the backend over a Unix socket (shared volume), not over HTTP. | | `ocsinventory-db` | `mysql:8.4` or `postgres:15.15` | The database, with a healthcheck the backend waits on before starting. | | `ocsinventory-frontend` | Built locally from the frontend repo | The Vue.js web console, exposed on `DEV_FRONTEND_PORT`. | The backend and proxy communicate over a Unix socket, shared through the `ocsinventory-backend-socket` volume, rather than over the network - this mirrors how the production packages are set up. ### Data Persistence Four named volumes persist data across restarts: | Volume | Contents | | ---------------------------------- | ----------------------------------------------------------------------------------- | | `ocsinventory-backend-socket` | The Unix socket shared between the backend and the proxy. | | `ocsinventory-db` | The database files (MySQL or PostgreSQL, depending on which compose file you used). | | `ocsinventory-frontend-config` | The frontend's runtime configuration (`config.json`). | | `ocsinventory-frontend-extensions` | Frontend extensions. | To fully reset the stack, including all data, add `-v` when tearing it down (see below). ### Stopping the Stack ```bash docker compose -f ocsinventory-server/docker/dev/docker-compose.mysql.yml down ``` Add `-v` to also remove the named volumes (database data, frontend config, etc.) for a completely clean slate: ```bash docker compose -f ocsinventory-server/docker/dev/docker-compose.mysql.yml down -v ``` ### Switching Between MySQL and PostgreSQL The two compose files use separate container names, volumes, and Compose project names (`ocsinventory-dev-mysql` vs `ocsinventory-dev-postgres`), so they won't collide if you happen to run both - but running both at once isn't a typical workflow and will double up on backend/frontend build time and host resources. If you need to switch databases, stop and remove the stack you're not using (`down -v`) before starting the other. ### Troubleshooting | Symptom | Likely cause | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Build fails right away | Confirm you're running the command from a full checkout of `OCSInventory-Server-Packages` - the backend/frontend build contexts are sibling folders and must exist. | | Backend container keeps restarting | Check its logs (`docker compose ... logs ocsinventory-backend`) - a common cause is the database healthcheck not passing yet, or an invalid `BACKEND_REF`. | | Frontend loads but can't reach the API | Confirm `DEV_HTTP_PORT` matches what you're browsing to, and that the proxy and backend containers are both running. | | Changes to `BACKEND_REF` don't seem to take effect | Re-run with `--build` - without it, Compose reuses the previously built image instead of rebuilding from the new ref. | | Port already in use | Override `DEV_HTTP_PORT`, `DEV_HTTPS_PORT`, or `DEV_FRONTEND_PORT` to a free port on your machine. | --- # 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/developer-docs/setup-development-environment/docker.md?ask=&goal= ``` `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.