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:

• ☐ Windows 10 64-bit (Build 19041 or later) or Windows 11 — Home, Pro, Enterprise, or Education
• ☐ An account with Administrator privileges
• ☐ Hardware virtualisation enabled in BIOS/UEFI (Intel VT-x or AMD-V)
• ☐ At least 4 GB RAM available (Docker Desktop requires a minimum of 4 GB)
• ☐ Internet access (to download Docker Desktop, 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 — Enable WSL2

Docker Desktop on Windows uses the Windows Subsystem for Linux 2 (WSL2) backend for best performance. You must enable WSL2 before installing Docker Desktop.

3.1 — Enable WSL and the Virtual Machine Platform

PS> dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
PS> dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart your computer after running both commands before continuing.

3.2 — Set WSL2 as the default version

PS> wsl --set-default-version 2

Install Docker Desktop

4.1 — Download Docker Desktop

Go to docker.com/products/docker-desktop in your browser and download the Docker Desktop Installer for Windows (the .exe file).

4.2 — Run the installer

4.3 — Verify the installation

Open a new PowerShell or Command Prompt window (no administrator rights needed) and run:

PS> docker --version
Docker version 27.x.x, build xxxxxxx

PS> docker compose version
Docker Compose version v2.x.x

4.4 — Enable drive sharing (if prompted)

Docker Desktop may ask for permission to share your local drives so that containers can access files on your Windows filesystem. When prompted, click Share it. You can also manage this manually:

Open Docker Desktop → Settings → Resources → File Sharing, and confirm that the drive containing your project files (typically C:) is listed and enabled.

Get the Application Source

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

Option A — Clone from a Git repository

If Git is not installed, download it from git-scm.com and run the installer with default settings. Then open PowerShell and run:

PS> git clone <repository-url> C:\serpentua-dvp
PS> cd C:\serpentua-dvp

Option B — Copy an existing folder

Use File Explorer to copy the serpentua-dvp-docker folder to a convenient location, for example C:\serpentua-dvp. Alternatively, use PowerShell:

PS> Copy-Item -Recurse "D:\Downloads\serpentua-dvp-docker" "C:\serpentua-dvp"

Option C — Extract from a ZIP archive

PS> Expand-Archive -Path "C:\Downloads\serpentua-dvp-docker.zip" `
    -DestinationPath "C:\serpentua-dvp"
PS> cd "C:\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 Notepad, Notepad++, or VS Code:

PS> notepad .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 and close the file after making your changes.

Build & Launch the Application

Open PowerShell, navigate to the project root directory, and run:

PS> cd C:\serpentua-dvp\serpentua-dvp-docker
PS> docker compose up -d --build

Docker will:

Watching the logs in real time

# Follow logs for all containers
PS> docker compose logs -f

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

Verify the Installation

Check container status

PS> 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 Windows C:\ drive into the container at /host (read-only). When you add asset paths inside the DVP UI, you must use the container path, not the Windows path. Replace the drive letter and backslashes with the /host prefix and forward slashes.

Firewall & Remote Access

Windows Defender Firewall may block inbound connections on port 8443. When Docker Desktop starts a container that binds a port, Windows will often prompt you to allow access. If no prompt appeared, or if remote machines cannot reach the web UI, add the rule manually.

Add an inbound firewall rule via PowerShell

PS> New-NetFirewallRule `
    -DisplayName "Serpentua DVP Web" `
    -Direction Inbound `
    -Protocol TCP `
    -LocalPort 8443 `
    -Action Allow

Verify the rule was created

PS> Get-NetFirewallRule -DisplayName "Serpentua DVP Web" | Select-Object DisplayName, Enabled, Direction

Add the rule via the GUI (alternative)

Open Windows Defender Firewall with Advanced Security (search in Start menu) → Inbound Rules → New Rule → select Port, enter 8443, choose Allow the connection, apply to all profiles, and name the rule Serpentua DVP Web.

Auto-Start on Boot

Docker Desktop auto-start (recommended)

Both containers already have restart: unless-stopped set in docker-compose.yml, which means they will restart automatically whenever the Docker Engine restarts. Enable Docker Desktop to start with Windows by opening Docker Desktop → Settings (gear icon) → General → check "Start Docker Desktop when you sign in to your computer" → click Apply & Restart.

Optional — Task Scheduler startup task

If you need the containers to start before any user logs in (e.g., on a server), use Windows Task Scheduler to run docker compose up -d at system startup:

PS> $action = New-ScheduledTaskAction `
    -Execute "docker" `
    -Argument "compose up -d" `
    -WorkingDirectory "C:\serpentua-dvp\serpentua-dvp-docker"

PS> $trigger = New-ScheduledTaskTrigger -AtStartup

PS> Register-ScheduledTask `
    -TaskName "Serpentua DVP" `
    -Action $action `
    -Trigger $trigger `
    -RunLevel Highest `
    -User "SYSTEM"

To verify the task was created:

PS> Get-ScheduledTask -TaskName "Serpentua DVP"

Day-to-Day Management

Run all management commands from a PowerShell window inside the project directory (C:\serpentua-dvp\serpentua-dvp-docker).

Updating the application

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

Database backups

PS> $date = Get-Date -Format "yyyyMMdd"
PS> docker compose exec db mysqldump -u dvp -p dvp_app > "dvp_backup_$date.sql"

Troubleshooting

Container fails to start — "port already in use"

Another process is already listening on port 8443 or 3306.

PS> netstat -ano | findstr :8443
PS> netstat -ano | findstr :3306

Note the PID from the last column and find the process in Task Manager (Details tab), or use: Get-Process -Id <PID>. 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

PS> 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. Note: Windows File Explorer may hide file extensions; confirm the file is named .env and not .env.txt.

Database container health check failing

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

PS> docker compose down -v
PS> docker compose up -d --build

Cannot access the web UI from another machine

• Confirm the firewall rule exists: Get-NetFirewallRule -DisplayName "Serpentua DVP Web" — the rule should show Enabled: True.
• Confirm Docker is listening: netstat -ano | findstr :8443.
• Check that any external firewall, router, or cloud security group also allows port 8443.
• Try disabling Windows Defender Firewall temporarily to rule it out as the cause.

Docker Desktop does not start / whale icon not appearing

• Confirm WSL2 is installed correctly: open PowerShell and run wsl --status.
• Confirm virtualisation is enabled: open Task Manager → Performance tab → CPU — Virtualisation: Enabled should appear.
• Try restarting Docker Desktop from the system tray: right-click the whale icon → Restart.
• Review Docker Desktop logs at %APPDATA%\Docker\log.txt.

Line-ending issues with shell scripts in the container

Windows uses CRLF (\r\n) line endings while Linux expects LF (\n). If startup scripts fail inside the container with "No such file or directory" errors, configure Git to not alter line endings:

PS> git config --global core.autocrlf false

Then re-clone or re-checkout the project files.

Uninstalling

Stop and remove containers and volumes

PS> cd C:\serpentua-dvp\serpentua-dvp-docker
PS> docker compose down -v     # stops containers and deletes the MySQL volume

Remove the Docker images

PS> docker images --filter "reference=dvp*" -q | ForEach-Object { docker image rm $_ }
PS> docker image rm mysql:8.0
PS> docker image prune -f    # remove any dangling build-cache images

Remove the project files

PS> Remove-Item -Recurse -Force "C:\serpentua-dvp"

Remove the firewall rule

PS> Remove-NetFirewallRule -DisplayName "Serpentua DVP Web"

Optionally uninstall Docker Desktop

Open Windows Settings → Apps → search for Docker Desktop → click Uninstall. This will remove Docker Desktop and all associated data including any remaining images and volumes.