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:
./install.sh
Note
This command installs the latest stable release. If you want to install the very latest available commit, use ./install -r master
.
It will prepare your environment and run all the services needed by OpenCVE.
Info
The script will configure your OpenCVE instance with default settings. If you want to customize them you can:
- run the
./install.sh prepare
command, it will prepare the configuration files for you (you just have to launch it once) - customize your settings
- run the
./install.sh start
command to start all the components
List of Commands
You can run dedicated commands of the install.sh
script if you want to proceed step by step:
add-config-files : Add default configurations files
start-docker-stack : Start docker compose stack
clone-repositories : Clone KB repositories
import-opencve-kb : Import OpenCVE KB inside local database
start-opencve-dag : Unpause OpenCVE Dag in Airflow
add-config-files
This command initialize the default configuration files.
./install.sh add-config-files
--> Adding airflow config file
--> Adding Django settings file
--> Copying .env file for docker compose
--> Copying opencve.conf.template for Nginx
/!\ Don't forget to update the .env and settings.py files with your inputs before starting the docker compose stack:
Docker .env: ./.env
Webserver .env: ../web/opencve/conf/.env
Django settings: ../web/opencve/conf/settings.py
Airflow settings: ../scheduler/airflow.cfg
Note
You can refer to the configuration section of this documentation to customize OpenCVE settings.
set-airflow-start-date
This command is used to setup the start day at today inside the Airflow configuration file, it needs to be done before starting the stack:
./install.sh set-airflow-start-date
--> Configuring start_start in Airflow configuration file for today
start_date = 2024-04-02
start-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 start-docker-stack
--> Get PG ENV variables from docker compose env file
--> Starting Docker compose stack
[...]
--> Adding Airflow connections
[...]
--> Updating OpenCVE secret key
[...]
--> Restarting webserver
[...]
--> Collecting static files from Django webserver
[...]
You can check if the docker instances are running correctly:
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c05be1dcd8a5 opencve-airflow-webserver "/usr/bin/dumb-init …" 9 minutes ago Up 7 minutes (healthy) 0.0.0.0:8080->8080/tcp airflow-webserver
45dde77ffdd7 opencve-airflow-worker "/usr/bin/dumb-init …" 9 minutes ago Up 7 minutes (healthy) 8080/tcp airflow-worker
08302ce6d0f7 opencve-airflow-scheduler "/usr/bin/dumb-init …" 9 minutes ago Up 7 minutes (healthy) 8080/tcp airflow-scheduler
041ad3546c46 opencve-webserver "gunicorn opencve.ws…" 9 minutes ago Up 9 minutes 8000/tcp webserver
5e0d20559b01 nginx:bookworm "/docker-entrypoint.…" 9 minutes ago Up 9 minutes 0.0.0.0:80->80/tcp nginx
b91f0cda0c40 redis/redis-stack:latest "/entrypoint.sh" 9 minutes ago Up 9 minutes (healthy) 6379/tcp, 8001/tcp redis
2be9eeed7d6c postgres:15 "docker-entrypoint.s…" 9 minutes ago Up 9 minutes (healthy) 5432/tcp postgres
clone-repositories
This command is used to clone the repositories needed for opencve to work:
./install.sh clone-repositories
--> Cloning OpenCVE needed repositories
Cloning into '/home/airflow/repositories/opencve-kb'...
[...]
Cloning into '/home/airflow/repositories/opencve-nvd'...
[...]
Cloning into '/home/airflow/repositories/opencve-redhat'...
[...]
Cloning into '/home/airflow/repositories/cvelistV5'...
[...]
Cloning into '/home/airflow/repositories/vulnrichment'...
[...]
You can now reach OpenCVE web portal at your configured IP/FQDN on the port 80 and the Airflow webserver on the port 8080.
create-superuser
This command creates the superuser needed to access to the admin part of your OpenCVE website:
$ ./install.sh create-superuser
--> Creating superuser on OpenCVE
Username: xxx
Email address: xxx
Password:
Password (again):
Superuser created successfully.
--> Get PG ENV variables from docker compose env file
--> Confirm the new user
INSERT 0 1
import-opencve-kb
This command imports the OpenCVE KB in your database:
./install.sh import-opencve-kb
--> Importing OpenCVE KB inside the database, this can take 15 to 30min.
Parsing the OpenCVE KB repository (/app/repositories/opencve-kb)
Found 260248 CVEs, adding them in database...
Done in 768.394s
start-opencve-dag
This command unpauses the main DAG so Airflow can execute the opencve
workflow:
./install.sh start-opencve-dag
--> Unpausing the dag
Dag: opencve, paused: False
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 timeOPENCVE_*_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):
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
:
~/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:
docker compose up -d --build
After the containers are updated, execute the following Django commands to collect static files and apply any database migrations:
docker exec webserver python manage.py collectstatic
docker exec webserver python manage.py migrate
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: