370 lines
7.1 KiB
Markdown
370 lines
7.1 KiB
Markdown
# Docker Deployment Guide
|
|
|
|
This guide explains how to deploy your Groceries/Product Tracker application using Docker Compose.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker Engine 20.10+
|
|
- Docker Compose 2.0+
|
|
- Git (for cloning from your Gitea repository)
|
|
|
|
## Quick Start
|
|
|
|
1. **Clone your repository from Gitea:**
|
|
```bash
|
|
git clone <your-gitea-repo-url>
|
|
cd groceries
|
|
```
|
|
|
|
2. **Set up environment variables:**
|
|
```bash
|
|
cp docker.env.example .env
|
|
# Edit .env with your production values
|
|
nano .env
|
|
```
|
|
|
|
3. **Build and start all services:**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. **Access your application:**
|
|
- Frontend: http://localhost
|
|
- Backend API: http://localhost:8000
|
|
- API Documentation: http://localhost:8000/docs
|
|
|
|
## Architecture
|
|
|
|
The Docker Compose setup includes:
|
|
|
|
- **PostgreSQL Database** (port 5432)
|
|
- **FastAPI Backend** (port 8000)
|
|
- **React Frontend with Nginx** (port 80)
|
|
|
|
## Environment Configuration
|
|
|
|
### Required Environment Variables
|
|
|
|
Create a `.env` file in the root directory:
|
|
|
|
```bash
|
|
# Database Configuration
|
|
DB_PASSWORD=your_secure_database_password
|
|
|
|
# Backend Configuration
|
|
SECRET_KEY=your-super-secret-key-for-jwt-tokens-make-it-very-long-and-random
|
|
DEBUG=False
|
|
```
|
|
|
|
### Optional Configuration
|
|
|
|
You can override default ports by adding to your `.env` file:
|
|
|
|
```bash
|
|
# Custom ports (optional)
|
|
FRONTEND_PORT=3000
|
|
BACKEND_PORT=8001
|
|
DB_PORT=5433
|
|
```
|
|
|
|
Then update the docker-compose.yml ports section accordingly.
|
|
|
|
## Deployment Commands
|
|
|
|
### Development Deployment
|
|
|
|
```bash
|
|
# Start all services
|
|
docker-compose up
|
|
|
|
# Start in background
|
|
docker-compose up -d
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
|
|
# View logs for specific service
|
|
docker-compose logs -f backend
|
|
```
|
|
|
|
### Production Deployment
|
|
|
|
1. **Set production environment:**
|
|
```bash
|
|
export COMPOSE_FILE=docker-compose.yml
|
|
export COMPOSE_PROJECT_NAME=groceries_prod
|
|
```
|
|
|
|
2. **Use production environment file:**
|
|
```bash
|
|
cp docker.env.example .env.prod
|
|
# Edit .env.prod with production values
|
|
docker-compose --env-file .env.prod up -d
|
|
```
|
|
|
|
3. **Run database migrations:**
|
|
```bash
|
|
docker-compose exec backend alembic upgrade head
|
|
```
|
|
|
|
## Database Management
|
|
|
|
### Initial Setup
|
|
|
|
The database will be automatically created when you first start the services. To run migrations:
|
|
|
|
```bash
|
|
# Run migrations
|
|
docker-compose exec backend alembic upgrade head
|
|
|
|
# Create new migration (if you've made model changes)
|
|
docker-compose exec backend alembic revision --autogenerate -m "Description"
|
|
```
|
|
|
|
### Backup and Restore
|
|
|
|
```bash
|
|
# Backup database
|
|
docker-compose exec db pg_dump -U product_user product_tracker > backup.sql
|
|
|
|
# Restore database
|
|
docker-compose exec -T db psql -U product_user product_tracker < backup.sql
|
|
```
|
|
|
|
## Service Management
|
|
|
|
### Individual Service Control
|
|
|
|
```bash
|
|
# Restart specific service
|
|
docker-compose restart backend
|
|
|
|
# Rebuild and restart service
|
|
docker-compose up -d --build backend
|
|
|
|
# Scale services (if needed)
|
|
docker-compose up -d --scale backend=2
|
|
```
|
|
|
|
### Updating the Application
|
|
|
|
```bash
|
|
# Pull latest code from Gitea
|
|
git pull origin main
|
|
|
|
# Rebuild and restart services
|
|
docker-compose down
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
## Monitoring and Logs
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
# All services
|
|
docker-compose logs -f
|
|
|
|
# Specific service
|
|
docker-compose logs -f backend
|
|
docker-compose logs -f frontend
|
|
docker-compose logs -f db
|
|
|
|
# Last 100 lines
|
|
docker-compose logs --tail=100 backend
|
|
```
|
|
|
|
### Health Checks
|
|
|
|
The services include health checks. Check status:
|
|
|
|
```bash
|
|
docker-compose ps
|
|
```
|
|
|
|
### Resource Usage
|
|
|
|
```bash
|
|
# View resource usage
|
|
docker stats
|
|
|
|
# View specific containers
|
|
docker stats groceries_backend groceries_frontend groceries_db
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Port conflicts:**
|
|
```bash
|
|
# Check what's using the port
|
|
lsof -i :80
|
|
lsof -i :8000
|
|
lsof -i :5432
|
|
|
|
# Change ports in .env file or docker-compose.yml
|
|
```
|
|
|
|
2. **Database connection issues:**
|
|
```bash
|
|
# Check database logs
|
|
docker-compose logs db
|
|
|
|
# Test database connection
|
|
docker-compose exec db psql -U product_user -d product_tracker -c "SELECT 1;"
|
|
```
|
|
|
|
3. **Backend not starting:**
|
|
```bash
|
|
# Check backend logs
|
|
docker-compose logs backend
|
|
|
|
# Exec into container to debug
|
|
docker-compose exec backend bash
|
|
```
|
|
|
|
4. **Frontend not loading:**
|
|
```bash
|
|
# Check nginx logs
|
|
docker-compose logs frontend
|
|
|
|
# Verify build completed successfully
|
|
docker-compose exec frontend ls -la /usr/share/nginx/html
|
|
```
|
|
|
|
### Reset Everything
|
|
|
|
```bash
|
|
# Stop and remove all containers, networks, and volumes
|
|
docker-compose down -v
|
|
|
|
# Remove all images
|
|
docker-compose down --rmi all
|
|
|
|
# Start fresh
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### Production Security
|
|
|
|
1. **Change default passwords:**
|
|
- Update `DB_PASSWORD` in `.env`
|
|
- Generate a strong `SECRET_KEY`
|
|
|
|
2. **Use HTTPS:**
|
|
- Add SSL certificates
|
|
- Configure nginx for HTTPS
|
|
- Update docker-compose.yml with SSL configuration
|
|
|
|
3. **Network security:**
|
|
- Remove port mappings for internal services
|
|
- Use Docker secrets for sensitive data
|
|
- Configure firewall rules
|
|
|
|
4. **Regular updates:**
|
|
- Keep Docker images updated
|
|
- Update application dependencies
|
|
- Monitor security advisories
|
|
|
|
### Example Production docker-compose.yml
|
|
|
|
For production, consider:
|
|
|
|
```yaml
|
|
# Remove port mappings for internal services
|
|
services:
|
|
db:
|
|
# Remove: ports: - "5432:5432"
|
|
|
|
backend:
|
|
# Remove: ports: - "8000:8000"
|
|
|
|
frontend:
|
|
ports:
|
|
- "443:443" # HTTPS
|
|
- "80:80" # HTTP redirect
|
|
```
|
|
|
|
## Gitea Integration
|
|
|
|
### Automated Deployment
|
|
|
|
You can set up automated deployment from your Gitea repository:
|
|
|
|
1. **Create a webhook** in your Gitea repository
|
|
2. **Set up a deployment script** on your server:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# deploy.sh
|
|
cd /path/to/your/app
|
|
git pull origin main
|
|
docker-compose down
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
3. **Configure webhook** to trigger the deployment script
|
|
|
|
### CI/CD Pipeline
|
|
|
|
Consider setting up Gitea Actions or external CI/CD:
|
|
|
|
```yaml
|
|
# .gitea/workflows/deploy.yml
|
|
name: Deploy
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
jobs:
|
|
deploy:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Deploy to server
|
|
run: |
|
|
# Your deployment commands
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
## Performance Optimization
|
|
|
|
### Production Optimizations
|
|
|
|
1. **Use multi-stage builds** (already implemented)
|
|
2. **Enable gzip compression** in nginx
|
|
3. **Add caching headers** (already configured)
|
|
4. **Use connection pooling** for database
|
|
5. **Configure resource limits:**
|
|
|
|
```yaml
|
|
services:
|
|
backend:
|
|
deploy:
|
|
resources:
|
|
limits:
|
|
memory: 512M
|
|
cpus: '0.5'
|
|
```
|
|
|
|
## Backup Strategy
|
|
|
|
### Automated Backups
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# backup.sh
|
|
DATE=$(date +%Y%m%d_%H%M%S)
|
|
docker-compose exec -T db pg_dump -U product_user product_tracker > "backup_${DATE}.sql"
|
|
# Upload to cloud storage or remote location
|
|
```
|
|
|
|
Set up a cron job:
|
|
```bash
|
|
# Run daily at 2 AM
|
|
0 2 * * * /path/to/backup.sh
|
|
```
|
|
|
|
This setup provides a robust, production-ready deployment of your groceries application using Docker Compose! |