opencve · ldurnez · Jul 11, 2026 · Jul 2, 2026
diff --git a/docs/deployment.md b/docs/deployment.md
diff --git a/docs/deployment/configuration.md b/docs/deployment/configuration.md
@@ -0,0 +1,79 @@
+# Configuration
+
+This page describes all configuration files used by the OpenCVE Docker stack. Review them **before** running `./install.sh start` for the first time.
+
+The `prepare` command (or `./install.sh` with no arguments) copies example files to their active locations:
+
+| File | Purpose |
+|------|---------|
+| `docker/.env` | Docker Compose environment variables |
+| `docker/conf/opencve.conf.template` | Nginx configuration for OpenCVE |
+| `docker/conf/default.conf.template` | Nginx default site template |
+| `web/opencve/conf/.env` | Django webserver environment |
+| `web/opencve/conf/settings.py` | Django settings overrides |
+| `scheduler/airflow.cfg` | Airflow scheduler configuration |
+
+Use `./install.sh -f prepare` to replace existing configuration files with fresh defaults from the examples.
+
+## docker/.env
+
+We recommend verifying and updating your docker `.env` file before the first start.
+
+### Security (change before first start)
+
+- `POSTGRES_PASSWORD`
+- `_AIRFLOW_WWW_USER_USERNAME`
+- `_AIRFLOW_WWW_USER_PASSWORD`
+- `AIRFLOW__CORE__FERNET_KEY`
+
+!!! warning
+    These variables are applied when Docker Compose creates the containers for the first time. Change them **before** running `./install.sh start`.
+    If you change `POSTGRES_PASSWORD`, update `OPENCVE_DATABASE_URL` in `web/opencve/conf/.env` accordingly before starting the stack.
+
+!!! note
+    To customize the fernet key: [how to generate a new fernet key](https://airflow.apache.org/docs/apache-airflow/stable/security/secrets/fernet.html#generating-fernet-key).
+
+### Version and ports
+
+- `OPENCVE_REPOSITORY`: Git repository URL (default: `https://github.com/opencve/opencve.git`)
+- `OPENCVE_VERSION`: release tag or branch built into Docker images (default: `master`, set by `./install.sh prepare`)
+- `OPENCVE_PORT`: port exposed for the OpenCVE web interface (default: `80`)
+- `AIRFLOW_WEBSERVER_PORT`: port exposed for the Airflow UI (default: `8080`)
+
+The application code is fetched from `OPENCVE_REPOSITORY` at `OPENCVE_VERSION` during the Docker build. Updating the running application does **not** require a `git pull` of the application code, use `./install.sh upgrade` instead (see [Operations](operations.md#upgrade)).
+
+## web/opencve/conf/.env
+
+This file exposes important settings used by the OpenCVE webserver:
+
+- `OPENCVE_DATABASE_URL`: database URI. Update it if you changed PostgreSQL parameters in `docker/.env`. Connection parameters must match in both files.
+- `OPENCVE_SECRET_KEY`: generated automatically by `./install.sh` on first run (skipped if already set)
+- `OPENCVE_*_REPO_PATH`: paths to the KB repositories (KB, MITRE, NVD, etc.)
+- `OPENCVE_V1_DATABASE`: URI of an OpenCVE v1 instance if needed (used for [data migration](../guides/migrate_opencve_v1.md))
+
+## web/opencve/conf/settings.py
+
+This file overrides Django default settings defined in [web/opencve/conf/base.py](https://github.com/opencve/opencve/blob/master/web/opencve/conf/base.py).
+
+See the [Django settings reference](https://docs.djangoproject.com/en/5.1/ref/settings/) to customize your instance.
+
+## scheduler/airflow.cfg
+
+This file configures the Airflow scheduler of OpenCVE.
+
+See the [Airflow configuration reference](https://airflow.apache.org/docs/apache-airflow/stable/configurations-ref.html) to customize your Airflow instance.
+
+The `prepare` command sets the DAG start dates to the current date.
+
+## Nginx templates
+
+Nginx configuration is managed through templates in `docker/conf/`:
+
+- `opencve.conf.template`: routes traffic to the Django webserver and serves static files
+- `default.conf.template`: default site configuration
+
+These are processed by the official `nginx:trixie` image at container startup.
+
+## Email (SMTP)
+
+To enable email notifications, configure SMTP settings in `scheduler/airflow.cfg` and trigger the `check_smtp` DAG. See the dedicated [SMTP configuration guide](../guides/smtp_configuration.md).
diff --git a/docs/deployment/install.md b/docs/deployment/install.md
@@ -0,0 +1,157 @@
+# Reference
+
+This page documents the `install.sh` script: its options and commands.
+
+For a guided first install, see [Overview](../deployment.md#installation).
+
+## Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `-h` | Print usage | `./install.sh -h` |
+| `-r` | Release or branch to install (default: `master`) | `./install.sh -r v3.0.0 prepare` |
+| `-f` | Force overwrite of existing configuration files | `./install.sh -f prepare` |
+| `-y` | Skip confirmation prompts (`reset` only) | `./install.sh -y reset` |
+
+## Commands
+
+| Command | When to use |
+|---------|-------------|
+| `prepare` | First install, or refresh config files |
+| `start` | First install (after prepare + configuration) |
+| `upgrade` | Update to a new version — see [Operations](operations.md#upgrade) |
+| `reset` | Destroy all data and reinstall — see [Operations](operations.md#reset) |
+| `create-superuser` | Create or reset the admin account |
+| `docker-build` | Rebuild images manually |
+| `docker-up` | Start containers, migrate, collect static files |
+| `init-docker-stack` | Bootstrap containers and connections |
+| `clone-repositories` | Clone KB repos into the Docker volume |
+| `import-opencve-kb` | Import CVEs into PostgreSQL (one-time) |
+| `start-opencve-dag` | Unpause all Airflow DAGs |
+| `init-secret-key` | Generate Django secret key |
+| `bye` | Display installation summary (URLs, version) |
+
+Most commands are **idempotent**: they skip steps already completed (existing repositories, imported CVEs, superuser, secret key, etc.).
+
+For step-by-step installation, run individual commands from the table above instead of `start`.
+
+!!! note
+    Full command details: `./install.sh -h`.
+
+## init-docker-stack
+
+Bootstraps the whole OpenCVE stack: builds and starts containers, applies migrations, collects static files, configures Airflow connections, and generates `OPENCVE_SECRET_KEY` if not already set.
+
+```
+./install.sh init-docker-stack
+
+--------| Docker compose up (1/5)
+> starting OpenCVE docker stack...
+[...]
+> done ✅
+
+--------| Apply Django webserver DB migration (2/5)
+> migrating DB schema with latest changes...
+> done ✅
+
+--------| Collect static files from Django webserver (3/5)
+> collecting latest static files...
+> done ✅
+
+--------| Add Airflow connections (4/5)
+> adding opencve_postgres Airflow connection...
+> done ✅
+> adding opencve_redis Airflow connection...
+> done ✅
+
+--------| Generate OpenCVE secret key (5/5)
+> updating OpenCVE secret key...
+> done ✅
+```
+
+Verify running containers:
+
+```
+docker ps
+CONTAINER ID   IMAGE                       COMMAND                  CREATED       STATUS                 PORTS                    NAMES
+9fb104f950f9   opencve-airflow-webserver   "/usr/bin/dumb-init …"   1 hour ago    Up 1 hour (healthy)    0.0.0.0:8080->8080/tcp   opencve-airflow-webserver-1
+00f090d9a66c   opencve-airflow-scheduler   "/usr/bin/dumb-init …"   1 hour ago    Up 1 hour (healthy)    8080/tcp                 opencve-airflow-scheduler-1
+8907176332df   opencve-airflow-worker      "/usr/bin/dumb-init …"   1 hour ago    Up 1 hour (healthy)    8080/tcp                 opencve-airflow-worker-1
+d9bea2556edc   postgres:15                 "docker-entrypoint.s…"   1 hour ago    Up 1 hour (healthy)    5432/tcp                 opencve-postgres-1
+672d2db6326d   nginx:trixie                "/docker-entrypoint.…"   1 hour ago    Up 1 hour              0.0.0.0:80->80/tcp       opencve-nginx-1
+da5a51bdb679   redis/redis-stack:latest    "/entrypoint.sh"         1 hour ago    Up 1 hour (healthy)    6379/tcp, 8001/tcp       opencve-redis-1
+e762d16ce6f2   opencve-webserver           "gunicorn opencve.ws…"   1 hour ago    Up 1 hour              8000/tcp                 opencve-webserver-1
+```
+
+## clone-repositories
+
+Clones the KB repositories into the `repositories` Docker volume. Skips repositories that are already present (ongoing updates are handled by the OpenCVE DAG).
+
+```
+./install.sh clone-repositories
+
+--------| Initialize OpenCVE repositories (1/1)
+> cloning opencve-kb...
+> done ✅
+> cloning opencve-nvd...
+> done ✅
+[...]
+```
+
+## import-opencve-kb
+
+Imports the [OpenCVE KB](../concepts/kb.md) into PostgreSQL. Skipped if CVEs are already present. Expect **10 to 30 minutes** depending on hardware.
+
+```
+./install.sh import-opencve-kb
+
+--------| Import OpenCVE KB inside the database, it can take 10 to 30 min (1/1)
+> importing CVEs...
+> done ✅
+```
+
+## start-opencve-dag
+
+Unpauses all OpenCVE DAGs: `opencve`, `summarize_reports`, `sync_weaknesses`, `clean_reports`.
+
+```
+./install.sh start-opencve-dag
+
+--------| Unpause Airflow DAGs (1/1)
+> unpausing opencve dag...
+> done ✅
+> unpausing summarize_reports dag...
+> done ✅
+> unpausing sync_weaknesses dag...
+> done ✅
+> unpausing clean_reports dag...
+> done ✅
+```
+
+!!! note
+    You may see a warning about `graphviz` not being installed. It does not impact OpenCVE.
+
+## create-superuser
+
+Creates the admin account for OpenCVE. Skipped if a superuser already exists.
+
+```
+$ ./install.sh create-superuser
+
+--------| Create OpenCVE admin user (1/2)
+> creating OpenCVE admin user...
+Username: xxx
+Email address: xxx
+Password:
+Password (again):
+Superuser created successfully.
+> done ✅
+
+--------| Auto confirm the created user (2/2)
+> confirming the created admin user...
+> done ✅
+```
+
+## install-end / bye
+
+Displays a summary of access URLs, installed version, and credentials. Run manually with `./install.sh bye`, or it runs automatically at the end of `start` and `upgrade`.
diff --git a/docs/deployment/operations.md b/docs/deployment/operations.md
@@ -0,0 +1,91 @@
+# Operations
+
+This page covers day-to-day operations: upgrading, resetting, and backing up your OpenCVE instance.
+
+## Backup
+
+Before any upgrade or destructive operation, back up your PostgreSQL database:
+
+```
+~/opencve/docker$ docker compose exec -T postgres pg_dump -U opencve opencve | gzip > opencve-backup-$(date +%Y%m%d).sql.gz
+```
+
+Adjust the username if you changed `POSTGRES_USER` in `docker/.env`.
+
+To restore from a backup:
+
+```
+~/opencve/docker$ gunzip -c opencve-backup-YYYYMMDD.sql.gz | docker compose exec -T postgres psql -U opencve opencve
+```
+
+## Upgrade
+
+Upgrading OpenCVE rebuilds the Docker images at the target version and runs database migrations.
+
+!!! warning
+    Back up your database before upgrading. Review the [Releases page](https://github.com/opencve/opencve/releases) for version-specific notes.
+
+Navigate to the `docker/` directory and run:
+
+```
+~/opencve/docker$ ./install.sh upgrade
+```
+
+This installs the latest `master` branch by default. The script will:
+
+1. Update `OPENCVE_VERSION` in `docker/.env`
+2. Pause all Airflow DAGs and wait for running tasks to finish (up to 5 minutes)
+3. Rebuild and restart the webserver, then apply migrations and collect static files
+4. Rebuild and restart the Airflow stack and nginx
+5. Verify that container versions match `OPENCVE_VERSION`
+6. Reconfigure Airflow connections and unpause all DAGs
+
+To upgrade to a specific release:
+
+```
+~/opencve/docker$ ./install.sh -r v3.0.0 upgrade
+```
+
+!!! tip
+    You can also pause / unpause DAGs manually:
+
+    ```
+    docker compose exec airflow-scheduler airflow dags pause opencve
+    docker compose exec airflow-scheduler airflow dags unpause opencve
+    ```
+
+!!! note
+    The application code is pulled from GitHub at build time via `OPENCVE_VERSION`. A `git pull` on your local clone only updates Docker configuration files and `install.sh` — it does not update the running application.
+
+    Since OpenCVE relies on Django and Airflow, review their upgrade documentation for additional guidance:
+
+    - [Django Upgrade Guide](https://docs.djangoproject.com/en/5.1/howto/upgrade-version/)
+    - [Airflow Upgrade Guide](https://airflow.apache.org/docs/apache-airflow/stable/installation/upgrading.html)
+
+## Reset
+
+The `reset` command stops the stack and removes all Docker volumes (database, repositories, static files). Configuration files on the host are kept.
+
+```
+~/opencve/docker$ ./install.sh reset
+```
+
+The script asks for confirmation (`Type 'yes' to confirm destruction`). Use `-y` to skip the prompt:
+
+```
+~/opencve/docker$ ./install.sh -y reset
+```
+
+After a reset, reinstall with:
+
+```
+./install.sh prepare && ./install.sh start
+```
+
+The KB import step alone can take 10 to 30 minutes on a fresh install.
+
+To also replace configuration files with fresh defaults:
+
+```
+./install.sh reset && ./install.sh -f prepare && ./install.sh start
+```
diff --git a/docs/js/redirects.js b/docs/js/redirects.js
@@ -0,0 +1,25 @@
+(function () {
+  var deploymentAnchors = {
+    upgrade: "operations/#upgrade",
+    configuration: "configuration/",
+    "list-of-commands": "install/",
+    "init-docker-stack": "install/#init-docker-stack",
+    "clone-repositories": "install/#clone-repositories",
+    "import-opencve-kb": "install/#import-opencve-kb",
+    "start-opencve-dag": "install/#start-opencve-dag",
+    "create-superuser": "install/#create-superuser",
+  };
+
+  if (!window.location.pathname.match(/\/deployment\/?$/)) {
+    return;
+  }
+
+  var hash = window.location.hash.slice(1);
+  var target = deploymentAnchors[hash];
+  if (!target) {
+    return;
+  }
+
+  var base = window.location.pathname.replace(/\/?$/, "/");
+  window.location.replace(base + target);
+})();
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -53,7 +53,7 @@ E: Unable to locate package git
 
 This means the container could not access the internet to fetch packages. This issue is related to your **host machine or Docker network configuration**, not to OpenCVE itself.
 
-You can work around the issue by forcing Docker to use the host network during the build. Edit your `docker-compose.yml` and add `network: host` under the `build` section of the service that fails, for example:
+You can work around the issue by forcing Docker to use the host network during the build. Edit your `docker-compose.yaml` and add `network: host` under the `build` section of the service that fails, for example:
 
 ```
 webserver:
@@ -85,7 +85,7 @@ Because this behavior was undocumented, OpenCVE’s scheduler failed to parse th
 
 The problem has been fixed in this [pull request](https://github.com/opencve/opencve/pull/604).
 
-You can upgrade OpenCVE and relaunch the failed DAG run in your Airflow scheduler instance. To do so, select it:
+You can upgrade OpenCVE with `./install.sh upgrade` (see [Operations → Upgrade](deployment/operations.md#upgrade)) and relaunch the failed DAG run in your Airflow scheduler instance. To do so, select it:
 
 ![Troubleshooting Select DAGRun](images/troubleshooting/select-dagrun.png){.center style="width:100%"}