Data Validation Platform (DVP)
Ubuntu Installer Script Guide

How to use install_dvp_ubuntu.sh to automate the full DVP installation

PlatformUbuntu 20.04 / 22.04 / 24.04 LTS

Scriptinstall_dvp_ubuntu.sh

RuntimeDocker CE & Docker Compose

Duration~10 min (first run)

Download Script

Overview
Prerequisites
Before You Begin
Running the Script
Step-by-Step Walkthrough
After Installation
Troubleshooting

Section 1

Overview

install_dvp_ubuntu.sh automates every step described in the DVP Ubuntu Installation Guide. Running it on a fresh Ubuntu machine will take you from a bare OS to a fully running DVP instance in a single terminal session.

The script performs the following eight steps automatically:

Step	What it does	User input?
1	Check OS version, disk space, and port availability	None
2	Run `apt update && upgrade` and install prerequisite utilities	None
3	Add Docker's official repository and install Docker CE + Compose plugin	None
4	Add your user to the `docker` group and enable Docker on boot	None
5	Ask where the DVP project folder is located	Directory path
6	Prompt for secure passwords and write them to `.env`	Two passwords
7	Build the Docker images and start all containers	None
8	Wait for containers to start, then confirm DVP is accessible	None

ⓘ

The script is idempotent for Docker — if Docker is already installed it will detect this and skip the installation, so it is safe to re-run on a machine where Docker was previously set up.

Section 2

Prerequisites

Confirm all of the following before running the script:

☐Ubuntu 20.04, 22.04, or 24.04 LTS — 64-bit (server or desktop edition)
☐A user account with sudo privileges — do not run as root
☐Internet access to download Docker images and Python packages
☐At least 3 GB of free disk space on /
☐Ports 8443 and 3306 not already in use
☐The DVP project folder already copied to this machine, containing docker-compose.yml and .env
☐Both install_dvp_ubuntu.sh and the project folder accessible from the same user account

⚠

The script calls sudo internally for system-level operations. You will be prompted for your sudo password by the OS the first time a privileged command runs — this is normal behaviour.

Section 3

Before You Begin

Ensure the project files are on the machine

The script does not download the DVP source code — you must copy the serpentua-dvp-docker folder to the Ubuntu machine before running it. The folder must contain at minimum:

required project files

serpentua-dvp-docker/
├── Dockerfile
├── docker-compose.yml
├── .env
├── requirements.txt
├── runserver.py
└── dvp/

See the DVP Ubuntu Installation Guide — Section 5 for methods to copy the project to the machine (git clone, SCP, or ZIP upload).

Place the script on the machine

Copy install_dvp_ubuntu.sh to the Ubuntu machine. It can live anywhere — your home directory is fine:

bash — copy script via SCP from your local machine

$ scp install_dvp_ubuntu.sh user@<server-ip>:~/

Make the script executable

On the Ubuntu machine, grant execute permission:

bash

$ chmod +x ~/install_dvp_ubuntu.sh

Section 4

Running the Script

Open a terminal, log in as your regular (non-root) user, and run:

bash

$ bash ~/install_dvp_ubuntu.sh

ⓘ

You can also run it as ./install_dvp_ubuntu.sh if you are in the same directory as the script and it has been made executable with chmod +x.

The script will clear the screen and display a banner listing what it is about to do, then pause and wait for you to press Enter before proceeding. This gives you a final chance to abort with Ctrl+C.

terminal — opening banner

  ╔═════════════════════════════════════════════════════╗
  ║      Serpentua Data Validation Platform (DVP)       ║
  ║           Ubuntu Automated Installer                ║
  ╚═════════════════════════════════════════════════════╝

  This script will:
    1.  Check system prerequisites
    2.  Update system packages
    3.  Install Docker CE and Docker Compose (official repository)
    4.  Add your user to the docker group and enable Docker on boot
    5.  Ask for the DVP project directory
    6.  Set secure passwords in .env
    7.  Build and launch the application
    8.  Verify containers are running

  Press ENTER to continue or Ctrl+C to abort ... ↵

Output colour key

The script uses coloured prefixes so you can see at a glance what is happening:

[ OK] Step completed successfully

[INFO] Informational message, no action needed

[WARN] Warning — read it, but the script continues

[FAIL] Fatal error — script has stopped, see message for cause

Section 5

Step-by-Step Walkthrough

This section explains what the script does and shows representative output for each of the eight steps. Your exact output will vary slightly depending on your system.

Step 1 — Checking Prerequisites

The script reads /etc/os-release to confirm Ubuntu is running, checks the CPU architecture, verifies at least 3 GB of free disk space, and checks whether ports 8443 and 3306 are already in use. No user input is required.

expected output — step 1

[  OK]  Ubuntu 22.04 LTS detected.
[INFO]  Architecture: amd64
[  OK]  Free disk space: 18.4 GB.
[  OK]  Port 8443 is free.
[  OK]  Port 3306 is free.

⚠

If a port is already in use you will see a [WARN] message instead of [OK] for that port. The script will continue, but the container will fail to start in Step 7 unless you resolve the conflict first. See Troubleshooting for help identifying the conflicting process.

Step 2 — Updating System Packages

Runs apt-get update and apt-get upgrade -y, then installs the utilities Docker's setup requires (ca-certificates, curl, gnupg, lsb-release, git). This step runs quietly — you will see a brief progress indicator from apt. No user input is required.

expected output — step 2

[INFO]  Running apt update and upgrade ...
[  OK]  System packages are up to date.
[INFO]  Installing prerequisite utilities ...
[  OK]  Utilities installed (ca-certificates, curl, gnupg, lsb-release, git).

Step 3 — Installing Docker CE & Docker Compose

If Docker is not already installed, the script adds Docker's official GPG key, registers the stable apt repository, then installs docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin.

If Docker is already installed (including the Compose plugin), the script detects this and skips the installation with a [WARN] message.

expected output — step 3 (fresh install)

[INFO]  Adding Docker's official GPG key ...
[INFO]  Adding Docker stable repository ...
[INFO]  Installing Docker packages ...
[  OK]  Docker installed: Docker version 27.4.0, build bde2b89
[  OK]  Docker Compose: Docker Compose version v2.32.1

expected output — step 3 (Docker already installed)

[WARN]  Docker is already installed: Docker version 27.4.0, build bde2b89
[WARN]  Docker Compose: Docker Compose version v2.32.1
[WARN]  Skipping Docker installation. Uninstall first if you want a fresh install.

Step 4 — Configuring Docker

Adds your user account to the docker group (so you can run Docker commands without sudo after your next login) and enables the Docker systemd service to start automatically on boot. No user input is required.

expected output — step 4

[INFO]  Adding 'alice' to the docker group ...
[  OK]  User 'alice' added to the docker group.
[WARN]  Group change takes effect after your next login. Docker commands in
[WARN]  this script will run via 'sudo docker' for the remainder of this session.
[INFO]  Enabling Docker to start on boot ...
[  OK]  Docker service is active.

ⓘ

The [WARN] about the group change is expected and harmless — the script automatically uses sudo docker for the remainder of this run. After you log out and back in, you can use docker directly without sudo.

Step 5 — Locating the DVP Project

The script asks you where the serpentua-dvp-docker project folder is located. Press Enter to accept the default path, or type a custom path.

terminal — step 5 prompt

  The project directory must already exist on this machine and contain
  docker-compose.yml and .env.

  Project path [default: /home/alice/serpentua-dvp/serpentua-dvp-docker]: ↵
[  OK]  Project found: /home/alice/serpentua-dvp/serpentua-dvp-docker

The script validates that the directory exists and contains both docker-compose.yml and .env. If either file is missing it will print a [FAIL] message and exit — copy the missing files and re-run.

ⓘ

You can type a path with a leading ~ (e.g. ~/my-dvp/serpentua-dvp-docker) — the script will expand it to the full absolute path automatically.

Step 6 — Configuring the Environment (.env)

The script shows whether the current passwords in .env are set or still at their defaults, warns you that the defaults are insecure, and asks whether you want to set new passwords now.

terminal — step 6 prompts

  Current DB_PASSWORD         : ******* (set)
  Current MYSQL_ROOT_PASSWORD : ******* (set)

