# Installation

This section provides detailed instructions for installing the software and its dependencies.

## Prerequisites

Valkey (or Redis) must be built from source next to the codebase. Kvrocks can be
built the same way, installed system-wide, or run with Docker: `storage/run_kvrocks.sh`
tries them in that order. By default, the standard scripts of *Vulnerability-Lookup* expect the following directory structure:

```bash
/vulnerability-lookup   # Vulnerability-Lookup codebase
/kvrocks
/valkey
```

The *Vulnerability-Lookup* launcher provides configuration for both Valkey and Kvrocks.

:::{note}
- The script `./vulnerability-lookup/storage/run_kvrocks.sh` runs `./kvrocks/build/kvrocks`
- The script `./vulnerability-lookup/cache/run_redis.sh` runs `./valkey/src/valkey-server`
:::

### Valkey

[Valkey](https://valkey.io) is an open-source (BSD-licensed) in-memory data structure store used as a database, cache, and message broker.

:::{note}
Clone and build Valkey **in the same parent directory** as this repository — not inside it.
:::

Install required packages:

```bash
sudo apt-get update
sudo apt install build-essential tcl
```

Then install Valkey:

```bash
git clone https://github.com/valkey-io/valkey
cd valkey
git checkout 9.0.1
make
# Optionally, run the tests:
make test
cd ..
```

### Kvrocks

[Kvrocks](https://github.com/apache/kvrocks) is a distributed key value NoSQL database that uses [RocksDB](https://rocksdb.org/) as storage engine and is compatible with Redis protocol.
Kvrocks intends to decrease the cost of memory and increase the capacity while compared to Redis.

:::{note}
Build Kvrocks from source one directory up from vulnerability-lookup, or install it
system-wide. Without either, `storage/run_kvrocks.sh` starts the apache/kvrocks Docker container.
:::

Install the required packages:

```bash
sudo apt-get update
sudo apt install git gcc g++ make cmake autoconf automake libtool python3 libssl-dev
```

Then clone and build Kvrocks:

```bash
git clone https://github.com/apache/kvrocks.git
cd kvrocks
git checkout v2.14.0
./x.py build
cd ..
```

### Node.js and npm

The frontend libraries of the website (JavaScript and CSS) are declared in
`package.json` and installed with npm, which requires Node.js >= 18. Nothing
is compiled — the postinstall step only copies the pre-built dist files — so
the distribution packages are sufficient.

On Debian 12 (Bookworm) or later:

```bash
sudo apt install nodejs npm
```

On distributions whose packaged Node.js is older than 18, install a current
LTS release from the
[NodeSource repository](https://github.com/nodesource/distributions), or use
your preferred Node.js version manager.

Verify the installed version:

```bash
node --version
```

No build toolchain is needed: npm only downloads the libraries, and the
`postinstall` step copies the served files into `website/web/static/`.

### Meilisearch

Meilisearch is an optional dependency for Vulnerability-Lookup that will enable fulltext-search through the Web UI. See how to set it up in
chapter about [fulltext-search](fulltextsearch.md).

### Import CSAF Sources

1. Build the [CSAF support tools](https://github.com/gocsaf/csaf?tab=readme-ov-file#build-from-sources).
   (Requires Go >= 1.23)

2. Verify the downloader exists and works:

```bash
$ ./bin-linux-amd64/csaf_downloader --version
3.6.1-1-g00a5614
```

   Version 2.1.0 or later is required: the feeders identify the instance to
   each provider with `-H`, which older builds reject.

3. Add the **full path** to the downloader binary in `config/generic.json` under the key `csaf_downloader_path`.

## Source Code

Clone *Vulnerability-Lookup* with its submodules:

```bash
git clone --recursive https://github.com/vulnerability-lookup/vulnerability-lookup.git
```

## Dependencies

From within the cloned directory, install the Python dependencies:

```bash
poetry install
```

Install the frontend dependencies (JavaScript and CSS libraries declared in
`package.json`). This requires [Node.js](https://nodejs.org) >= 18 with npm:

```bash
npm ci --omit=dev
```

:::{note}
The `postinstall` script of `package.json` runs
`tools/copy_frontend_assets.py`, which copies the allowlisted library files
from `node_modules` into `website/web/static/npm_components`, from which the
website serves them. `poetry run update` runs `npm ci` automatically on
subsequent updates.
:::

Initialize the environment file:

```bash
echo VULNERABILITYLOOKUP_HOME="$(pwd)" >> .env
```

:::{note}
`VULNERABILITYLOOKUP_HOME` must match the name defined in `vulnerabilitylookup/default/__init__.py`.
:::

Initialize submodules (this may take a while):

```bash
git submodule update --init
```

## Configuration

### Generic Configuration

Copy the sample configuration files and adjust them to your needs:

```bash
cp config/generic.json.sample config/generic.json
cp config/logging.json.sample config/logging.json
cp config/website.py.sample config/website.py
cp config/stream.json.sample config/stream.json
cp config/fulltextsearch.json.sample config/fulltextsearch.json
cp config/cpe.json.sample config/cpe.json
cp config/vulniverse.json.sample  config/vulniverse.json
cp config/patch2vuln.json.sample  config/patch2vuln.json
```

### Modules

Request your API keys for NVD and VARIoT:

- [NVD API key](https://nvd.nist.gov/developers/request-an-api-key)
- [VARIoT API key](https://www.variotdbs.pl/api/register)

Then copy and edit the module configuration file:

```bash
cp config/modules.cfg.sample config/modules.cfg
```

Enable or disable a feeder with `enabled = true` or `false` in its section.
A feeder without `enabled` is on. Some feeders are disabled in the sample file.

### GCVE publication as a GNA

This step is optional but recommended for users who want to contribute to the GCVE ecosystem by publishing vulnerability information.
One of the main goals of the GCVE ecosystem is to make vulnerability publication simple, independent, and decentralized.
Vulnerability-Lookup can be used to publish vulnerability information as a GNA (Global Name Authority) in the GCVE ecosystem, making it available to all GCVE participants and consumers.
For this your instance must be publicly accessible and meet the requirements defined in the GCVE documentation.

:::{note}
If your oranization has a GNA idenfier you must set your GNA ID in the configuration file generic.json under the key `local_instance_name`.
More information about GCVE publication as a GNA can be found [here](https://gcve.eu/publishing-vulnerability-information/#3-configure-your-instance).
:::

### User Accounts

Enable user accounts, comments, and bundles by setting `"user_accounts": true` in `config/generic.json`.

Create a PostgreSQL user and database:

```bash
sudo apt install postgresql
sudo -u postgres createuser -P <username>
Enter password for new role: <password>
sudo -u postgres createdb <database> -O <username>
```

Update `config/website.py` with the correct credentials under `DB_CONFIG_DICT`,
and set `DATABASE_NAME` (default: `vulnlookup`).

Initialize the database:

```bash
poetry run flask --app website.app db_init             # initialize database
poetry run flask --app website.app db stamp head       # create alembic_version table
poetry run flask --app website.app seed-rbac           # create default roles and permissions
```

Create the first admin user:

```bash
poetry run flask --app website.app create_admin --login admin --email admin@example.org --password <password>
```

Optionally, import OSI licenses and programming languages:

```bash
poetry run flask --app website.app import_osi_approved_licenses
poetry run flask --app website.app import_languages
```

Initialize the local GCVE registry:

```bash
poetry run flask --app website.app update_gcve_registry
```

## Usage

Start the application (from the project directory):

```bash
poetry run start
```

:::{note}
On first launch, the system will download and process the complete archive from all feeds.
This may require substantial CPU time. Subsequent runs will be much lighter.
:::

Stop the application:

```bash
poetry run stop
```

By default, the web interface is available at:
**http://0.0.0.0:10001**

Use the web UI or API to explore and interact with the system.

The statistics and scorecard pages are filled by prepared figures. Once the feeders
and the KEV catalogues have been imported, run these once, then add them to cron
([the four cron lines and what each does](command-line-interface.md#prepared-statistics-figures)):

```bash
poetry run index_vulnerabilities
poetry run euvd --stats-scan --stats-source cvelistv5
poetry run scorecard --window-only
poetry run kev_scorecard
```

To update the tool:

```bash
poetry run update
```

## Launching the Website with systemd

:::{note}
This is an alternative startup method.
The website is automatically launched with the `start` command.
:::

Create the file `/etc/systemd/system/vulnerability-lookup-web.service`:

```ini
[Unit]
Description=Vulnerability-Lookup Web service
After=network.target

[Service]
Type=forking
User=<system user used to install Vulnerability-Lookup>
Group=<group of the user used to install Vulnerability-Lookup>
WorkingDirectory=<path to the cloned repository>
Environment="VULNERABILITYLOOKUP_HOME=<path to the cloned repository>"
Environment="PATH=<path-to-virtualenv>/bin:/home/<user>/.local/bin:/usr/bin"
ExecStart=/bin/bash -c "exec poetry run start"
ExecStop=/bin/bash -c "exec poetry run stop"
StandardOutput=append:/var/log/vulnerability-lookup_message.log
StandardError=append:/var/log/vulnerability-lookup_error.log

[Install]
WantedBy=multi-user.target
```

Then reload and enable the service:

```bash
sudo systemctl daemon-reload
sudo systemctl enable vulnerability-lookup-web.service
sudo systemctl start vulnerability-lookup-web.service
systemctl status vulnerability-lookup-web.service
```

To follow the service logs live:

```bash
sudo journalctl -u vulnerability-lookup-web.service -f
```
