Database Migration

On-prem Deployment Guide (AWS)

Goal: Initialize the database schema and create the application user (run once before any service starts).

Prerequisites:

• Environment Configuration completed with Phase 1 (root/master) credentials in .env

• "insightly" database created in RDS (see RDS Database Setup, Step 3)

• RDS connectivity verified from VM (see Environment Configuration, Step 3)

Step 1: Verify Root Credentials in .env

Application/System: EC2 VM and AWS Secrets Manager (if applicable)

Verify that config/.env contains root/master credentials:

cd /opt/hivel-onprem

# Verify .env has root credentials
cat config/.env | grep DB_USER
cat config/.env | grep DB_PASSWORD
# Should show:
# DB_USER=your_rds_master_username
# DB_PASSWORD='your_rds_master_password'

If RDS uses AWS Secrets Manager:

# Retrieve credentials from Secrets Manager
aws secretsmanager get-secret-value --secret-id <your-secret-name> --query SecretString --output text

# Update .env file with root credentials from Secrets Manager

Do not proceed until root credentials are correctly set in .env.

Step 2: Run Flyway Database Migration

Application/System: EC2 VM (Docker)

Critical: This step runs once only, before any other services start. It initializes the entire database.

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

What this does:

• Creates all Hivel database schemas and tables

• Creates the application user (<user>)

• Sets default application password

• Initializes all required database objects

Wait 1–2 minutes for completion.

Step 3: Verify Migration Success

Application/System: EC2 VM (Docker)

# 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 contain: "Successfully applied X migration(s)"

• Logs contain: "user <user> created"

• Container status: "Exited (0)"

Failure indicators:

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

• Logs show error messages

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

If migration failed: See Troubleshooting: Migration Failed. Do not proceed to the next step.

Step 4: Update .env with Application User Credentials

After migration succeeds, update .env file to use 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

Notes:

• Default password is <password> (if you did not customize it during migration).

• If you customized the password earlier, use the same password here.

• Passwords with special characters must be in single quotes.

Important Notes

• The flyway-migration container is a one-time initialization job. It runs, migrates the database, and exits. It does not need to remain running.

• Rerunning migration on an already-initialized database may cause errors. Run it only once per RDS database.

• All subsequent services use the application user credentials.

Back to ECR Access Configuration

Deployment Methods