feat: Goa GEL Blockchain e-Licensing Platform - Full Stack Implementation
Complete implementation of the Goa Government e-Licensing platform with: Backend: - NestJS API with JWT authentication - PostgreSQL database with Knex ORM - Redis caching and session management - MinIO document storage - Hyperledger Besu blockchain integration - Multi-department workflow system - Comprehensive API tests (266/282 passing) Frontend: - Angular 21 with standalone components - Angular Material + TailwindCSS UI - Visual workflow builder - Document upload with progress tracking - Blockchain explorer integration - Role-based dashboards (Admin, Department, Citizen) - E2E tests with Playwright (37 tests) Infrastructure: - Docker Compose orchestration - Blockscout blockchain explorer - Development and production configurations
This commit is contained in:
Mahi
374
docs/development/DOCKER_SETUP.md
Normal file
374
docs/development/DOCKER_SETUP.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# 🐳 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
|
||||
Reference in New Issue
Block a user