> 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/backend.md). # Backend This guide walks a developer through setting up a local development environment for the [OCS Inventory Server Backend Rework](https://github.com/OCSInventory-NG/OCSInventory-Server-Backend-Rework) repository - the Django-based rewrite of the OCS Inventory server backend. This guide is for **development environments only**. For a production deployment, see the [OCS Inventory Server Setup](/administrator-docs/server-setup.md) guide instead. ### Overview This repository contains only the **backend** (a Django REST API). It does not include the frontend SPA or the agent. To run a full stack locally, you'll also need the separate frontend project, but this guide only covers the backend. ### Prerequisites * **Python 3.12 or later** - the project depends on `django>=6.0.2`, which requires a recent Python version. * **pip** (and optionally `venv` or `virtualenv`) - to manage dependencies in an isolated environment. * **Git** - to clone the repository. * A **database server** - either PostgreSQL or MySQL/MariaDB. The project doesn't include a database setup script; you're expected to create the database and user yourself using your database system's own tools. * Build tools for `python-ldap` (used for LDAP authentication). On Debian/Ubuntu, this typically means the `libldap2-dev`, `libsasl2-dev`, and `python3-dev` system packages, plus a C compiler. See the [python-ldap installation notes](https://www.python-ldap.org/en/python-ldap-3.4.3/installing.html) if `pip install` fails on this dependency. {% hint style="info" %} This project doesn't ship a `Dockerfile` or `docker-compose.yml` for development. Setup is done directly on your machine (or inside a VM/container you manage yourself). {% endhint %} ### Step 1 - Clone 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-Backend-Rework.git cd OCSInventory-Server-Backend-Rework ``` The default branch for active development is `dev`. ### Step 2 - Create a Virtual Environment Working in a virtual environment keeps this project's dependencies separate from your system's Python packages. ```bash python3 -m venv venv source venv/bin/activate ``` ### Step 3 - Install Python Dependencies Install the base requirements first: ```bash pip install -r requirements.txt ``` {% hint style="warning" %} If installing `python-ldap` fails with a build error, it's almost always a missing system dependency (headers for LDAP/SASL), not a Python packaging issue. See the [python-ldap installation guide](https://www.python-ldap.org/en/python-ldap-3.4.3/installing.html) for the packages required on your OS. {% endhint %} Then install the driver matching your database: ```bash pip install -r requirements_psql.txt # PostgreSQL # or pip install -r requirements_mysql.txt # MySQL / MariaDB ``` ### Step 4 - Create the Database The project doesn't create the database or the database user for you. Using your database system's own tooling, create: * An empty database (e.g. `ocsinventory`). * A database user with full privileges on that database. Refer to your database system's documentation for the exact commands (`psql`/`createdb` for PostgreSQL, `mysql`/`mariadb` client for MySQL/MariaDB). ### Step 5 - Configure Environment Variables Copy the sample environment file: ```bash cp .env-sample .env ``` Edit `.env` with your own values: | Variable | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | `DEBUG` | `True` for a development environment (enables Django's debug mode). Keep `False` in production. | | `SECRET_KEY` | Django's secret key. Replace the sample value with your own random string, even for local dev. | | `FRONTEND_REDIRECT` | URL of the frontend application (e.g. `http://localhost:3000`), used for redirects after actions such as login. | | `DB_ENGINE` | `django.db.backends.postgresql` for PostgreSQL, or `django.db.backends.mysql` for MySQL/MariaDB. | | `DB_NAME` | Name of the database you created in Step 4. | | `DB_USER` | Database user. | | `DB_PASSWORD` | Database user's password. | | `DB_HOST` | Database host (e.g. `localhost`). | | `DB_PORT` | Database port (`5432` for PostgreSQL, `3306` for MySQL/MariaDB). | For the full list of database options supported by Django, see the [Django database documentation](https://docs.djangoproject.com/en/5.2/ref/databases/). ### Step 6 - Apply Database Migrations Once the database is reachable and `.env` is configured, create the schema: ```bash python manage.py migrate ``` {% hint style="info" %} Migrations create a default superuser with the credentials `admin` / `admin`. This is convenient for local development, but change the password (or disable the account) before using this setup anywhere it could be exposed. {% endhint %} ### Step 7 - Run the Development Server ```bash python manage.py runserver ``` By default, the API is now available at `http://localhost:8000/`. If you're running the frontend separately, make sure `FRONTEND_REDIRECT` in `.env` points to where the frontend is served. ### Troubleshooting | Symptom | Likely cause | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `pip install` fails while building `python-ldap` | Missing system headers for LDAP/SASL. Install your OS's development packages and retry. | | Django can't connect to the database | Check `DB_HOST`, `DB_PORT`, `DB_USER`, and `DB_PASSWORD` in `.env`, and confirm the database server is running and reachable. | | Wrong database driver installed | Make sure `DB_ENGINE` in `.env` matches the requirements file you installed (`requirements_psql.txt` vs `requirements_mysql.txt`). | | Frontend can't reach the API or redirects fail | Confirm `FRONTEND_REDIRECT` matches the actual URL where your frontend is running. | ### How to Contribute {% stepper %} {% step %} **Fork the repository** on GitHub, then clone your fork locally (see the note in Step 1 above). {% endstep %} {% step %} **Create a branch** for your change, based on `main`: ```bash git checkout main git pull git checkout -b my-feature-branch ``` {% endstep %} {% step %} **Make your changes**, following the existing code style. The repository includes several quality and security configs (`.cspell.json`, `.gitleaks.toml`, `.jscpd.json`, `.mega-linter.yml`) — running the relevant checks locally before committing will catch most issues early and matches what CI checks on your pull request. {% endstep %} {% step %} **Commit and push** your branch to your fork: ```bash git add . git commit -m "Describe your change" git push origin my-feature-branch ``` {% endstep %} {% step %} **Open a pull request** from your branch to the `main` branch of the main repository, with a clear description of what the change does and why. {% endstep %} {% endstepper %} {% hint style="info" %} Keep pull requests focused on a single change. Smaller, well-scoped PRs are easier to review and more likely to be merged quickly. {% endhint %} ### One Last Thing You made it through project installation, migrations and `.env` files without rage-quitting : you're basically already qualified.\ \ OCS Inventory has been tracking IT assets since before some of your dependencies were born, and this backend rework is where the next chapter gets written. Every bug you squash, every endpoint you clean up, every typo you fix in a docstring makes life easier for the sysadmins out there who just want to know how many laptops still run an OS from a bygone era.\ \ So go ahead, open that pull request. Worst case, a reviewer asks for changes. Best case, your code ships to inventory servers you'll never see, quietly doing its job for years. Either way, dev branch is waiting for you. 🚀 --- # 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/backend.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.