Skip to content

Deployment & Setup

Tip

The easiest way to run OpenCVE is to use OpenCVE Cloud (no installation, configuration or maintenance needed).

You can install the complete OpenCVE stack with Docker. It will contain all the services you need to run OpenCVE (Django webserver, Airflow services, Redis, PostgreSQL).

Requirements

You need to have your server installed with Debian OS or equivalent, Docker v25.0.x at least and the docker-compose plugin.

The procedure is run as root and has been tested with Debian 11 and Debian 12.

The minimum requirement for the host is 4 cores and 4 GB RAM, the disk usage will be around 25GB or 30GB. The instance d2-8 from OVHcloud is a good fit to start.

Installation

Clone the OpenCVE repository and go into the docker/ directory.

Then run the install.sh script:

~/opencve/docker$ ./install.sh

Note

This command installs the latest stable release. If you want to install the very latest available commit, use ./install.sh -r master. For details about the command: ./install.sh -h.

As a first step, it will prepare your environment with the default configuration files:

🟒 The default configuration files are all set, you can update them now if you want before starting the entire docker stack:
 Docker compose  : ./.env
 Webserver       : ../web/opencve/conf/.env
 Airflow         : ../scheduler/airflow.cfg
 Django          : ../web/opencve/conf/settings.py

See the documentation for details: https://docs.opencve.io/deployment/#configuration

 πŸš€ You can now run: ./install.sh start

Info

To customize the default settings before starting the OpenCVE docker stack, you can refer to our configuration section of this documentation.

Then you can run the second part of the installation:

./install.sh start

It will proceed with all the installation steps automatically. When all the steps are done, the installation will end like this:

🟒 Everything is set up, you can now access to OpenCVE locally:

- on port 80 for OpenCVE web instance
 You can login with your account and password set at the previous step 'Create OpenCVE admin user'.
 You can set a new one with the following command: ./install.sh create-superuser
 The installed version is: v2.0.0

- on port 8080 for OpenCVE Airflow scheduler
 You can login with the username "xxx" and password "xxx".

 πŸ‘‹ Installation complete! Thank you for choosing OpenCVE! 

List of Commands

You can run dedicated commands of the install.sh script if you want to proceed step by step once the configuration files are set :

 init-docker-stack
 clone-repositories
 create-superuser
 import-opencve-kb
 start-opencve-dag
 install-end

Note

For details about Γ’each command: ./install -h.

init-docker-stack

This command is used to bootstrap the whole OpenCVE stack.

It will create the containers, add the airflow connections, collect the web static files, update the OPENCVE_SECRET_KEY and create the needed database tables and procedures:

./install.sh init-docker-stack

--------| Docker compose up
> starting OpenCVE docker stack...
[...]
 βœ” Network opencve_default        Created                                                                                                                                     0.2s
 βœ” Volume "opencve_staticfiles"   Created                                                                                                                                     0.0s
 βœ” Volume "opencve_postgres-db"   Created                                                                                                                                     0.0s
 βœ” Volume "opencve_repositories"  Created                                                                                                                                     0.0s
 βœ” Container webserver            Started                                                                                                                                     1.1s
 βœ” Container redis                Healthy                                                                                                                                     6.6s
 βœ” Container nginx                Started                                                                                                                                     1.2s
 βœ” Container postgres             Healthy                                                                                                                                     6.6s
 βœ” Container airflow-init         Exited                                                                                                                                     22.5s
 βœ” Container airflow-webserver    Started                                                                                                                                    22.9s
 βœ” Container airflow-scheduler    Started                                                                                                                                    22.9s
 βœ” Container airflow-worker       Started                                                                                                                                    22.9s
> done βœ…

--------| Collect static files from Django webserver
> collecting latest static files...
> done βœ…

--------| Apply Django webserver DB migration
> migrating DB schema with latest changes...
> done βœ…

--------| Airflow connections
> adding Postgresql Airflow connection...
> done βœ…
> adding Redis Airflow connection...
> done βœ…

