A complete guide to setting up your host machine for Visionaire4 — NVIDIA driver, Docker Engine, NVIDIA Container Toolkit, Docker Compose, and TimescaleDB.

Install Dependencies

Before you can run Visionaire4, your host machine needs a handful of system-level pieces in place: a working NVIDIA driver, Docker, the NVIDIA Container Toolkit, Docker Compose, and a database. This guide installs each of them in order. Follow it top to bottom on a fresh Ubuntu machine and you'll have a host that's fully ready for the Pre-requisite Installation guide.

Assumptions for this guide:

OS: Ubuntu 22.04 or later (other Linux distributions follow similar steps)
Access: sudo privileges
Network: the machine can reach the public internet for package downloads
GPU: an NVIDIA card is physically installed (skip section 2 if you're going CPU-only)

1. Update the System

Always start with a clean, up-to-date package index:

sudo apt update && sudo apt upgrade -y

Reboot if the upgrade installed a new kernel:

sudo reboot

2. NVIDIA Driver

Skip this section if you're running Visionaire4 in CPU mode.

Check that your GPU is detected

lspci | grep -i nvidia

You should see your NVIDIA card listed. If nothing appears, confirm the card is seated correctly before continuing.

Remove any existing NVIDIA packages

Mixing driver versions causes hard-to-debug issues. Start clean:

sudo apt-get purge -y 'nvidia-*' 'libnvidia-*'
sudo apt-get autoremove -y

Install the recommended driver

Ubuntu can pick the right driver for your card automatically:

sudo ubuntu-drivers install

Or, if you prefer to pin a specific version (Visionaire4 needs 525 or later):

sudo apt install -y nvidia-driver-535

Reboot

The driver only loads after a fresh boot:

sudo reboot

Verify

Once the machine is back, run:

nvidia-smi

You should see a table listing your GPU, driver version, and CUDA version. If it errors out, check dmesg | grep -i nvidia for clues.

3. Docker Engine

Visionaire4 ships as a Docker image, so Docker Engine is non-negotiable.

Remove old Docker packages

sudo apt-get remove -y docker docker-engine docker.io containerd runc

Add Docker's official repository

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine, CLI, and the Compose plugin

sudo apt-get update
sudo apt-get install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

The docker-compose-plugin package gives you docker compose (Compose v2) — that's all you need for the next sections.

Run Docker without `sudo`

Add your user to the docker group so you don't need to prefix every command with sudo:

sudo groupadd docker 2>/dev/null || true
sudo usermod -aG docker $USER

Log out and log back in (or run newgrp docker) for the group change to take effect.

Verify

docker run --rm hello-world
docker compose version

The first command pulls a tiny image and prints a "Hello from Docker!" message. The second prints the Compose v2 version.

4. NVIDIA Container Toolkit

This is what makes the --gpus all flag work — it lets Docker containers see your GPU. Skip this section if you're going CPU-only.

Add the NVIDIA repository

distribution=$(. /etc/os-release; echo $ID$VERSION_ID)

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list > /dev/null

Install the toolkit

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

Configure Docker to use it

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Verify

Run a CUDA container and check it can see your GPU:

docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

You should see the same GPU table you got from running nvidia-smi on the host. If you do, the toolkit is working.

5. TimescaleDB

Visionaire4 stores events in a PostgreSQL-compatible database. TimescaleDB is a PostgreSQL extension optimized for time-series workloads — ideal for high-volume event ingestion. Running it as a Docker container is the simplest path.

Pull and run TimescaleDB

docker run -d \
  --name timescaledb \
  --restart always \
  -e POSTGRES_PASSWORD=nfvisionaire123 \
  -e POSTGRES_DB=postgres \
  -e POSTGRES_USER=postgres \
  -e PGDATA=/var/lib/postgresql/data/pgdata \
  -p 5432:5432 \
  -v /var/lib/postgresql/data:/var/lib/postgresql/data \
  timescale/timescaledb:latest-pg18

The timescale/timescaledb:latest-pg18 image is PostgreSQL 18 with the latest TimescaleDB pre-installed and ready to use. If you need to pin to a different PostgreSQL version, swap the tag (e.g. latest-pg17, latest-pg16).

Enable the TimescaleDB extension

Connect to the database and enable the extension on the schema you'll be using:

docker exec -it timescaledb psql -U postgres -d postgres \
  -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"

Verify

docker exec -it timescaledb psql -U postgres -d postgres \
  -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'timescaledb';"

You should see timescaledb listed with its version.

Add the TimescaleDB repository

sudo apt install -y gnupg postgresql-common apt-transport-https lsb-release wget
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

echo "deb https://packagecloud.io/timescale/timescaledb/ubuntu/ $(lsb_release -c -s) main" | \
  sudo tee /etc/apt/sources.list.d/timescaledb.list

wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | \
  sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/timescaledb.gpg

Install TimescaleDB

sudo apt update
sudo apt install -y timescaledb-2-postgresql-18

Tune PostgreSQL for TimescaleDB

sudo timescaledb-tune --quiet --yes
sudo systemctl restart postgresql

Enable the extension

sudo -u postgres psql -d postgres \
  -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"

Change the default password (nfvisionaire123) before exposing this database to anything beyond localhost.

You're Ready

If every verification step above passed, your host is fully prepared. You should now have:

A working NVIDIA driver (nvidia-smi works)
Docker Engine and Docker Compose v2 (docker run hello-world works)
NVIDIA Container Toolkit (docker run --gpus all ... nvidia-smi works)
TimescaleDB running on port 5432

Continue to the next guide to install Visionaire4 itself:

Pre-requisite Installation

Install and configure Visionaire4 on your prepared host.

Install Dependencies

Pre-requisite Installation

On this page