Goa-gel-fullstack/docs/development/DOCKER_SETUP.md

🐳 Docker Setup Guide - Goa-GEL Platform

Complete guide to run all Goa-GEL services in Docker.

---

🚀 Quick Start

# From the root directory
docker-compose up -d

# Wait for all services to be healthy (2-3 minutes)
docker-compose ps

# Access the services
open http://localhost:4200      # Frontend
open http://localhost:8080      # Documentation
open http://localhost:3001      # API
open http://localhost:4000      # Blockscout Explorer
open http://localhost:9001      # MinIO Console

---

📦 Services Included

1. Frontend (Angular)

• Port: 4200
• URL: http://localhost:4200
• Description: Main user interface for citizens, department officers, and admins

2. API Backend (NestJS)

• Port: 3001
• URL: http://localhost:3001
• Health: http://localhost:3001/health
• Swagger: http://localhost:3001/api
• Description: RESTful API backend with business logic

3. Documentation Service

• Port: 8080
• URL: http://localhost:8080
• Description: Static documentation site with user guides and technical docs

4. PostgreSQL Database

• Port: 5432
• Database: goa_gel_platform
• User: postgres
• Password: postgres_secure_password

5. Redis Cache

• Port: 6379
• Description: In-memory cache and job queue

6. MinIO Object Storage

• API Port: 9000
• Console Port: 9001
• Console URL: http://localhost:9001
• Credentials: minioadmin / minioadmin_secure
• Description: S3-compatible object storage for documents

7. Hyperledger Besu Blockchain

• RPC Port: 8545
• WebSocket Port: 8546
• P2P Port: 30303
• Description: Private Ethereum blockchain for license verification

8. Blockscout Explorer

• Port: 4000
• URL: http://localhost:4000
• Description: Blockchain explorer to view transactions and contracts

9. Blockscout Database

• Port: Internal only
• Description: PostgreSQL database for Blockscout

---

📋 Prerequisites

• Docker 20.10+ or Docker Desktop
• Docker Compose 1.29+
• Minimum Resources:
  • 8GB RAM
  • 20GB free disk space
  • 4 CPU cores

---

🔧 Configuration

Environment Variables

Create a .env file in the root directory:

# Copy example file
cp .env.example .env

# Edit the file
nano .env

Required Variables (will be populated after contract deployment):

• CONTRACT_ADDRESS_LICENSE_NFT
• CONTRACT_ADDRESS_APPROVAL_MANAGER
• CONTRACT_ADDRESS_DEPARTMENT_REGISTRY
• CONTRACT_ADDRESS_WORKFLOW_REGISTRY
• PLATFORM_WALLET_PRIVATE_KEY

---

🚀 Running Services

Start All Services

docker-compose up -d

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api
docker-compose logs -f frontend
docker-compose logs -f documentation

Check Service Status

docker-compose ps

Expected output:

NAME                      STATUS              PORTS
goa-gel-api               Up (healthy)        0.0.0.0:3001->3001/tcp
goa-gel-frontend          Up (healthy)        0.0.0.0:4200->80/tcp
goa-gel-documentation     Up (healthy)        0.0.0.0:8080->80/tcp
goa-gel-postgres          Up (healthy)        0.0.0.0:5432->5432/tcp
goa-gel-redis             Up (healthy)        0.0.0.0:6379->6379/tcp
goa-gel-minio             Up (healthy)        0.0.0.0:9000-9001->9000-9001/tcp
goa-gel-besu-1            Up (healthy)        0.0.0.0:8545-8546->8545-8546/tcp
goa-gel-blockscout        Up                  0.0.0.0:4000->4000/tcp
goa-gel-blockscout-db     Up (healthy)        5432/tcp

Stop Services

docker-compose stop

Restart Services

docker-compose restart

Stop and Remove Everything

docker-compose down

Stop and Remove with Volumes (⚠️ Deletes data)

docker-compose down -v

---

🔄 Updating Services

Rebuild After Code Changes

# Rebuild all services
docker-compose up -d --build

# Rebuild specific service
docker-compose up -d --build frontend
docker-compose up -d --build api

Update Docker Images

# Pull latest base images
docker-compose pull

# Restart services
docker-compose up -d

---

🐛 Troubleshooting

Port Already in Use

Check what's using the port:

lsof -i :4200  # Frontend
lsof -i :3001  # API
lsof -i :8080  # Documentation

Change ports in docker-compose.yml:

ports:
  - "4201:80"  # Change 4200 to 4201

Service Not Starting

View detailed logs:

docker-compose logs service-name

Check health status:

docker inspect --format='{{.State.Health.Status}}' container-name

Out of Memory

Increase Docker memory:

• Docker Desktop → Settings → Resources → Memory
• Recommended: 8GB minimum

Database Connection Failed

Wait for PostgreSQL to be ready:

docker-compose logs postgres

Manually check connection:

docker exec -it goa-gel-postgres psql -U postgres -d goa_gel_platform -c "SELECT 1;"

Blockchain Not Mining

Check Besu logs:

docker-compose logs besu-node-1

Verify RPC is accessible:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

---

📊 Service Health Checks

All services have health checks. Check status:

# API Health
curl http://localhost:3001/health

# Frontend Health
curl -I http://localhost:4200/

# Documentation Health
curl -I http://localhost:8080/

# Blockchain RPC
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

---

💾 Data Persistence

Data is stored in Docker volumes:

# List volumes
docker volume ls | grep goa-gel

# Inspect volume
docker volume inspect goa-gel_postgres_data

# Backup database
docker exec goa-gel-postgres pg_dump -U postgres goa_gel_platform > backup.sql

# Restore database
docker exec -i goa-gel-postgres psql -U postgres goa_gel_platform < backup.sql

---

🔐 Security Notes

Development Setup (Current)

• Default passwords (change in production)
• All ports exposed for debugging
• CORS allows all origins
• No SSL/TLS

Production Checklist

• Change all default passwords
• Use environment variables for secrets
• Set up SSL/TLS certificates
• Configure proper CORS origins
• Use Docker secrets for sensitive data
• Close unnecessary ports
• Set up firewall rules
• Enable audit logging
• Regular security updates

---

📈 Resource Usage

Expected resource usage:

Service	CPU	Memory	Disk
Frontend	< 5%	~50MB	~100MB
API	~10%	~200MB	~500MB
Documentation	< 1%	~20MB	~50MB
PostgreSQL	~5%	~100MB	~2GB
Redis	< 5%	~50MB	~100MB
MinIO	~5%	~100MB	~5GB
Besu	~20%	~1GB	~10GB
Blockscout	~10%	~500MB	~500MB
Total	~70%	~2GB	~18GB

---

🎯 Next Steps

1. ✅ Start all services
2. ✅ Wait for health checks to pass
3. ✅ Access frontend at http://localhost:4200
4. 📝 Deploy smart contracts (see blockchain/README.md)
5. 🔑 Update .env with contract addresses
6. 🔄 Restart API service
7. 👥 Create initial admin user
8. 🎉 Start using the platform!

---

📞 Support

• Documentation: http://localhost:8080
• API Docs: http://localhost:3001/api
• Architecture: ARCHITECTURE_GUIDE.md
• User Guide: USER_GUIDE.md
• Testing: E2E_TESTING_GUIDE.md

---

Happy Dockering! 🐳

Version: 1.0.0 Last Updated: February 2026