Overview

The Serpentua Data Validation Platform (DVP) is a web-based file integrity monitoring system. It continuously scans files and directories using SHA-256 checksums, alerts you when files are modified or deleted, and provides reporting and export capabilities.

DVP is delivered as a Docker Compose application consisting of two containers:

Prerequisites

Before you begin, confirm the following:

• ☐Ubuntu 20.04, 22.04, or 24.04 LTS (64-bit) — server or desktop edition
• ☐A user account with sudo privileges
• ☐Internet access (to pull Docker images and Python packages)
• ☐At least 2 GB of free disk space for images and the MySQL data volume
• ☐Ports 8443 and 3306 not already in use
• ☐The DVP project files (folder serpentua-dvp-docker/)

System Preparation

Update your package index and upgrade existing packages before installing anything new.

$ sudo apt update && sudo apt upgrade -y

Install a few utilities that are used during the Docker installation process:

$ sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release \
    git

Install Docker & Docker Compose

4.1 — Add Docker's GPG key and repository

# Add Docker's official GPG key
$ 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

# Add the Docker stable repository
$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4.2 — Install Docker Engine and Docker Compose plugin

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

4.3 — Verify the installation

$ docker --version
Docker version 27.x.x, build xxxxxxx

$ docker compose version
Docker Compose version v2.x.x

4.4 — Allow your user to run Docker without sudo

Add your account to the docker group so you do not need to prefix every Docker command with sudo. Log out and back in after running this command for it to take effect.

$ sudo usermod -aG docker $USER
$ newgrp docker   # apply group change in the current session

4.5 — Enable Docker to start on boot

$ sudo systemctl enable docker
$ sudo systemctl start docker

Get the Application Source

Copy the serpentua-dvp-docker project folder to your Ubuntu machine. Choose the method that suits your situation:

Option A — Clone from a Git repository

$ git clone <repository-url> ~/serpentua-dvp
$ cd ~/serpentua-dvp

Option B — Copy an existing folder via SCP

Run the following from your local machine (e.g., Windows with WSL or a separate workstation) to push the folder to the Ubuntu server:

$ scp -r /path/to/serpentua-dvp-docker \
    user@<server-ip>:~/serpentua-dvp

Option C — Upload as a ZIP and extract

# Install unzip if not already present
$ sudo apt install -y unzip

# Extract the archive
$ unzip serpentua-dvp-docker.zip -d ~/serpentua-dvp
$ cd ~/serpentua-dvp/serpentua-dvp-docker

After this step you should be inside a directory that contains, at a minimum: Dockerfile, docker-compose.yml, requirements.txt, runserver.py, .env, and the dvp/ folder.

Configure the Environment

All runtime settings are read from the .env file in the project root. Open it with any text editor:

$ nano .env

The file contains the following variables:

DB_USER=dvp
DB_PASSWORD=ChangeMe!123
DB_NAME=dvp_app
DB_HOST=db
MYSQL_ROOT_PASSWORD=rootpassword
SERVER_HOST=0.0.0.0
SERVER_PORT=8443

Save the file after making your changes (Ctrl+O then Ctrl+X in nano).

Build & Launch the Application

From the project root directory, run:

$ docker compose up -d --build

Docker will:

Watching the logs in real time

# Follow logs for all containers
$ docker compose logs -f

# Follow logs for the app container only
$ docker compose logs -f app

Verify the Installation

Check container status

$ docker compose ps

Both containers should show a status of running. The db container should show healthy.

NAME                    IMAGE          STATUS          PORTS
dvp-app-1               dvp-app        Up 2 minutes    0.0.0.0:8443->8443/tcp
dvp-db-1                mysql:8.0      Up 2 minutes    0.0.0.0:3306->3306/tcp (healthy)

Access the web interface

Open a browser and navigate to:

http://localhost:8443

Or, from another machine on the same network:

http://<server-ip-address>:8443

File Path Mapping

