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

```bash
# 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:

```bash
# 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

```bash
docker-compose up -d
```

### View Logs

```bash
# 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

```bash
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

```bash
docker-compose stop
```

### Restart Services

```bash
docker-compose restart
```

### Stop and Remove Everything

```bash
docker-compose down
```

### Stop and Remove with Volumes (⚠️ Deletes data)

```bash
docker-compose down -v
```

---

## 🔄 Updating Services

### Rebuild After Code Changes

```bash
# 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

```bash
# Pull latest base images
docker-compose pull

# Restart services
docker-compose up -d
```

---

## 🐛 Troubleshooting

### Port Already in Use

Check what's using the port:
```bash
lsof -i :4200  # Frontend
lsof -i :3001  # API
lsof -i :8080  # Documentation
```

Change ports in `docker-compose.yml`:
```yaml
ports:
  - "4201:80"  # Change 4200 to 4201
```

### Service Not Starting

View detailed logs:
```bash
docker-compose logs service-name
```

Check health status:
```bash
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:
```bash
docker-compose logs postgres
```

Manually check connection:
```bash
docker exec -it goa-gel-postgres psql -U postgres -d goa_gel_platform -c "SELECT 1;"
```

### Blockchain Not Mining

Check Besu logs:
```bash
docker-compose logs besu-node-1
```

Verify RPC is accessible:
```bash
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:

```bash
# 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:

```bash
# 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