# Installation

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

## Prerequisites

You need to have both Valkey and Kvrocks built from source and available locally.
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}
Kvrocks should be installed from the source, and the repository must be in one directory up as the one you will be cloning vulnerability-lookup into.
It is also possible to make the apache/kvrocks docker container available to use.
:::

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 ..
```

### 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.5.1
```

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 dependencies:

```bash
poetry install
```

Initialize the environment file:

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

:::{note}
`VULNERABILITYLOOKUP_HOME` must match the name defined in `vulnerability-lookup/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
```

### 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
```

You can enable or disable individual feeders by setting `enabled = false` in their respective configuration sections.
By default, all feeders are enabled.

### 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
```

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.

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
```