Skip to main content

Deployment Guide

How to deploy Almafrica to staging and production environments.

Environments​

EnvironmentURLPurpose
DevelopmentlocalhostLocal development
Stagingstaging.almafrica.comTesting before production
Productionalmafrica.comLive system

Prerequisites​

  • Access to deployment servers or cloud platform
  • Docker installed locally for building images
  • Access to container registry
  • Database migration permissions

Deployment Process​

1. Pre-Deployment Checklist​

  • All tests pass locally
  • PR reviewed and approved
  • CHANGELOG.md updated
  • Database migrations reviewed (especially Down() methods)
  • Environment variables configured in target environment
  • Backup of database taken (production)

2. Build and Push Images​

# Build backend image
docker build -t almafrica-api:latest ./backend

# Build web image
docker build -t almafrica-web:latest ./web/almafrica-web

# Tag for registry
docker tag almafrica-api:latest registry.example.com/almafrica-api:v1.2.3
docker tag almafrica-web:latest registry.example.com/almafrica-web:v1.2.3

# Push to registry
docker push registry.example.com/almafrica-api:v1.2.3
docker push registry.example.com/almafrica-web:v1.2.3

3. Deploy to Staging​

# SSH into staging server
ssh deploy@staging.almafrica.com

# Pull latest images
docker-compose -f docker-compose.staging.yml pull

# Run database migrations
docker-compose -f docker-compose.staging.yml run api dotnet ef database update

# Deploy services
docker-compose -f docker-compose.staging.yml up -d

# Check health
curl https://staging-api.almafrica.com/health

4. Verify Staging​

  • Health check returns 200 OK
  • Login works
  • Critical user flows work
  • No errors in logs

5. Deploy to Production​

# Create database backup
pg_dump almafrica > backup_$(date +%Y%m%d).sql

# Deploy (same as staging but with production compose file)
docker-compose -f docker-compose.production.yml pull
docker-compose -f docker-compose.production.yml run api dotnet ef database update
docker-compose -f docker-compose.production.yml up -d

6. Post-Deployment Verification​

  • Health check returns 200 OK
  • Monitor logs for errors
  • Verify key functionality
  • Check performance metrics

Database Migrations​

Running Migrations​

# Check pending migrations
dotnet ef migrations list

# Apply migrations
dotnet ef database update

# Apply to specific migration
dotnet ef database update MigrationName

Rolling Back Migrations​

# Rollback to previous migration
dotnet ef database update PreviousMigrationName

# In production, always test rollback in staging first

Migration Best Practices​

  1. Always include Down() method - Required for rollbacks
  2. Test both directions - Apply and rollback in staging
  3. Avoid data loss - Don't drop columns with data
  4. Use transactions - Wrap destructive operations
  5. Plan for large tables - Add indexes concurrently

Rollback Procedure​

If deployment fails or causes issues:

1. Application Rollback​

# Revert to previous image version
docker-compose -f docker-compose.production.yml down
docker tag almafrica-api:v1.2.2 almafrica-api:latest
docker-compose -f docker-compose.production.yml up -d

2. Database Rollback​

# Rollback database migration
dotnet ef database update PreviousMigrationName

See Database Rollback Runbook for detailed procedures.

Monitoring​

Health Endpoints​

ServiceEndpoint
Backend API/health
Web/api/health

Log Aggregation​

  • Centralized logging via [logging platform]
  • Error tracking via Sentry
  • Performance monitoring via [APM tool]

Alerts​

Configure alerts for:

  • Health check failures
  • High error rates
  • Database connection issues
  • Memory/CPU thresholds

CI/CD Pipeline​

The deployment is automated via GitHub Actions:

Push to main → Tests → Build Images → Deploy Staging → Manual Approval → Deploy Production

Pipeline Stages​

  1. Test: Run all test suites
  2. Build: Create Docker images
  3. Staging Deploy: Automatic on main branch
  4. Production Deploy: Requires manual approval

Troubleshooting​

Deployment fails​

  1. Check CI/CD logs
  2. Verify environment variables
  3. Check Docker image builds
  4. Review database migration logs

Service unhealthy after deploy​

  1. Check container logs: docker logs <container>
  2. Verify environment configuration
  3. Check database connectivity
  4. Review recent changes

Migration fails​

  1. Check migration SQL for errors
  2. Verify database permissions
  3. Check for locks: SELECT * FROM pg_locks
  4. May need manual intervention