Database Migration

Goal: Initialize the database schema and create the application user (run exactly once, before any services start)

Prerequisites

Before proceeding, confirm:

✓ Environment Configuration Step 2 completed with Phase 1 (superuser) credentials in .env

✓ PostgreSQL database created in Database Setup

✓ You are on the host where Docker is installed

---

Step 1: Verify Superuser Credentials in .env

Run:

cat config/.env | grep DB_USER
cat config/.env | grep DB_PASSWORD

Step 2: Ensure Docker Is Ready

Docker group membership from Server Infrastructure Setup only takes effect in a new shell session. Prepare Docker for this session:

# creates the docker group, in case it wasn't already created during Docker installation
sudo groupadd docker

# adds the current user to the docker group so Docker commands can run without sudo      
sudo usermod -aG docker $USER

# refreshes the current session's group membership immediately, without needing to log out
newgrp docker

# verifies Docker is actually reachable and working in this session                     
docker run hello-world
​

Success: docker run hello-world completes without error Failure: If docker run hello-world still fails, log out and back in (instead of using newgrp docker), then retry

Step 3: Run the Migration

Run:

./deploy.sh --service flyway-migration

Step 4: Verify Migration Succeeded

Wait 1–2 minutes, then run:

docker logs flyway-migration
docker inspect flyway-migration --format='{{.State.ExitCode}}'
docker ps -a | grep flyway-migration

Success:

• Exit code is 0

• Logs show "Successfully applied X migration(s)" and application user created

• Status shows Exited (0)

Failure: Non-zero exit code, error messages, or Exited (1). See Migration failed in Troubleshooting. Do not proceed until this succeeds.

Step 5: Update .env to Application User Credentials (Phase 2)

The Flyway migration created the application user. Update .env with the application user credentials:

nano config/.env

Set these two values in the file:

DB_USER=<user>
DB_PASSWORD='<your app-user password>'

Note: flyway-migration is a one-time job-it runs, initializes the schema, creates the application user, and exits. It will not run again.

Back to Environment Configuration

Deployment