Deployment Guide
SA3 has two deployment modes: VPS Docker (current) and AWS App Runner (production target).
VPS Docker Deployment (Current)
SA3 runs as a Docker container on the VPS alongside other workspace services.
cd /home/stephen/projects/sa3
docker compose up -d --build # Build and start
docker compose logs -f # View logs
docker compose down # Stop
docker ps | grep sa3 # Check status
| Setting | Value |
|---|---|
| Port | 4200 |
| Public URL | https://sa3.stephensprive.app |
| Network | data-network (external, connects to platform-postgres) |
| Env | .env file via env_file; DATABASE_URL overridden for Docker network |
Pre-deployment Checks
# Verify nothing is already running on the port
ss -tlnp | grep :4200
docker ps | grep sa3
# Build and start
docker compose up -d --build
# Verify
docker ps | grep sa3
curl -s https://sa3.stephensprive.app | head -5
AWS App Runner Deployment (Production)
The production deployment uses App Runner with ECR source images, provisioned via Terraform.
Build and Push
# Build container
docker build -t sa3 .
# Tag and push to ECR
aws ecr get-login-password --region eu-west-3 | docker login --username AWS --password-stdin <account>.dkr.ecr.eu-west-3.amazonaws.com
docker tag sa3:latest <account>.dkr.ecr.eu-west-3.amazonaws.com/sa3:latest
docker push <account>.dkr.ecr.eu-west-3.amazonaws.com/sa3:latest
Terraform Apply
cd infrastructure/terraform/sa3
terraform plan
terraform apply
CI/CD (GitHub Actions)
The deploy-apps.yml workflow auto-deploys on push to master when files in projects/sa3/ are changed. The workflow:
- Builds the Docker image
- Pushes to ECR
- App Runner detects the new image and deploys automatically
Environment Variables
Required environment variables for production:
| Variable | Purpose |
|---|---|
DATABASE_URL | PostgreSQL connection string |
NEXTAUTH_SECRET | next-auth session encryption key |
NEXTAUTH_URL | Public URL of the app |
HOSTNAME | Must be 0.0.0.0 (Critical Rule 6) |
AWS_REGION | eu-west-3 |
SA3_FILES_BUCKET | S3 bucket name |
KMS_KEY_ARN_PII | KMS key ARN for PII encryption |
SQS_PDF_QUEUE_URL | SQS queue URL for PDF generation |
Database Migrations
# Run migrations before deploying new code with schema changes
cd projects/sa3
npx prisma migrate deploy
warning
Always run migrations before deploying the new application version. Schema changes must be backward-compatible with the running version during the migration window.