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:

• ☐macOS 12 Monterey or later — Intel or Apple Silicon (M1 / M2 / M3)
• ☐An account with Administrator (sudo) privileges
• ☐Internet access (to download Docker Desktop, images, and Python packages)
• ☐At least 4 GB RAM available (Docker Desktop requires a minimum of 4 GB)
• ☐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

3.1 — Verify your macOS version

Open the Terminal application (find it in Finder → Applications → Utilities → Terminal, or press ⌘ + Space and type Terminal) and run:

$ sw_vers -productVersion
12.x.x  (must be 12.0 or later)

3.2 — Install Xcode Command Line Tools

The Xcode Command Line Tools provide git and other utilities needed during installation. If they are not already installed, run:

$ xcode-select --install

A dialog will appear asking you to install the tools. Click Install and wait for the download to complete (~500 MB). If the tools are already installed you will see the message "xcode-select: error: command line tools are already installed" — that is fine, continue to the next step.

3.3 — (Apple Silicon only) Install Rosetta 2

If your Mac has an Apple Silicon chip (M1, M2, or M3), install Rosetta 2 so that Docker can run x86_64 container images when needed:

$ softwareupdate --install-rosetta --agree-to-license

Install Docker Desktop

4.1 — Download Docker Desktop for Mac

Go to docker.com/products/docker-desktop in your browser and download the Docker Desktop for Mac installer (.dmg file). On the download page, choose either Mac with Intel Chip or Mac with Apple Chip to match your hardware.

4.2 — Install from the disk image

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 — Configure file sharing

Docker Desktop on macOS can only mount directories that are explicitly allowed. Confirm that the directory containing your project files is in the sharing list:

Open Docker Desktop → Settings (gear icon) → Resources → File Sharing. The list should already include /Users, /Volumes, /private, and /tmp. If you plan to store the project or monitor files outside of these paths, click + to add the required directory, then click Apply & Restart.

Get the Application Source

Copy the serpentua-dvp-docker project folder to your Mac. 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

Use Finder to copy the serpentua-dvp-docker folder to your home directory, or use Terminal:

$ cp -r /Volumes/USB/serpentua-dvp-docker ~/serpentua-dvp

Option C — Extract from a ZIP archive

# macOS includes unzip natively
$ unzip ~/Downloads/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 in Terminal is the quickest option:

$ 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 macOS host's filesystem into the container at /host (read-only). Because macOS already uses Unix-style paths, the mapping is straightforward: prepend /host to any absolute macOS path when entering it inside the DVP application.

Firewall & Remote Access

The macOS Application Firewall controls inbound connections on a per-application basis rather than per port. When Docker Desktop first binds a port, macOS may display a dialog asking whether to allow incoming connections — click Allow. If the dialog was dismissed or the firewall blocks access, manage it manually:

Check and configure the firewall via Terminal

$ sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
Firewall is enabled. (State = 1)

If the firewall is enabled and remote machines cannot connect, explicitly allow the Docker Desktop application:

$ sudo /usr/libexec/ApplicationFirewall/socketfilterfw \
    --add /Applications/Docker.app
$ sudo /usr/libexec/ApplicationFirewall/socketfilterfw \
    --unblockapp /Applications/Docker.app

Configure via System Settings (alternative)

Open System Settings → Network → Firewall → Options. Locate Docker Desktop in the list and set it to Allow incoming connections. Click OK.

Auto-Start on Boot

Docker Desktop auto-start (recommended)

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

Optional — launchd service

If you need the containers to start as a background service without requiring a user login (e.g., on a dedicated Mac server), create a launchd plist:

$ sudo nano /Library/LaunchDaemons/com.serpentua.dvp.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.serpentua.dvp</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/docker</string>
    <string>compose</string>
    <string>up</string>
    <string>-d</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/YOUR_USER/serpentua-dvp</string>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

$ sudo launchctl load /Library/LaunchDaemons/com.serpentua.dvp.plist

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 lsof -i :8443
$ sudo lsof -i :3306

Note the PID in the output and stop the conflicting process with kill <PID>, 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. Note: macOS Finder hides files beginning with a dot (.) by default. Press ⌘ + Shift + . to show hidden files.

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 Docker is listening: sudo lsof -i :8443.
• Check the macOS firewall: System Settings → Network → Firewall — confirm Docker Desktop is allowed.
• Check that your router or any cloud security group also allows port 8443.

Apple Silicon — platform mismatch warnings

On Apple Silicon Macs you may see a warning such as: "The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)". Docker Desktop uses Rosetta 2 to run x86_64 images transparently, so the containers will still work, but you can silence the warning by adding a platform key to each service in docker-compose.yml:

services:
  app:
    platform: linux/amd64
    build: .
    ...
  db:
    platform: linux/amd64
    image: mysql:8.0
    ...

Docker Desktop runs slowly or uses too much memory

Docker Desktop allocates a fixed amount of RAM and CPU to its Linux VM. If the machine feels sluggish, adjust the limits under Docker Desktop → Settings → Resources. A minimum of 2 GB RAM and 2 CPUs is recommended for DVP.

Docker Desktop does not start

• Restart Docker Desktop from the menu bar: click the whale icon → Restart.
• Try the built-in reset tool: whale icon → Troubleshoot → Restart Docker Desktop.
• Review Docker Desktop logs at ~/Library/Containers/com.docker.docker/Data/log/.

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 uninstall Docker Desktop

The easiest way to uninstall Docker Desktop is via its built-in uninstaller, which also removes all associated data and virtual machine files:

Click the whale icon in the menu bar → Troubleshoot → Uninstall. Confirm when prompted.

Alternatively, drag Docker.app from Applications to the Trash, then remove the remaining data:

$ rm -rf ~/Library/Group\ Containers/group.com.docker
$ rm -rf ~/Library/Containers/com.docker.docker
$ rm -rf ~/.docker

Remove the launchd service (if created)

$ sudo launchctl unload /Library/LaunchDaemons/com.serpentua.dvp.plist
$ sudo rm /Library/LaunchDaemons/com.serpentua.dvp.plist