[WARN]  The default passwords in .env are insecure and must be changed before production use.

  Set new passwords now? [Y/n]: Y

  Enter DB_PASSWORD: (typing is hidden)
  Confirm DB_PASSWORD: (typing is hidden)

  Enter MYSQL_ROOT_PASSWORD: (typing is hidden)
  Confirm MYSQL_ROOT_PASSWORD: (typing is hidden)

[  OK]  .env updated with new passwords.

Passwords are written to .env using a Python helper that handles any special characters safely — you may use !, @, #, $, and other symbols without issue.

Prompt	What to enter
`Set new passwords now? [Y/n]`	Press Enter (defaults to Y) or type `n` to skip
`Enter DB_PASSWORD`	A strong password for the MySQL application user — typing is hidden
`Confirm DB_PASSWORD`	Type the same password again to confirm — must match exactly
`Enter MYSQL_ROOT_PASSWORD`	A strong password for the MySQL root user — typing is hidden
`Confirm MYSQL_ROOT_PASSWORD`	Type the same root password again to confirm — must match exactly

⚠

If you choose n (skip), the .env file will keep its current values. Make sure you update the passwords manually with nano .env before going to production. The default passwords in the shipped .env are publicly known and must not be used in a live environment.

Step 7 — Building & Launching DVP

Runs docker compose up -d --build from the project directory. Docker pulls the MySQL image, builds the application image, and starts both containers in the background. No user input is required.

The first run is the slowest — Docker needs to download the base images (~700 MB) and compile Python packages. Expect this step to take 5–15 minutes depending on your internet connection. Subsequent runs are much faster.

expected output — step 7

[INFO]  Running: sudo docker compose up -d --build
[INFO]  The first build downloads images and compiles Python packages — this can take several minutes.

[+] Building 142.3s (12/12) FINISHED
 => [db] mysql:8.0 pulled                              45.2s
 => [app] build context loaded                          0.1s
 => [app] python:3.13-slim pulled                      38.7s
 => [app] pip install -r requirements.txt              54.8s
[+] Running 2/2
 ✔ Container dvp-db-1   Started
 ✔ Container dvp-app-1  Started

[  OK]  Build and launch complete.

Step 8 — Verifying the Installation

The script waits 15 seconds for MySQL to finish initialising, then runs docker compose ps and checks that both containers report a running status. If successful, it prints the URLs you can use to access DVP. No user input is required.

expected output — step 8

[INFO]  Waiting 15 seconds for containers to initialise ...

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

  ╔═════════════════════════════════════════════════════╗
  ║              DVP is up and running!                 ║
  ╚═════════════════════════════════════════════════════╝

  Local access:   http://localhost:8443
  Network access: http://192.168.1.50:8443

The script finishes with a summary of the project directory and a list of the most useful day-to-day management commands.

final summary output

  Project directory : /home/alice/serpentua-dvp/serpentua-dvp-docker

  Useful commands (run from the project directory):
    docker compose ps              — check container status
    docker compose logs -f         — follow live logs
    docker compose logs -f app     — app logs only
    docker compose down            — stop the application
    docker compose up -d           — start the application
    docker compose up -d --build   — rebuild and start

  ⚠  Log out and back in so your user can run docker without sudo.

Section 6

After Installation

Access the web interface

Open a browser on the same machine and navigate to:

URL — local access

http://localhost:8443

From another machine on the same network, use the IP address printed at the end of the script:

URL — remote access

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

Apply the docker group change

If this was a fresh Docker install, log out and back in so your user account gains the docker group permission. After re-login you can drop sudo from all Docker commands:

bash — verify group membership after re-login

$ groups
alice adm sudo docker ...

Auto-start on boot

The script enables the Docker service to start on boot and both containers are configured with restart: unless-stopped. DVP will come back up automatically after a system reboot with no additional configuration.

✓

Installation is complete. For ongoing management commands, firewall configuration, file path mapping, and more, refer to the DVP Ubuntu Installation Guide.

Section 7

Troubleshooting

[FAIL] "Do not run as root"

You ran the script with sudo bash install_dvp_ubuntu.sh or as the root user. Run it as your normal user account — the script will call sudo internally when it needs elevated privileges:

bash — correct way to run the script

$ bash ~/install_dvp_ubuntu.sh

[FAIL] "This script requires Ubuntu"

