Alexis Bruneteau d4ce64f097 docs: Add test runner and backend startup guides for blockchain integration

2025-11-07 03:01:59 +01:00

9.2 KiB

Raw Blame History

Backend Startup Guide

Quick Start

# Start all services (database, backend, frontend)
docker compose up -d

# Wait for initialization (30-40 seconds)
sleep 40

# Verify backend is running
curl http://localhost:8000/health

# Should return:
# {"status": "ok", "version": "0.1.0"}

What Happens on Startup

1. MariaDB Database Starts (10-20 seconds)

Container starts
Database initialized from docker/init.sql
Creates tables: voters, elections, candidates, votes, audit_logs
Inserts sample election and candidates
Runs docker/populate_past_elections.sql (adds 10 past elections)
Runs docker/create_active_election.sql (ensures election 1 is active)

2. Backend Starts (5-10 seconds)

FastAPI application loads
Database connection established
Blockchain initialization begins:
- Loads all elections from database
- Records each to blockchain if not already recorded
- Verifies blockchain integrity
- Prints status: ✓ Blockchain integrity verified - N blocks
Backend ready to serve requests

3. Frontend Starts (5-10 seconds)

Next.js application builds and starts
Connects to backend API

Startup Timeline

docker compose up -d
  |
  ├─ MariaDB starts (10-20s)
  │   ├─ init.sql runs (create tables)
  │   ├─ populate_past_elections.sql runs (past data)
  │   └─ create_active_election.sql runs (make election 1 active)
  │
  ├─ Backend starts (5-10s)
  │   ├─ FastAPI loads
  │   ├─ Blockchain initialization starts
  │   │   ├─ Load elections from DB
  │   │   ├─ Record to blockchain
  │   │   └─ Verify integrity
  │   └─ Backend ready
  │
  └─ Frontend starts (5-10s)
      └─ Next.js ready

Total startup time: 30-45 seconds

Status Checks

Check All Services

docker compose ps

Expected:

NAME                 STATUS           PORTS
evoting_mariadb      healthy (running)
evoting_backend      healthy (running)  127.0.0.1:8000->8000/tcp
evoting_frontend     healthy (running)  127.0.0.1:3000->3000/tcp
evoting_adminer      healthy (running)  127.0.0.1:8081->8080/tcp

Check Backend Health

curl http://localhost:8000/health

Expected:

{"status": "ok", "version": "0.1.0"}

If you get 502 Bad Gateway:

Backend is still starting
Wait another 10-20 seconds
Try again

Check Database Health

# Connect to database
docker compose exec mariadb mariadb -u evoting_user -pevoting_pass123 evoting_db

# Query elections
MariaDB [evoting_db]> SELECT id, name, is_active FROM elections LIMIT 5;

# Expected: Election 1 should be active with recent dates

Check Blockchain Initialization

# View backend logs
docker compose logs backend | grep -i blockchain

# Should show:
# ✓ Recorded election 1 (Election Présidentielle 2025) to blockchain
# ✓ Blockchain integrity verified - 1 blocks

Common Startup Issues

Issue 1: 502 Bad Gateway on All Endpoints

Cause: Backend is still initializing

Solution:

# Wait longer
sleep 30

# Check if backend is up
curl http://localhost:8000/health

# If still 502, check logs
docker compose logs backend | tail -50

Issue 2: Database Won't Start

Symptoms:

docker compose logs mariadb
# Error: "InnoDB: Specified key was too long"
# or: "Address already in use"

Solutions:

Option A - Different port:

# Stop and remove containers
docker compose down

# Change port in docker-compose.yml:
# mariadb:
#   ports:
#     - "3307:3306"  # Changed from 3306

docker compose up -d

Option B - Fresh database:

# Remove database volume
docker compose down -v

# Start fresh
docker compose up -d
sleep 40

Issue 3: Backend Import Errors

Symptoms:

docker compose logs backend
# ModuleNotFoundError: No module named 'blockchain_elections'
# or: ImportError: cannot import name 'initialize_elections_blockchain'

Solution:

# Rebuild backend with new modules
docker compose down
docker compose up -d --build backend
sleep 40

Issue 4: Port Already in Use

Symptoms:

docker compose up -d
# Error: "bind: address already in use"

Solution:

# Kill the process using the port
sudo lsof -i :8000
sudo kill -9 <PID>

# Or stop competing containers
docker ps
docker stop <container_name>

# Then start again
docker compose up -d

Issue 5: Frontend Can't Connect to Backend

Symptoms:

Frontend loads but shows error fetching elections
Network requests to /api/elections/active return 502

Solution:

# Wait for backend to fully initialize
sleep 40

# Check backend is running
curl http://localhost:8000/api/elections/active

# Check frontend environment variable
docker compose logs frontend | grep NEXT_PUBLIC_API_URL

# Should be: http://localhost:8000

Startup Verification Checklist

After docker compose up -d, verify each step:

Wait 40 seconds
Backend health: curl http://localhost:8000/health → 200 OK
Database has elections: curl http://localhost:8000/api/elections/debug/all → shows elections
Active election exists: curl http://localhost:8000/api/elections/active → shows 1+ elections
Blockchain initialized: curl http://localhost:8000/api/elections/blockchain → shows blocks
Blockchain verified: curl http://localhost:8000/api/elections/1/blockchain-verify → "verified": true
Frontend loads: curl http://localhost:3000 → 200 OK
Frontend can fetch elections: Browser console shows no errors

Debugging Tips

View All Logs

docker compose logs -f

Follow output as services start.

View Specific Service Logs

# Backend
docker compose logs backend -f

# Database
docker compose logs mariadb -f

# Frontend
docker compose logs frontend -f

Check Database Content

# Connect to database
docker compose exec mariadb mariadb -u evoting_user -pevoting_pass123 evoting_db

# See elections
SELECT id, name, is_active, start_date, end_date FROM elections LIMIT 5;

# See candidates
SELECT c.id, c.name, c.election_id FROM candidates LIMIT 10;

# Exit
exit

Check Backend API Directly

# Health check
curl http://localhost:8000/health

# Active elections
curl http://localhost:8000/api/elections/active

# All elections (with debug info)
curl http://localhost:8000/api/elections/debug/all

# Blockchain
curl http://localhost:8000/api/elections/blockchain

# Verify election
curl http://localhost:8000/api/elections/1/blockchain-verify

Restart Services

# Restart just backend
docker compose restart backend
sleep 10

# Restart database
docker compose restart mariadb
sleep 20

# Restart frontend
docker compose restart frontend
sleep 5

# Restart all
docker compose down
docker compose up -d
sleep 40

Fresh Start (Nuclear Option)

# Stop everything
docker compose down

# Remove all data
docker compose down -v

# Remove all containers/images
docker system prune -a

# Start fresh
docker compose up -d
sleep 40

# Verify
curl http://localhost:8000/health

Expected Responses

Healthy Backend

GET /health

{"status": "ok", "version": "0.1.0"}

GET /api/elections/active

[
  {
    "id": 1,
    "name": "Election Présidentielle 2025",
    "description": "Vote pour la présidence",
    "start_date": "2025-11-07T01:59:00",
    "end_date": "2025-11-14T01:59:00",
    "is_active": true,
    "results_published": false
  }
]

GET /api/elections/blockchain

{
  "blocks": [
    {
      "index": 0,
      "election_id": 1,
      "election_name": "Election Présidentielle 2025",
      "candidates_count": 4,
      "block_hash": "...",
      "signature": "...",
      ...
    }
  ],
  "verification": {
    "chain_valid": true,
    "total_blocks": 1,
    "timestamp": "2025-11-07T03:00:00.123456"
  }
}

GET /api/elections/1/blockchain-verify

{
  "verified": true,
  "election_id": 1,
  "election_name": "Election Présidentielle 2025",
  "hash_valid": true,
  "chain_valid": true,
  "signature_valid": true
}

Database Adminer

Access database management UI:

URL: http://localhost:8081
Server: mariadb
User: evoting_user
Password: evoting_pass123
Database: evoting_db

Use this to:

View tables
Run SQL queries
Add test data
Inspect blockchain integrity

Next Steps

Once backend is healthy:

Test blockchain integration
```
python3 test_blockchain_election.py
```

Verify elections exist

curl http://localhost:8000/api/elections/active | jq '.'

Check blockchain

curl http://localhost:8000/api/elections/blockchain | jq '.blocks | length'

Register and vote
- Open http://localhost:3000
- Register as voter
- Participate in active election
View blockchain (future)
- Create page with blockchain visualizer component
- Show elections on immutable blockchain
- Verify integrity status

Support

If issues persist:

Check logs: docker compose logs
Read documentation: See BLOCKCHAIN_*.md files
Run tests: python3 test_blockchain_election.py
Try fresh start: docker compose down -v && docker compose up -d

9.2 KiB Raw Blame History

Backend Startup Guide

Quick Start

What Happens on Startup

1. MariaDB Database Starts (10-20 seconds)

2. Backend Starts (5-10 seconds)

3. Frontend Starts (5-10 seconds)

Startup Timeline

Status Checks

Check All Services

Check Backend Health

Check Database Health

Check Blockchain Initialization

Common Startup Issues

Issue 1: 502 Bad Gateway on All Endpoints

Issue 2: Database Won't Start

Issue 3: Backend Import Errors

Issue 4: Port Already in Use

Issue 5: Frontend Can't Connect to Backend

Startup Verification Checklist

Debugging Tips

View All Logs

View Specific Service Logs

Check Database Content

Check Backend API Directly

Restart Services

Fresh Start (Nuclear Option)

Expected Responses

Healthy Backend

Database Adminer

Next Steps

Support

9.2 KiB

Raw Blame History