fitpub/DOCKER.md

Docker Deployment Guide

This guide explains how to deploy FitPub using Docker and Docker Compose.

Prerequisites

• Docker Engine 20.10 or later
• Docker Compose 2.0 or later

Quick Start

1. Clone the Repository

git clone <repository-url>
cd feditrack

2. Create Environment File

Copy the example environment file and customize it:

cp .env.example .env

3. Configure Environment Variables

Edit .env and update the following critical values:

Security (REQUIRED):

# Generate a secure JWT secret
JWT_SECRET=$(openssl rand -base64 64)

# Use a strong database password
POSTGRES_PASSWORD=$(openssl rand -base64 32)

Domain Configuration (REQUIRED):

APP_DOMAIN=your-domain.com
APP_BASE_URL=https://your-domain.com

4. Start the Application

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Check service status
docker-compose ps

5. Verify Deployment

The application should be available at:

• Application: http://localhost:8080
• Health Check: http://localhost:8080/actuator/health

Environment Variables

See .env.example for all available configuration options:

Variable	Description	Default
POSTGRES_DB	Database name	fitpub
POSTGRES_USER	Database user	fitpub
POSTGRES_PASSWORD	Database password	MUST CHANGE
POSTGRES_PORT	Database port	5432
APP_PORT	Application port	8080
APP_DOMAIN	Your domain name	example.com
APP_BASE_URL	Full application URL	https://example.com
JWT_SECRET	JWT signing secret	MUST CHANGE
JWT_EXPIRATION_MS	JWT expiration time	86400000 (24h)

Docker Compose Services

postgres

• Image: postgis/postgis:16-3.4
• Port: 5432 (configurable via POSTGRES_PORT)
• Volume: postgres_data - Persistent database storage
• Health Check: PostgreSQL readiness check

app

• Build: From Dockerfile
• Port: 8080 (configurable via APP_PORT)
• Volumes:
  • app_uploads - User uploaded files
  • app_logs - Application logs
• Health Check: Spring Boot Actuator health endpoint
• Depends On: postgres (waits for healthy state)

Volumes

Three named volumes are created for data persistence:

# List volumes
docker volume ls | grep fitpub

# Inspect volume
docker volume inspect feditrack_postgres_data

# Backup database volume
docker run --rm -v feditrack_postgres_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres-backup-$(date +%Y%m%d).tar.gz -C /data .

# Restore database volume
docker run --rm -v feditrack_postgres_data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/postgres-backup-YYYYMMDD.tar.gz -C /data

Common Operations

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f app
docker-compose logs -f postgres

Restart Services

# Restart all services
docker-compose restart

# Restart specific service
docker-compose restart app

Stop Services

# Stop services (keeps containers)
docker-compose stop

# Stop and remove containers (keeps volumes)
docker-compose down

# Stop and remove everything including volumes (DANGER: data loss)
docker-compose down -v

Execute Commands in Container

# Access app container shell
docker-compose exec app bash

# Access PostgreSQL CLI
docker-compose exec postgres psql -U fitpub -d fitpub

# Run SQL query
docker-compose exec postgres psql -U fitpub -d fitpub -c "SELECT version();"

Database Operations

# Create database backup
docker-compose exec postgres pg_dump -U fitpub fitpub > backup.sql

# Restore database backup
docker-compose exec -T postgres psql -U fitpub fitpub < backup.sql

# Check Flyway migration status
docker-compose exec postgres psql -U fitpub -d fitpub -c \
  "SELECT * FROM flyway_schema_history ORDER BY installed_rank;"

Rebuild Application

# Rebuild and restart app
docker-compose up -d --build app

# Force rebuild without cache
docker-compose build --no-cache app
docker-compose up -d app

Production Deployment

Security Checklist

• Change POSTGRES_PASSWORD to a strong random password
• Generate secure JWT_SECRET using openssl rand -base64 64
• Set correct APP_DOMAIN and APP_BASE_URL
• Configure HTTPS/TLS (use reverse proxy like nginx or Traefik)
• Disable JPA_SHOW_SQL and JPA_FORMAT_SQL
• Set appropriate log levels (INFO or WARN for production)
• Configure firewall rules (only expose necessary ports)
• Set up regular database backups
• Configure volume backup strategy
• Review and restrict network access

Reverse Proxy Example (nginx)

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Monitoring

Health Checks

# Application health
curl http://localhost:8080/actuator/health

# Database health
docker-compose exec postgres pg_isready -U fitpub

Resource Usage

# Container stats
docker stats

# Specific container stats
docker stats fitpub-app fitpub-postgres

Troubleshooting

Application Won't Start

# Check logs
docker-compose logs app

# Check if database is ready
docker-compose ps postgres
docker-compose exec postgres pg_isready -U fitpub

# Verify environment variables
docker-compose config

Database Connection Issues

# Check PostgreSQL logs
docker-compose logs postgres

# Test database connection
docker-compose exec postgres psql -U fitpub -d fitpub -c "SELECT 1;"

# Check network connectivity
docker-compose exec app ping postgres

Migration Failures

# Check Flyway schema history
docker-compose exec postgres psql -U fitpub -d fitpub -c \
  "SELECT * FROM flyway_schema_history;"

# Reset database (DANGER: data loss)
docker-compose down -v
docker-compose up -d

Out of Disk Space

# Check Docker disk usage
docker system df

# Clean up unused resources
docker system prune -a --volumes

# Remove specific volume
docker volume rm feditrack_postgres_data

Development Mode

For local development with live reload:

# Use development profile
echo "SPRING_PROFILES_ACTIVE=dev" >> .env

# Enable SQL logging
echo "JPA_SHOW_SQL=true" >> .env
echo "JPA_FORMAT_SQL=true" >> .env

# Mount source code for live reload (modify docker-compose.yml)
# Add under app.volumes:
#   - ./src:/app/src

Scaling

To run multiple app instances behind a load balancer:

# Scale app service
docker-compose up -d --scale app=3

# Note: You'll need to configure a load balancer and remove
# the container_name directive from docker-compose.yml

Updating

# Pull latest code
git pull

# Rebuild and restart
docker-compose down
docker-compose up -d --build

# Check migration status
docker-compose logs app | grep -i flyway