The Docker Compose file mounts the Ubuntu host's root filesystem into the container at /host (read-only). When you add asset paths inside the DVP UI, you must use the container path, not the host OS path.

Firewall & Remote Access

If Ubuntu's Uncomplicated Firewall (ufw) is enabled, you need to allow traffic on port 8443 so other machines can reach the DVP web interface.

# Check whether ufw is active
$ sudo ufw status

# Allow DVP web traffic
$ sudo ufw allow 8443/tcp

# Optional — allow SSH if you haven't already
$ sudo ufw allow OpenSSH

# Apply and confirm
$ sudo ufw enable
$ sudo ufw status verbose

Auto-Start on Boot

Both containers already have restart: unless-stopped set in docker-compose.yml, which means they will restart automatically after a Docker daemon restart. Because Docker itself is set to start on boot (Section 4.5), the application will come back up after a reboot without any additional configuration.

To confirm the behaviour, simulate it:

$ sudo reboot

# After the server comes back, verify containers resumed
$ docker compose -f ~/serpentua-dvp/docker-compose.yml ps

Optional — systemd service unit

If you prefer an explicit systemd service that manages the Docker Compose stack, create the following unit file:

$ sudo nano /etc/systemd/system/dvp.service

[Unit]
Description=Serpentua DVP
After=docker.service
Requires=docker.service

[Service]
WorkingDirectory=/home/YOUR_USER/serpentua-dvp
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
Restart=always
User=YOUR_USER

[Install]
WantedBy=multi-user.target

$ sudo systemctl daemon-reload
$ sudo systemctl enable dvp
$ sudo systemctl start dvp

Day-to-Day Management

Updating the application

$ git pull                      # if using git
$ docker compose down
$ docker compose up -d --build

Database backups

$ docker compose exec db \
    mysqldump -u dvp -p dvp_app > dvp_backup_$(date +%Y%m%d).sql

Troubleshooting

Container fails to start — "port already in use"

Another process is already listening on port 8443 or 3306.

$ sudo ss -tlnp | grep 8443
$ sudo ss -tlnp | grep 3306

Stop the conflicting process, or change the port mapping in docker-compose.yml (e.g., "8080:8443" maps host port 8080 to container port 8443).

App container restarts repeatedly

$ docker compose logs app

Common causes:

• Database not yet ready — the app may have started before MySQL finished initialising. Wait 30 seconds and run docker compose restart app.
• Wrong credentials in .env — ensure DB_USER, DB_PASSWORD, and DB_NAME match what MySQL was initialised with.
• Missing .env file — make sure the file exists in the same directory as docker-compose.yml.

Database container health check failing

$ docker compose logs db

If you see InnoDB or permission errors, the MySQL data volume may be corrupted or initialised with different credentials. Remove the volume and start fresh:

$ docker compose down -v
$ docker compose up -d --build

Cannot access the web UI from another machine

• Confirm the UFW rule: sudo ufw status — port 8443 should be listed as ALLOW.
• Confirm Docker is listening: sudo ss -tlnp | grep 8443.
• Check that your cloud provider / router security group / ACL also allows port 8443.

Permission denied when running docker commands

You may not have logged out and back in after adding yourself to the docker group (Section 4.4). Run newgrp docker in the current terminal, or fully log out and log back in.

Uninstalling

Stop and remove containers and volumes

$ cd ~/serpentua-dvp
$ docker compose down -v     # stops containers and deletes the MySQL volume

Remove the Docker images

$ docker image rm $(docker images -q 'dvp*') mysql:8.0 2>/dev/null || true
$ docker image prune -f    # remove any dangling build-cache images

Remove the project files

$ rm -rf ~/serpentua-dvp

Optionally remove Docker itself

$ sudo apt purge -y docker-ce docker-ce-cli containerd.io \
    docker-buildx-plugin docker-compose-plugin
$ sudo rm -rf /var/lib/docker /etc/docker
$ sudo rm /etc/apt/sources.list.d/docker.list
$ sudo rm /etc/apt/keyrings/docker.gpg