Database Migration

On-Prem Deployment Guide (Azure)

Step 1: Verify Admin Credentials in .env

Goal: confirm .env currently holds Phase 1 (admin) credentials before running migration - running migration with the application user's limited privileges will fail.

Prerequisites: Environment Configuration completed with Phase 1 credentials; database created (Database Setup).

Before running migration, ensure .env file has admin/root credentials:

cd /opt/hivel-onprem
 
# Verify .env has admin credentials
cat config/.env | grep DB_USER
cat config/.env | grep DB_PASSWORD
 
# Should show:
# DB_USER=your_admin_username
# DB_PASSWORD='your_admin_password'

If credentials are stored in Azure Key Vault:

# Retrieve credentials from Key Vault
az keyvault secret show --vault-name <your-vault-name> --name <secret-name> --query value -o tsv
 
# Update .env file with admin credentials from Key Vault

Step 2: Run Flyway Migration

Goal: initialize the database schema and create the application user, exactly once, before any services start.

Important : This must be done ONCE on VM only before deploying any services.

Prerequisites: admin credentials confirmed in .env (previous step).

On VM:

cd /opt/hivel-onprem
 
# Ensure .env has admin credentials (for migration)
# Then deploy only the flyway-migration service
./deploy.sh --service flyway-migration

What flyway-migration does:

• Creates all Hivel database schemas and tables

• Creates the application user: <user>

• Sets up default password: <password> (unless customized)

• Initializes all required database objects

Expected result: the command completes and exits - see verification below for what "success" looks like.

If it fails: see Migration failed in Troubleshooting.

Step 3: Verify Migration Completed

Wait for migration to complete (usually 1-2 minutes):

# Check migration logs
docker logs flyway-migration
 
# Check exit code (0 = success, non-zero = failure)
docker inspect flyway-migration --format='{{.State.ExitCode}}'
 
# Check container status
docker ps -a | grep flyway-migration

Success indicators:

• Exit code: 0

• Logs show "Successfully applied X migration(s)"

• Logs show user <user> created

• Container status: "Exited (0)"

Failure indicators:

• Exit code: non-zero (1, 2, etc.)

• Logs show error messages

• Container status: "Exited (1)" or similar

Do not proceed until migration is successful.

Step 4: Update .env with Application User Credentials

After migration succeeds, update the .env file to use the application user:

# Edit .env file
nano config/.env
 
# Update these values:
DB_USER= <user>
DB_PASSWORD='<password>'  # Default password (or your custom password)
 
# Save and exit

If you customized the password:

• Ensure the password in .env matches what was set during migration

Note: The flyway-migration service is a one-time job. It runs, initializes the database, and exits. It does not need to stay running.

Next step: Deployment Methods.

Back to Environment Configuration

Deployment Methods