The script detected a different Linux distribution. It only supports Ubuntu 20.04, 22.04, and 24.04 LTS. If you are running a different Ubuntu-based distro (e.g., Linux Mint), follow the manual installation steps in the DVP Ubuntu Installation Guide.

[FAIL] "Need at least 3 GB free"

The root filesystem has less than 3 GB available. Free up space or expand the disk, then re-run the script:

bash — check what is using disk space

$ df -h /
$ du -sh /var/log/* | sort -rh | head -20

[WARN] Port already in use

The script warns you but continues. The containers will fail to bind their ports in Step 7. Identify the process using the port and stop it before re-running:

bash — find the process using port 8443

$ sudo ss -tlnp | grep :8443

[FAIL] "Directory not found" or "docker-compose.yml not found"

The path you entered in Step 5 does not exist or is missing required files. Check that the project folder was copied to the machine correctly, then re-run the script and enter the correct path.

bash — verify the project folder contents

$ ls -la ~/serpentua-dvp/serpentua-dvp-docker/

Passwords do not match (Step 6)

If the two entries for a password do not match, the script will print [WARN] Passwords do not match — try again. and re-prompt you. There is no limit on retries — type carefully and try again.

Step 7 fails — containers do not start

If docker compose up exits with an error, check the compose logs for the specific failure reason:

bash — check container logs after a failed Step 7

$ cd ~/serpentua-dvp/serpentua-dvp-docker
$ docker compose logs

Common causes: mismatched credentials between .env and an existing MySQL data volume (run docker compose down -v to reset), or a port conflict that was not resolved before Step 7.

Step 8 — containers shown as not running

The 15-second wait may not be long enough for MySQL to fully initialise on slower machines. Wait another 30 seconds and check manually:

bash — check status and logs manually

$ cd ~/serpentua-dvp/serpentua-dvp-docker
$ docker compose ps
$ docker compose logs db
$ docker compose logs app

Data Validation Platform (DVP) Ubuntu Installer Script Guide

Data Validation Platform (DVP)
Ubuntu Installer Script Guide

Table of Contents

Overview

Prerequisites

Before You Begin

Ensure the project files are on the machine

Place the script on the machine

Make the script executable

Running the Script

Output colour key

Step-by-Step Walkthrough

Step 1 — Checking Prerequisites

Step 2 — Updating System Packages

Step 3 — Installing Docker CE & Docker Compose

Step 4 — Configuring Docker

Step 5 — Locating the DVP Project

Step 6 — Configuring the Environment (.env)

Step 7 — Building & Launching DVP

Step 8 — Verifying the Installation

After Installation

Access the web interface

Apply the docker group change

Auto-start on boot

Troubleshooting

[FAIL] "Do not run as root"

[FAIL] "This script requires Ubuntu"

[FAIL] "Need at least 3 GB free"

[WARN] Port already in use

[FAIL] "Directory not found" or "docker-compose.yml not found"

Passwords do not match (Step 6)

Step 7 fails — containers do not start

Step 8 — containers shown as not running

Related Articles

Data Validation Platform (DVP) Ubuntu Installation Instructions

Data Validation Platform (DVP) Ubuntu Installer Script Guide

Data Validation Platform (DVP)Ubuntu Installer Script Guide

Table of Contents

Overview

Prerequisites

Before You Begin

Ensure the project files are on the machine

Place the script on the machine

Make the script executable

Running the Script

Output colour key

Step-by-Step Walkthrough

Step 1 — Checking Prerequisites

Step 2 — Updating System Packages

Step 3 — Installing Docker CE & Docker Compose

Step 4 — Configuring Docker

Step 5 — Locating the DVP Project

Step 6 — Configuring the Environment (.env)

Step 7 — Building & Launching DVP

Step 8 — Verifying the Installation

After Installation

Access the web interface

Apply the docker group change

Auto-start on boot

Troubleshooting

[FAIL] "Do not run as root"

[FAIL] "This script requires Ubuntu"

[FAIL] "Need at least 3 GB free"

[WARN] Port already in use

[FAIL] "Directory not found" or "docker-compose.yml not found"

Passwords do not match (Step 6)

Step 7 fails — containers do not start

Step 8 — containers shown as not running

Related Articles

Data Validation Platform (DVP) Ubuntu Installation Instructions

Data Validation Platform (DVP)
Ubuntu Installer Script Guide