--------| OpenCVE secret key
> cleaning old OpenCVE secret key...
> done βœ…
> updating with new OpenCVE secret key...
> done βœ…

--------| Webserver restart
> restarting webserver docker instance...
> done βœ…

You can check if the docker instances are running correctly:

docker ps
CONTAINER ID   IMAGE                       COMMAND                  CREATED              STATUS                        PORTS                                                                      NAMES
b6c6ff28f06d   opencve-airflow-worker      "/usr/bin/dumb-init …"   About a minute ago   Up About a minute (healthy)   8080/tcp                                                                   airflow-worker
7598b5df72f6   opencve-airflow-webserver   "/usr/bin/dumb-init …"   About a minute ago   Up About a minute (healthy)   0.0.0.0:8080->8080/tcp, :::8080->8080/tcp                                  airflow-webserver
004246bc3ff6   opencve-airflow-scheduler   "/usr/bin/dumb-init …"   About a minute ago   Up About a minute (healthy)   8080/tcp                                                                   airflow-scheduler
e4c55d1022ac   nginx:bookworm              "/docker-entrypoint.…"   About a minute ago   Up About a minute             0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   nginx
50a2d2f33f90   postgres:15                 "docker-entrypoint.s…"   About a minute ago   Up About a minute (healthy)   5432/tcp                                                                   postgres
ec7671ac36b3   opencve-webserver           "gunicorn opencve.ws…"   About a minute ago   Up About a minute             8000/tcp                                                                   webserver
3b32b8df0a9a   redis/redis-stack:latest    "/entrypoint.sh"         About a minute ago   Up About a minute (healthy)   6379/tcp, 8001/tcp                                                         redis

clone-repositories

This command is used to clone the repositories needed for OpenCVE to work:

./install.sh clone-repositories

--------| Setup OpenCVE repositories
> cloning opencve-kb...
Cloning into '/home/airflow/repositories/opencve-kb'...
Updating files: 100% (277971/277971), done.
> done βœ…
> cloning opencve-nvd...
Cloning into '/home/airflow/repositories/opencve-nvd'...
Updating files: 100% (277955/277955), done.
> done βœ…
> cloning opencve-redhat...
Cloning into '/home/airflow/repositories/opencve-redhat'...
Updating files: 100% (35928/35928), done.
> done βœ…
> cloning cvelistV5...
Cloning into '/home/airflow/repositories/cvelistV5'...
Updating files: 100% (278007/278007), done.
> done βœ…
> cloning vulnrichment...
Cloning into '/home/airflow/repositories/vulnrichment'...
Updating files: 100% (61734/61734), done.
> done βœ…

import-opencve-kb

This command imports the OpenCVE KB in your database:

./install.sh import-opencve-kb

--------| Import OpenCVE KB inside the database, this can take 10 to 30min.
> importing CVEs...
Parsing the OpenCVE KB repository (/app/repositories/opencve-kb)
Found 277970 CVEs, adding them in database...
Done in 659.365s
> done βœ…

start-opencve-dag

This command unpauses the main DAG so Airflow can execute the opencve workflow:

./install.sh start-opencve-dag

--------| Unpause Airflow OpenCVE dag to start to update local repositories and alerts
> unpausing OpenCVE Airflow dag...
> done βœ…

Note

You may have the following warning: /home/airflow/.local/lib/python3.11/site-packages/airflow/utils/dot_renderer.py:28 UserWarning: Could not import graphviz. Rendering graph to the graphical format will not be possible. It doesn't impact OpenCVE as this library is not used.

create-superuser

This command creates the superuser needed to access to the admin part of your OpenCVE website:

$ ./install.sh create-superuser

--------| Create admin user on OpenCVE
> creating OpenCVE admin user...
Username: xxx
Email address: xxx
Password:
Password (again):
Superuser created successfully.
> done βœ…

--------| Auto confirm the created user
> confirming the created admin user...
> done βœ…

Configuration

