Docker Deployment Guide - Payego

Complete guide for deploying Payego using Docker and Docker Compose

📋 Overview

Payego's Docker setup includes:

Backend API (Rust/Axum) with automatic migrations
PostgreSQL Database with persistent storage
Prometheus for metrics collection
Grafana for metrics visualization

🚀 Quick Start

Prerequisites

Docker 20.10+
Docker Compose 2.0+
.env file configured (see below)

1. Environment Setup

Copy the example environment file and configure it:

cp .env.example .env

Required environment variables:

# Database Configuration
DB_USER=postgres
DB_PASSWORD=your_secure_password_here
DB_NAME=payego
DB_PORT=5432

# Application Port
APP_PORT=8080

# JWT Configuration
JWT_SECRET=your_super_secret_key_must_be_at_least_32_characters_long
JWT_EXPIRATION_HOURS=2
ISSUER=payego-api
AUDIENCE=payego-client

# Payment Providers
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
PAYSTACK_SECRET_KEY=sk_test_...
PAYSTACK_WEBHOOK_SECRET=whsec_...
PAYPAL_CLIENT_ID=...
PAYPAL_SECRET=...

# Application Settings
RUST_LOG=info
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

2. Build and Run

Start all services:

docker-compose up --build -d

The -d flag runs containers in detached mode (background).

3. Verify Deployment

Check that all services are running:

docker-compose ps

You should see 4 services running:

payego-app-1 (Backend API)
payego-db-1 (PostgreSQL)
payego-prometheus-1 (Metrics)
payego-grafana-1 (Dashboards)

🌐 Service Access

Once deployed, access the services at:

Service	URL	Description
Backend API	http://localhost:8080	Main application API
Swagger UI	http://localhost:8080/swagger-ui/	API documentation
Database	localhost:5432	PostgreSQL (use DB client)
Prometheus	http://localhost:9090	Metrics collection
Grafana	http://localhost:3000	Metrics dashboards (admin/admin)

🏗️ Architecture

Multi-Stage Build

The Dockerfile uses a multi-stage build for optimal image size:

Builder Stage (rust:1.81-slim-bullseye):
- Installs build dependencies
- Compiles Diesel CLI
- Builds Rust application in release mode
- Uses dependency caching for faster rebuilds
Runtime Stage (debian:bullseye-slim):
- Minimal runtime dependencies
- Non-privileged user (appuser)
- Automatic database migrations on startup
- ~200MB final image size

Startup Sequence

When the container starts:

Wait for Database: Checks PostgreSQL readiness
Run Migrations: Applies all pending Diesel migrations
Start Application: Launches Payego API server

📦 Services Configuration

Backend (app)

ports:
  - "8080:8080"  # API server
environment:
  - DATABASE_URL=postgres://user:pass@db:5432/payego
  - JWT_SECRET=...
  - STRIPE_SECRET_KEY=...
  # ... other env vars
depends_on:
  - db

Key Features:

Automatic database migrations
Health checks via pg_isready
Restart policy: always
Custom DNS (8.8.8.8, 8.8.4.4)

Database (db)

image: postgres:15-alpine
ports:
  - "5432:5432"
volumes:
  - db_data:/var/lib/postgresql/data

Key Features:

PostgreSQL 15 Alpine (lightweight)
Persistent volume for data
Automatic initialization

Monitoring Stack

Prometheus:

Collects metrics from Payego API
Configuration: prometheus.yml
Port: 9090

Grafana:

Visualizes Prometheus metrics
Default credentials: admin/admin
Port: 3000

🔧 Common Operations

View Logs

All services:

docker-compose logs -f

Specific service:

docker-compose logs -f app
docker-compose logs -f db

Last 100 lines:

docker-compose logs --tail=100 app

Restart Services

All services:

docker-compose restart

Specific service:

docker-compose restart app

Stop Services

docker-compose down

Stop and remove volumes (⚠️ deletes database data):

docker-compose down -v

Database Access

Connect to PostgreSQL:

docker-compose exec db psql -U postgres -d payego

Run SQL query:

docker-compose exec db psql -U postgres -d payego -c "SELECT * FROM users LIMIT 5;"

Run Migrations Manually

If you need to run migrations without restarting:

docker-compose exec app diesel migration run

Execute Commands in Container

docker-compose exec app /bin/sh

🐛 Troubleshooting

Container Won't Start

Check logs:

docker-compose logs app

Common issues:

Missing environment variables → Check .env file
Database not ready → Wait for db service to be healthy
Port already in use → Change APP_PORT in .env

Database Connection Errors

Verify database is running:

docker-compose ps db

Check database logs:

docker-compose logs db

Test connection:

docker-compose exec app pg_isready -h db -p 5432

Migration Failures

View migration status:

docker-compose exec app diesel migration list

Revert last migration:

docker-compose exec app diesel migration revert

Reset database (⚠️ destructive):

docker-compose down -v
docker-compose up -d

Application Crashes

Check application logs:

docker-compose logs --tail=200 app

Common causes:

Invalid JWT_SECRET (must be 32+ characters)
Missing payment provider credentials
Database schema mismatch

Port Conflicts

If port 8080 is already in use, change it in .env:

APP_PORT=8081

Then restart:

docker-compose down
docker-compose up -d

🚢 Production Deployment

Environment Variables

For production, ensure you:

Use strong, unique passwords
Set RUST_LOG=warn or error (not debug)
Configure proper CORS_ORIGINS
Use production payment provider keys
Set secure JWT_SECRET (32+ random characters)

Security Considerations

Database:

Change default PostgreSQL password
Restrict database port exposure (remove from ports if not needed externally)
Use encrypted connections

Application:

Run behind reverse proxy (nginx/Traefik)
Enable HTTPS/TLS
Configure rate limiting
Set up firewall rules

Scaling

Horizontal scaling:

docker-compose up -d --scale app=3

Note: Requires load balancer configuration.

Backup Database

Create backup:

docker-compose exec db pg_dump -U postgres payego > backup.sql

Restore backup:

cat backup.sql | docker-compose exec -T db psql -U postgres payego

🌍 Cloud Deployment

Building for Different Platforms

If deploying to cloud with different CPU architecture (e.g., Mac M1 → AMD64 cloud):

docker build --platform=linux/amd64 -t payego:latest .

Push to Registry

Tag image:

docker tag payego:latest your-registry.com/payego:latest

Push to registry:

docker push your-registry.com/payego:latest

Example: AWS ECS

Push image to Amazon ECR
Create task definition with environment variables
Configure RDS PostgreSQL instance
Set up Application Load Balancer
Deploy ECS service

Example: Google Cloud Run

Push image to Google Container Registry
Create Cloud SQL PostgreSQL instance
Deploy with environment variables
Configure Cloud Run service

📊 Monitoring

Prometheus Metrics

Access Prometheus at http://localhost:9090

Available metrics:

HTTP request duration
Request count by endpoint
Database connection pool stats
System resource usage

Grafana Dashboards

Access Grafana at http://localhost:3000

Default credentials: admin/admin

Setup:

Add Prometheus data source (http://prometheus:9090)
Import dashboards from grafana/provisioning/
Create custom dashboards as needed

🔄 Updates and Maintenance

Update Application

Pull latest code
Rebuild and restart:

git pull
docker-compose up --build -d

Update Dependencies

Rebuild with no cache:

docker-compose build --no-cache
docker-compose up -d

Clean Up

Remove unused images:

docker image prune -a

Remove unused volumes:

docker volume prune

📚 Additional Resources

💡 Tips

Development: Use docker-compose up (without -d) to see logs in real-time
Production: Always use -d flag and monitor logs separately
Debugging: Use docker-compose exec app /bin/sh to inspect container
Performance: Monitor Grafana dashboards for bottlenecks
Backups: Schedule regular database backups in production

🆘 Getting Help

If you encounter issues:

Check logs: docker-compose logs app
Verify environment variables in .env
Ensure all required services are running
Check main README for application-specific details
Review Swagger UI for API documentation

FilesExpand file tree

README.Docker.md

Latest commit

History