123 lines
3.4 KiB
Markdown
123 lines
3.4 KiB
Markdown
# 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)**:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```python
|
|
SECRET_KEY = "your-production-secret-key"
|
|
GOOGLE_BOOKS_API_KEY = "your-api-key"
|
|
# Add other Flask config as needed
|
|
```
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# 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):
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
docker-compose pull
|
|
docker-compose up --build -d
|
|
```
|
|
|
|
4. **Monitoring**: Consider adding health check endpoints and monitoring services to the stack. |