tech/sendico
2
0
Fork 0
Code Issues 31 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
e6232f9b1daced0c8eba4cbdb65ec603ffd2c129
sendico/SETUP.md
Stephan D c1596296d1 dev cicd + tron + docs
2026-01-30 16:58:02 +01:00

8.0 KiB
Raw Blame History

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

# 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):

# 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

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

# 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

# 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

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

# 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

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

# 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

# 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

# Check if replica set is initialized
docker logs dev-mongo-init

# Check MongoDB is healthy
docker ps | grep mongo

Vault Sealed

# 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

# 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

# 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

# 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

# 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 View Git Blame Copy Permalink