dev cicd + tron + docs

2026-01-30 16:58:02 +01:00
parent 51f5b0804a
commit c1596296d1
52 changed files with 3695 additions and 0 deletions
--- a/ci/dev/README.md
+++ b/ci/dev/README.md
@@ -0,0 +1,124 @@
+# Sendico Development Environment
+
+Docker Compose + Makefile build system for local development.
+
+## Architecture
+
+**Infrastructure:**
+- MongoDB replica set (3 nodes) - credentials in `.env.dev`
+- NATS with JetStream - credentials in `.env.dev`
+- Vault (single node) - for application data ONLY (blockchain keys, external API keys)
+
+**Services:**
+- Discovery, Ledger, Billing Fees, Billing Documents, FX Oracle, Payments Orchestrator
+- Chain Gateway, MNTX Gateway, TGSettle Gateway
+- FX Ingestor, Notification, BFF (Server), Frontend
+
+## Quick Start
+
+```bash
+# 1. Initialize environment (first time)
+make init
+
+# 2. Start all services
+make up
+
+# 3. Initialize Vault (if services need it for application data)
+make vault-init
+
+# 4. View logs
+make logs SERVICE=ledger
+
+# 5. Stop everything
+make down
+```
+
+## Credentials
+
+All in `.env.dev` (plaintext for dev):
+- MongoDB: `dev_root` / `dev_password_123`
+- NATS: `dev_nats` / `nats_password_123`
+- Vault: Run `make vault-init` to get root token
+
+## Common Commands
+
+```bash
+make build                  # Build all images
+make up                     # Start environment
+make down                   # Stop environment
+make logs SERVICE=ledger    # View service logs
+make rebuild SERVICE=ledger # Rebuild specific service
+make proto                  # Regenerate protobuf
+make clean                  # Remove everything
+make status                 # Check service status
+```
+
+## Vault Usage
+
+**Vault is ONLY for application data**, not infrastructure secrets!
+
+Examples:
+- Blockchain private keys (Chain Gateway)
+- External API keys (MNTX, TGSettle)
+- Production-like secrets
+
+Infrastructure (MongoDB, NATS) uses plain `.env.dev` credentials.
+
+## Network
+
+All services on `sendico-dev` network. Vault also on `cicd` network to connect to infra Vault if needed.
+
+## Rebuilding Services
+
+After code changes:
+
+```bash
+# Rebuild specific service
+make rebuild SERVICE=ledger
+
+# Or manually
+docker compose -f docker-compose.dev.yml build ledger
+docker compose -f docker-compose.dev.yml up -d --force-recreate ledger
+```
+
+## Adding New Services
+
+1. Create Dockerfile: `ci/dev/yourservice.dockerfile`
+2. Add service to `docker-compose.dev.yml`
+3. Use environment variables from `.env.dev`
+4. Connect to `sendico-dev` network
+
+## Troubleshooting
+
+**MongoDB replica set not initializing:**
+```bash
+make down
+make up
+# Wait for health checks, then:
+docker logs dev-mongo-init
+```
+
+**Vault sealed:**
+```bash
+make vault-init
+# Save the unseal key and root token from vault-keys.txt
+```
+
+**Service can't connect to MongoDB:**
+- Check replica set: `docker exec -it dev-mongo-1 mongosh -u dev_root -p dev_password_123 --eval "rs.status()"`
+- Ensure `dev-mongo-init` completed: `docker ps -a | grep init`
+
+**Proto generation errors:**
+```bash
+make proto
+# Check output for missing dependencies
+```
+
+## Files
+
+- `docker-compose.dev.yml` - All services
+- `.env.dev` - Plaintext credentials
+- `Makefile` - Build commands
+- `ci/dev/*.dockerfile` - Service builds
+- `ci/dev/mongo.key` - MongoDB replica set key
+- `ci/dev/vault/config.hcl` - Vault config