dev cicd + tron + docs
This commit is contained in:
Stephan D
399
SETUP.md
Normal file
399
SETUP.md
Normal file
@@ -0,0 +1,399 @@
|
||||
# Sendico Development Environment - Setup Guide
|
||||
|
||||
Complete Docker Compose + Makefile build system for local development.
|
||||
|
||||
## 🎯 What's Included
|
||||
|
||||
**13 Services:**
|
||||
- ✅ Discovery (Service Registry)
|
||||
- ✅ FX Oracle & FX Ingestor
|
||||
- ✅ Billing Fees
|
||||
- ✅ Ledger (Double-Entry Accounting)
|
||||
- ✅ Payments Orchestrator
|
||||
- ✅ Chain Gateway (Blockchain)
|
||||
- ✅ MNTX Gateway (Card Payouts)
|
||||
- ✅ TGSettle Gateway (Telegram Settlements)
|
||||
- ✅ Notification
|
||||
- ✅ BFF (Backend for Frontend / Server)
|
||||
- ✅ Frontend (Flutter Web)
|
||||
|
||||
**Infrastructure:**
|
||||
- MongoDB Replica Set (3 nodes)
|
||||
- NATS with JetStream
|
||||
- Vault (single node, for application data only)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# 1. First time setup
|
||||
make init
|
||||
|
||||
# 2. Start everything
|
||||
make up
|
||||
|
||||
# 3. Initialize Vault (if services need blockchain keys, external API keys)
|
||||
make vault-init
|
||||
|
||||
# 4. Check status
|
||||
make status
|
||||
|
||||
# 5. View frontend
|
||||
open http://localhost:3000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
- Docker & Docker Compose
|
||||
- Make
|
||||
- Go 1.24+ (for local proto generation)
|
||||
- protoc, protoc-gen-go, protoc-gen-go-grpc (for proto generation)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Edit `.env.dev` (created after `make init`):
|
||||
|
||||
```bash
|
||||
# MongoDB
|
||||
MONGO_USER=dev_root
|
||||
MONGO_PASSWORD=dev_password_123
|
||||
|
||||
# NATS
|
||||
NATS_USER=dev_nats
|
||||
NATS_PASSWORD=nats_password_123
|
||||
|
||||
# Vault (for application data only)
|
||||
VAULT_ADDR=http://dev-vault:8200
|
||||
```
|
||||
|
||||
**IMPORTANT:** These are plaintext credentials for dev infrastructure only!
|
||||
|
||||
---
|
||||
|
||||
## 📊 Service Ports
|
||||
|
||||
**Infrastructure:**
|
||||
- MongoDB: `localhost:27017`
|
||||
- NATS: `localhost:4222`
|
||||
- NATS Monitoring: `localhost:8222`
|
||||
- Vault: `localhost:8200`
|
||||
|
||||
**Services:**
|
||||
- Discovery: `localhost:9407`
|
||||
- FX Oracle: `localhost:50051` (gRPC), `localhost:9400` (metrics)
|
||||
- FX Ingestor: `localhost:9102`
|
||||
- Billing Fees: `localhost:50060` (gRPC), `localhost:9402` (metrics)
|
||||
- Ledger: `localhost:50052` (gRPC), `localhost:9401` (metrics)
|
||||
- Payments Orchestrator: `localhost:50062` (gRPC), `localhost:9403` (metrics)
|
||||
- Chain Gateway: `localhost:50070` (gRPC), `localhost:9404` (metrics)
|
||||
- MNTX Gateway: `localhost:50075` (gRPC), `localhost:9405` (metrics), `localhost:8084` (HTTP)
|
||||
- TGSettle Gateway: `localhost:50080` (gRPC), `localhost:9406` (metrics)
|
||||
- Notification: `localhost:8081`
|
||||
- BFF: `localhost:8080`
|
||||
- Frontend: `localhost:3000`
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Common Commands
|
||||
|
||||
### Lifecycle
|
||||
|
||||
```bash
|
||||
make up # Start all services
|
||||
make down # Stop all services
|
||||
make restart # Restart all services
|
||||
make status # Check status
|
||||
make clean # Remove everything (containers + volumes)
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
make logs # All services
|
||||
make logs SERVICE=dev-ledger # Specific service
|
||||
|
||||
# Rebuild after code changes
|
||||
make rebuild SERVICE=dev-ledger
|
||||
|
||||
# Regenerate protobuf
|
||||
make proto
|
||||
```
|
||||
|
||||
### Selective Startup
|
||||
|
||||
```bash
|
||||
# Start infrastructure only
|
||||
make infra-up
|
||||
|
||||
# Then start services
|
||||
make services-up
|
||||
|
||||
# Or start specific service groups
|
||||
make build-core # discovery, ledger, billing-fees
|
||||
make build-fx # fx-oracle, fx-ingestor
|
||||
make build-payments # payments-orchestrator
|
||||
make build-gateways # chain, mntx, tgsettle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Vault Setup
|
||||
|
||||
Vault is **only for application data** (blockchain keys, external API keys).
|
||||
Infrastructure credentials (MongoDB, NATS) are in `.env.dev`.
|
||||
|
||||
### Initialize Vault
|
||||
|
||||
```bash
|
||||
make vault-init
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Initialize Vault with 1 key share
|
||||
2. Unseal Vault automatically
|
||||
3. Save keys to `vault-keys.txt` (NEVER commit this!)
|
||||
4. Display root token
|
||||
|
||||
### Using Vault in Services
|
||||
|
||||
Services that need Vault (e.g., Chain Gateway for blockchain keys):
|
||||
1. Set `VAULT_ADDR` in service environment
|
||||
2. Use Vault client to fetch secrets at runtime
|
||||
3. Store secrets in Vault: `kv/data/chain/ethereum/private_key`
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Development Workflow
|
||||
|
||||
### Typical Day
|
||||
|
||||
```bash
|
||||
# Morning: Start environment
|
||||
make up
|
||||
|
||||
# Work on ledger service
|
||||
vim api/ledger/internal/service/ledger/posting.go
|
||||
|
||||
# Rebuild ledger
|
||||
make rebuild SERVICE=dev-ledger
|
||||
|
||||
# View logs
|
||||
make logs SERVICE=dev-ledger
|
||||
|
||||
# Test
|
||||
curl http://localhost:9401/health
|
||||
|
||||
# End of day
|
||||
make down
|
||||
```
|
||||
|
||||
### After Changing Protos
|
||||
|
||||
```bash
|
||||
# Regenerate protos
|
||||
make proto
|
||||
|
||||
# Rebuild affected services
|
||||
make rebuild SERVICE=dev-ledger
|
||||
make rebuild SERVICE=dev-payments-orchestrator
|
||||
```
|
||||
|
||||
### Frontend Development
|
||||
|
||||
For faster iteration, run frontend locally instead of Docker:
|
||||
|
||||
```bash
|
||||
# Start backend services only
|
||||
make infra-up
|
||||
make services-up
|
||||
|
||||
# Run frontend locally
|
||||
cd frontend/pweb
|
||||
flutter run -d chrome
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Debugging
|
||||
|
||||
### MongoDB Replica Set Issues
|
||||
|
||||
```bash
|
||||
# Check replica set status
|
||||
docker exec -it dev-mongo-1 mongosh -u dev_root -p dev_password_123 --eval "rs.status()"
|
||||
|
||||
# Reinitialize
|
||||
make down
|
||||
make up
|
||||
docker logs dev-mongo-init
|
||||
```
|
||||
|
||||
### Service Can't Connect to MongoDB
|
||||
|
||||
```bash
|
||||
# Check if replica set is initialized
|
||||
docker logs dev-mongo-init
|
||||
|
||||
# Check MongoDB is healthy
|
||||
docker ps | grep mongo
|
||||
```
|
||||
|
||||
### Vault Sealed
|
||||
|
||||
```bash
|
||||
# Get unseal key from vault-keys.txt
|
||||
UNSEAL_KEY=$(grep 'Unseal Key 1:' vault-keys.txt | awk '{print $NF}')
|
||||
|
||||
# Unseal
|
||||
docker exec dev-vault vault operator unseal $UNSEAL_KEY
|
||||
```
|
||||
|
||||
### Service Crash Loop
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
make logs SERVICE=dev-ledger
|
||||
|
||||
# Check environment variables
|
||||
docker inspect dev-ledger | grep -A 20 Env
|
||||
|
||||
# Rebuild from scratch
|
||||
make rebuild SERVICE=dev-ledger
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Docker Images
|
||||
|
||||
All images tagged as `sendico-dev/<service>:latest`:
|
||||
- `sendico-dev/discovery:latest`
|
||||
- `sendico-dev/ledger:latest`
|
||||
- `sendico-dev/billing-fees:latest`
|
||||
- `sendico-dev/fx-oracle:latest`
|
||||
- `sendico-dev/fx-ingestor:latest`
|
||||
- `sendico-dev/payments-orchestrator:latest`
|
||||
- `sendico-dev/chain-gateway:latest`
|
||||
- `sendico-dev/mntx-gateway:latest`
|
||||
- `sendico-dev/tgsettle-gateway:latest`
|
||||
- `sendico-dev/notification:latest`
|
||||
- `sendico-dev/bff:latest`
|
||||
- `sendico-dev/frontend:latest`
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Full Flow
|
||||
|
||||
```bash
|
||||
# 1. Start everything
|
||||
make up
|
||||
|
||||
# 2. Check all services are healthy
|
||||
make status
|
||||
|
||||
# 3. Test discovery
|
||||
curl http://localhost:9407/health
|
||||
|
||||
# 4. Test ledger
|
||||
curl http://localhost:9401/health
|
||||
|
||||
# 5. Test BFF
|
||||
curl http://localhost:8080/api/v1/health
|
||||
|
||||
# 6. Test frontend
|
||||
open http://localhost:3000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗑️ Cleanup
|
||||
|
||||
```bash
|
||||
# Stop everything
|
||||
make down
|
||||
|
||||
# Remove volumes (fresh start)
|
||||
make clean
|
||||
|
||||
# Remove images
|
||||
docker rmi $(docker images 'sendico-dev/*' -q)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 File Structure
|
||||
|
||||
```
|
||||
sendico/
|
||||
├── docker-compose.dev.yml # All service definitions
|
||||
├── .env.dev # Plaintext credentials
|
||||
├── Makefile # Build commands
|
||||
├── SETUP.md # This file
|
||||
├── vault-keys.txt # Vault keys (gitignored)
|
||||
└── docker/
|
||||
└── dev/
|
||||
├── README.md # Detailed docs
|
||||
├── mongo.key # MongoDB keyfile
|
||||
├── vault/
|
||||
│ └── config.hcl # Vault config
|
||||
└── *.dockerfile # Service builds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
```bash
|
||||
# Show all available commands
|
||||
make help
|
||||
|
||||
# List all services
|
||||
make list-services
|
||||
|
||||
# Check service health
|
||||
make health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Next Steps
|
||||
|
||||
1. **Initialize Vault with secrets** for Chain Gateway
|
||||
2. **Seed test data** into MongoDB
|
||||
3. **Run integration tests**
|
||||
4. **Add monitoring** (Prometheus/Grafana - optional)
|
||||
5. **Document API endpoints** in each service
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
- **Never commit `.env.dev`** - Contains credentials
|
||||
- **Never commit `vault-keys.txt`** - Contains Vault keys
|
||||
- **Vault is for app data only** - Not for infrastructure secrets
|
||||
- **Use `dev-` prefix** for all service names to avoid conflicts
|
||||
- **MongoDB keyfile** must have `400` permissions
|
||||
|
||||
---
|
||||
|
||||
## 📝 Troubleshooting Checklist
|
||||
|
||||
- [ ] Docker is running
|
||||
- [ ] Docker Compose v2 is installed (`docker compose version`)
|
||||
- [ ] `.env.dev` exists and has correct values
|
||||
- [ ] Vault is initialized and unsealed (`make vault-init`)
|
||||
- [ ] MongoDB replica set is initialized (`docker logs dev-mongo-init`)
|
||||
- [ ] All services are healthy (`make status`)
|
||||
- [ ] No port conflicts on host machine
|
||||
- [ ] Proto generation succeeded (`make proto`)
|
||||
|
||||
---
|
||||
|
||||
**Ready to build? Run `make init && make up`** 🚀
|
||||
Reference in New Issue
Block a user