docker/.env

We recommend to verify and update your docker .env file. It's advised to change the following variables:

  • POSTGRES_PASSWORD
  • _AIRFLOW_WWW_USER_USERNAME
  • _AIRFLOW_WWW_USER_PASSWORD
  • AIRFLOW__CORE__FERNET_KEY

Warning

You need to set the above env variables before starting OpenCVE stack as they are configured at the first run of docker compose.

To customize the fernet key: how to generate a new fernet key.

web/opencve/conf/.env

This file exposes important settings used by the OpenCVE webserver:

  • OPENCVE_DATABASE_URL: the URI of the database. You need to update it if you have changed some of the postgresql parameters in the docker compose env file. The postgresql connection parameters need to be the same in both web and docker compose .env files.
  • OPENCVE_SECRET_KEY: this variable has to be replaced with a new secret when the web server is up the first time
  • OPENCVE_*_REPO_PATH: the paths of the repositories (KB, Mitre, NVD...)
  • OPENCVE_V1_DATABASE: the URI of an OpenCVE v1 instance (used for data migration)

web/opencve/conf/settings.py

This file is used to override the Django default settings defined in web/opencve/conf/base.py.

You can check the list of Django settings here to customize your OpenCVE instance.

scheduler/airflow.cfg

This file is used to configure the Airflow scheduler of OpenCVE.

You can check the list of Airflow configurations here to customize your Airflow instance.

Info

You can refer to this dedicated guide to configure SMTP settings and enable email sending.

Upgrade

Upgrading OpenCVE involves updating the Docker containers and running specific maintenance commands to ensure everything functions correctly.

Important

Before proceeding with the upgrade, we strongly recommend making a backup of your database to prevent any potential data loss. Additionally, review the Releases page for specific details and instructions about each new version.

Access the Airflow webserver and pause the opencve DAG to prevent it from running during the upgrade (ensure no DAG runs are in progress before pausing):

Pause DAG

Tip

You can also use the following commands to pause / unpause the DAG:

docker exec airflow-scheduler airflow dags pause opencve
docker exec airflow-scheduler airflow dags unpause opencve

Navigate to the OpenCVE project directory and pull the latest updates:

cd opencve && git pull

Then navigate to the docker folder and update the OPENCVE_VERSION variable of the .env:

cd docker
~/opencve/docker$ grep OPENCVE_VERSION .env
OPENCVE_VERSION=v2.0.0

Note

You can select the desired version in the releases list, or you can use master to install the very latest available commit of OpenCVE.

Update the Docker containers to reflect the latest code and dependencies, using install.sh:

~/opencve/docker$ ./install.sh docker-build

--------| Docker compose build
> building OpenCVE docker images...
[...]
> done βœ…

After the container images are built, execute the docker-up command that will up the containers and with Django, it will collect static files and apply any database migrations:

~/opencve/docker$ ./install.sh docker-up

--------| Docker compose up
> starting OpenCVE docker stack...
[+] Running 8/8
 βœ” Container redis              Healthy                                                                                                                                                              3.9s
 βœ” Container nginx              Running                                                                                                                                                              0.0s
 βœ” Container webserver          Started                                                                                                                                                              3.7s
 βœ” Container postgres           Healthy                                                                                                                                                              3.9s
 βœ” Container airflow-init       Exited                                                                                                                                                              22.0s
 βœ” Container airflow-worker     Started                                                                                                                                                             22.5s
 βœ” Container airflow-webserver  Started                                                                                                                                                             22.5s
 βœ” Container airflow-scheduler  Started                                                                                                                                                             22.4s
> done βœ…

--------| Collect static files from Django webserver
> collecting latest static files...
> done βœ…

--------| Apply Django webserver DB migration
> migrating DB schema with latest changes...
> done βœ…

You can finally unpause the opencve DAG to to restart the periodic tasks and resume normal operations.

Note

Since OpenCVE relies on Django and Airflow, it is good practice to review their upgrade documentation for additional guidance: