350 lines
7.3 KiB
Markdown
350 lines
7.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd feditrack
|
|
```
|
|
|
|
### 2. Create Environment File
|
|
|
|
Copy the example environment file and customize it:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
### 3. Configure Environment Variables
|
|
|
|
Edit `.env` and update the following critical values:
|
|
|
|
**Security (REQUIRED):**
|
|
```bash
|
|
# 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):**
|
|
```bash
|
|
APP_DOMAIN=your-domain.com
|
|
APP_BASE_URL=https://your-domain.com
|
|
```
|
|
|
|
### 4. Start the Application
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# All services
|
|
docker-compose logs -f
|
|
|
|
# Specific service
|
|
docker-compose logs -f app
|
|
docker-compose logs -f postgres
|
|
```
|
|
|
|
### Restart Services
|
|
|
|
```bash
|
|
# Restart all services
|
|
docker-compose restart
|
|
|
|
# Restart specific service
|
|
docker-compose restart app
|
|
```
|
|
|
|
### Stop Services
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```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
|
|
|
|
```bash
|
|
# Application health
|
|
curl http://localhost:8080/actuator/health
|
|
|
|
# Database health
|
|
docker-compose exec postgres pg_isready -U fitpub
|
|
```
|
|
|
|
### Resource Usage
|
|
|
|
```bash
|
|
# Container stats
|
|
docker stats
|
|
|
|
# Specific container stats
|
|
docker stats fitpub-app fitpub-postgres
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Application Won't Start
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```
|