hxbooks/docs/DEPLOYMENT.md

HXBooks Docker Deployment

This directory contains Docker Compose configuration for deploying HXBooks with Caddy as a reverse proxy.

Architecture

• App Container: Runs the Flask application on port 5000
• Caddy Container: Reverse proxy with automatic HTTPS, serves static files directly
• Database Initialization: Automatic on first startup (creates SQLite database and runs migrations)
• Volumes:
  • media: Book cover images (shared between app and Caddy)
  • static: CSS/JS files (copied from app to volume on startup, served by Caddy)
  • instance: Application configuration and SQLite database
  • caddy_data: TLS certificates
  • caddy_config: Caddy configuration cache

Quick Start

1. Development (localhost):

   docker-compose up -d
   

   Access the app at http://localhost

2. Production with your domain:

   • Edit Caddyfile and replace localhost with your domain
   • Run: docker-compose up -d
   • Caddy will automatically obtain TLS certificates

Configuration

Environment Variables

Set these in your docker-compose.yml or create a .env file:

# Flask configuration
FLASK_ENV=production
SECRET_KEY=your-secret-key-here

# Optional: Google Books API key
GOOGLE_BOOKS_API_KEY=your-api-key

Custom Configuration

Create instance/config.py for local overrides:

SECRET_KEY = "your-production-secret-key"
GOOGLE_BOOKS_API_KEY = "your-api-key" 
# Add other Flask config as needed

Commands

# Start services
docker-compose up -d

# View logs
docker-compose logs -f app
docker-compose logs -f caddy

# Stop services
docker-compose down

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

# Remove everything including volumes (⚠️ destroys data)
docker-compose down -v

File Serving Strategy

• Static files (CSS/JS): Copied from app container to shared volume on startup, served directly by Caddy
• Media files (book covers): Stored in shared volume, served directly by Caddy
• Application routes: Proxied to Flask app

This setup provides optimal performance by having Caddy serve static assets while the Flask app handles dynamic content.

Database Initialization

The application handles database setup automatically on first startup:

1. Fresh Install: Creates SQLite database and initializes tables using hxbooks db init
2. Existing Database: Runs Flask-Migrate migrations with flask db upgrade
3. Database Location: /app/instance/hxbooks.sqlite (persisted in instance volume)

Manual Database Operations (if needed):

# Connect to running container
docker-compose exec app sh

# Initialize database manually
hxbooks db init

# Create new migration
flask db migrate -m "description"

# Apply migrations
flask db upgrade

Production Notes

1. Database: Currently uses SQLite with volume persistence. For high-traffic sites, consider PostgreSQL.

2. Backups: The important data is in the instance and media volumes:

   # Backup
   docker run --rm -v hxbooks_instance:/source -v $(pwd):/backup alpine tar czf /backup/instance-backup.tar.gz -C /source .
   docker run --rm -v hxbooks_media:/source -v $(pwd):/backup alpine tar czf /backup/media-backup.tar.gz -C /source .
   

3. Updates: To update the application:

   docker-compose pull
   docker-compose up --build -d
   

4. Monitoring: Consider adding health check endpoints and monitoring services to the stack.