Alexis Bruneteau 368bb38057 chore: Setup complete Docker Compose configuration

Comprehensive Docker Compose setup with all services:

Services:
  • MariaDB 11 - Database with persistent storage
  • FastAPI Backend - Python 3.12 with Poetry
  • Next.js Frontend - Node 20 with production build
  • Adminer - Optional database management UI

Features:
  ✓ Health checks for all services
  ✓ Proper dependency ordering (database -> backend -> frontend)
  ✓ Networking with private subnet (172.20.0.0/16)
  ✓ Volume management for data persistence
  ✓ Environment variable configuration
  ✓ Logging configuration (10MB max, 3 files)
  ✓ Restart policies (unless-stopped)

Configuration Files:
  • docker-compose.yml - Production-ready compose file
  • .env - Development environment variables
  • .env.example - Template for environment setup
  • DOCKER_SETUP.md - Comprehensive setup guide

Improvements:
  • Added curl to backend Dockerfile for health checks
  • Better error handling and startup sequencing
  • Database initialization with multiple SQL files
  • Adminer for easy database management (port 8080)
  • Detailed logging with file rotation
  • Production-ready with comments and documentation

Environment Variables:
  Database:
    DB_HOST=mariadb, DB_PORT=3306
    DB_NAME=evoting_db, DB_USER=evoting_user
    DB_PASSWORD=evoting_pass123

  Services:
    BACKEND_PORT=8000, FRONTEND_PORT=3000

  Security:
    SECRET_KEY=your-secret-key-change-in-production
    DEBUG=false (for production)

Health Checks:
  • Database: mariadb-admin ping
  • Backend: curl /health endpoint
  • Frontend: wget to port 3000

Volumes:
  • evoting_data - MariaDB persistent storage
  • backend_cache - Backend cache directory

Networks:
  • evoting_network (172.20.0.0/16)
  • Internal service-to-service communication

Quick Start:
  1. cp .env.example .env
  2. docker-compose up -d
  3. http://localhost:3000 (frontend)
  4. http://localhost:8000/docs (API docs)
  5. http://localhost:8080 (database admin)

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-07 02:09:07 +01:00

10 KiB

Raw Blame History

E-Voting System - Docker Setup Guide

Complete guide to running the e-voting system with Docker Compose.

Prerequisites

Docker (20.10 or later)
Docker Compose (2.0 or later)
Git

Verify installation:

docker --version
docker-compose --version

Quick Start

1. Clone and Navigate

cd /path/to/e-voting-system

2. Create Environment File

Copy the example environment file:

cp .env.example .env

Configure as needed in .env:

DB_HOST=mariadb
DB_PORT=3306
DB_NAME=evoting_db
DB_USER=evoting_user
DB_PASSWORD=evoting_pass123
DB_ROOT_PASSWORD=rootpass123

BACKEND_PORT=8000
FRONTEND_PORT=3000

SECRET_KEY=your-secret-key-change-in-production

DEBUG=true
PYTHONUNBUFFERED=1

NEXT_PUBLIC_API_URL=http://localhost:8000

3. Start the Application

docker-compose up -d

This will:

✅ Build the backend (FastAPI)
✅ Build the frontend (Next.js)
✅ Start MariaDB database
✅ Start all services with proper networking

4. Wait for Services to Be Ready

Check service status:

docker-compose ps

Expected output:

NAME                 STATUS              PORTS
evoting_db           Up (healthy)        0.0.0.0:3306->3306/tcp
evoting_backend      Up (healthy)        0.0.0.0:8000->8000/tcp
evoting_frontend     Up (healthy)        0.0.0.0:3000->3000/tcp
evoting_adminer      Up                  0.0.0.0:8080->8080/tcp

5. Access the Application

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Docs: http://localhost:8000/docs
Database Admin: http://localhost:8080

Services

MariaDB (Database)

Container: evoting_db
Port: 3306 (internal), 3306 (exposed)
Database: evoting_db
User: evoting_user
Password: evoting_pass123
Volume: evoting_data (persistent)

Tables created automatically:

voters - User accounts
elections - Election definitions
candidates - Election candidates
votes - Cast votes
blockchain_blocks - Blockchain records (if applicable)

Backend (FastAPI)

Container: evoting_backend
Port: 8000 (internal), 8000 (exposed)
Framework: FastAPI (Python 3.12)
Volume: ./backend (live reload)
Dependencies: Installed via Poetry

Available endpoints:

GET /health - Health check
GET /docs - Swagger UI
GET /redoc - ReDoc documentation
POST /api/auth/register - User registration
POST /api/auth/login - User login
GET/POST /api/votes/* - Voting endpoints
GET /api/elections - Election list
GET /api/elections/{id} - Election details

Frontend (Next.js)

Container: evoting_frontend
Port: 3000 (internal), 3000 (exposed)
Framework: Next.js 15 (Node.js 20)
Build: Production build with optimizations
API URL: Configured to http://localhost:8000

Routes:

/ - Home page
/auth/login - Login
/auth/register - Registration
/dashboard - Voter dashboard
/dashboard/votes/active - Active elections
/dashboard/votes/upcoming - Upcoming elections
/dashboard/votes/history - Vote history
/dashboard/blockchain - Blockchain viewer

Adminer (Optional Database UI)

Container: evoting_adminer
Port: 8080
Access: http://localhost:8080
System: MariaDB
Server: mariadb
Username: evoting_user
Password: evoting_pass123

Common Commands

Start Services

# Start in foreground (see logs)
docker-compose up

# Start in background
docker-compose up -d

# Start specific service
docker-compose up -d backend

Stop Services

# Stop all services
docker-compose stop

# Stop and remove containers
docker-compose down

# Stop and remove all data
docker-compose down -v

View Logs

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f mariadb

# View last 50 lines
docker-compose logs --tail 50

Rebuild Services

# Rebuild all services
docker-compose build

# Rebuild specific service
docker-compose build --no-cache backend

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

Access Container Shell

# Backend shell
docker-compose exec backend bash

# Frontend shell
docker-compose exec frontend sh

# Database shell
docker-compose exec mariadb bash

Database Operations

# Connect to database
docker-compose exec mariadb mysql -u evoting_user -p evoting_db
# Password: evoting_pass123

# Backup database
docker-compose exec mariadb mysqldump -u evoting_user -p evoting_db > backup.sql
# Password: evoting_pass123

# Restore database
docker-compose exec -T mariadb mysql -u evoting_user -p evoting_db < backup.sql
# Password: evoting_pass123

Health Check

# Check service health
docker-compose exec backend curl http://localhost:8000/health

# View health in ps
docker-compose ps

# Manual database check
docker-compose exec mariadb mariadb-admin ping -h localhost -u evoting_user -p
# Password: evoting_pass123

Troubleshooting

Services Won't Start

Check logs:
```
docker-compose logs
```

Check ports are available:

lsof -i :3000
lsof -i :8000
lsof -i :3306

Remove conflicting containers:

docker-compose down
docker container prune
docker system prune

Rebuild services:

docker-compose build --no-cache
docker-compose up -d

Database Connection Error

Check database is healthy:

docker-compose ps mariadb
# Should show "Up (healthy)"

Check database logs:
```
docker-compose logs mariadb
```
Wait longer for startup:
- MariaDB can take 30-60 seconds to fully initialize
- Check health status with docker-compose ps
Verify credentials in .env:
```
cat .env | grep DB_
```

Backend Can't Reach Database

Check network:

docker-compose exec backend ping mariadb

Check environment variables:

docker-compose exec backend env | grep DB_

Verify connection string:

docker-compose exec backend python -c "from backend.config import settings; print(settings.database_url)"

Frontend Can't Reach Backend

Check API URL configuration:

docker-compose logs frontend | grep API

Test backend availability:

docker-compose exec frontend curl http://backend:8000/health

Check NEXT_PUBLIC_API_URL:
- For Docker: http://backend:8000
- For browser: http://localhost:8000

Development Workflow

Edit Code and Reload

# Changes to backend are auto-reloaded (uvicorn with --reload)
# Edit files in backend/
vim backend/routes/votes.py

# Changes to frontend require rebuild
# Edit files in frontend/
vim frontend/components/blockchain-viewer.tsx

# Rebuild frontend only
docker-compose build frontend
docker-compose up -d frontend

Access Development Tools

# Backend interactive Python
docker-compose exec backend python

# Frontend package management
docker-compose exec frontend npm install package-name

# Run frontend build
docker-compose exec frontend npm run build

Database Initialization

The database is automatically initialized on first run with:

docker/init.sql - Schema and tables
docker/populate_past_elections.sql - Sample data

To reinitialize:

docker-compose down -v
docker-compose up -d mariadb
# Wait for database to be healthy
docker-compose up

Production Deployment

Environment Configuration

Create .env with production values:

# Change all sensitive values
DB_PASSWORD=strong-random-password
DB_ROOT_PASSWORD=strong-random-password
SECRET_KEY=strong-random-secret-key

# Disable debug
DEBUG=false

# Set production API URL
NEXT_PUBLIC_API_URL=https://yourdomain.com

# Change ports if needed
BACKEND_PORT=8000
FRONTEND_PORT=3000

Production Build

# Pull latest code
git pull origin main

# Build images
docker-compose build --no-cache

# Start services
docker-compose up -d

# Verify
docker-compose ps

Backup Strategy

# Automated daily backup
0 2 * * * docker-compose exec -T mariadb mysqldump -u evoting_user -p"$PASSWORD" evoting_db > /backups/evoting_$(date +\%Y\%m\%d).sql

# Manual backup
docker-compose exec mariadb mysqldump -u evoting_user -p evoting_db > backup.sql

Monitoring

# View resource usage
docker stats

# View all logs
docker-compose logs -f --tail 100

# Check health status
watch -n 5 docker-compose ps

Networking

Service Discovery

Services can communicate within the network:

Database: mysql://evoting_user:evoting_pass123@mariadb:3306/evoting_db
Backend API: http://backend:8000
Frontend: http://frontend:3000

External Access

From outside Docker:

Frontend: http://localhost:3000
Backend: http://localhost:8000
Database: mysql://evoting_user:evoting_pass123@localhost:3306/evoting_db
Adminer: http://localhost:8080

Performance Tuning

Database

# In docker-compose.yml, adjust mariadb service
environment:
  MYSQL_MAX_CONNECTIONS: 100
  INNODB_BUFFER_POOL_SIZE: 256M

Backend

# Increase Python process
command: uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4

Frontend

# Increase Node memory if needed
environment:
  NODE_OPTIONS: --max-old-space-size=4096

Security Recommendations

Change default passwords in .env
Use strong SECRET_KEY (generate with openssl rand -hex 32)
Enable HTTPS with reverse proxy (nginx)
Restrict database access (bind to local network only)
Use secrets management (Docker Secrets, HashiCorp Vault)
Regular backups with offsite storage
Keep images updated with docker-compose pull && docker-compose up -d --build

Additional Resources

Docker Compose Docs: https://docs.docker.com/compose/
FastAPI Docs: https://fastapi.tiangolo.com/
Next.js Docs: https://nextjs.org/docs
MariaDB Docs: https://mariadb.com/docs/

Support

For issues, check:

Docker logs: docker-compose logs
Service health: docker-compose ps
Network connectivity: docker-compose exec service-name ping other-service
Environment variables: docker-compose config

Version: 1.0.0 Last Updated: 2025-11-07 Maintainer: E-Voting Team

10 KiB Raw Blame History