learning_ai_common_plat/docs/devops/single_azure_vm/README.md

ByteLyst Single-VM Deployment

Deploy the entire ByteLyst ecosystem on a single Azure VM from scratch. Two files: this README and setup.sh. Copy both to the VM and run the script.

---

Prerequisites

• Azure VM: Ubuntu 24.04 LTS (or 22.04), Standard_D8s_v5 (8 vCPU, 32 GB RAM) recommended
• Disk: 100 GB+ (Docker images, Cosmos emulator, build artifacts)
• Network: NSG allowing inbound on ports 80, 3000-3100, 4003-4019, 8025, 8080, 8081
• GitHub access: Repos must be accessible (public or deploy key configured)

Quick Start

# 1. SSH into your Azure VM
ssh azureuser@<vm-ip>

# 2. Copy setup.sh and make executable
chmod +x setup.sh

# 3. Run — provide your GitHub username (repos are cloned via HTTPS)
#    If repos are private, also export GITHUB_TOKEN first.
sudo ./setup.sh

# 4. Wait ~15-25 minutes for full build + deploy

# 5. Verify
docker compose -f /opt/bytelyst/learning_ai_common_plat/docker-compose.ecosystem.yml ps

What the Script Does

Phase	Duration	Description
1. System	~2 min	Install Docker, Node.js 22, pnpm 10.6.5, git
2. Gitea	~1 min	Start Gitea Docker container (npm registry on :3300)
3. Clone	~3 min	Clone all 11 repos to /opt/bytelyst/
4. Build	~5 min	Build all @bytelyst/* packages in common-plat
5. Publish	~3 min	Publish all packages to local Gitea npm registry
6. Env	instant	Generate .env.ecosystem with all required values
7. Deploy	~10 min	docker compose up --build for 27 services
8. Verify	~1 min	Health-check all services

Port Map (after deployment)

Infrastructure

Service	Port	URL
Gitea (npm registry)	3300	http://<vm-ip>:3300
Cosmos Data Explorer	1234	http://<vm-ip>:1234
Azurite (Blob)	10000	—
Mailpit UI	8025	http://<vm-ip>:8025
Grafana	3000	http://<vm-ip>:3000
Traefik Dashboard	8080	http://<vm-ip>:8080

Platform Services

Service	Port	URL
platform-service	4003	http://<vm-ip>:4003/health
extraction-service	4005	http://<vm-ip>:4005/health
mcp-server	4007	http://<vm-ip>:4007/health

Platform Dashboards

Dashboard	Port	URL
Admin Console	3001	http://<vm-ip>:3001
Issue Tracker	3003	http://<vm-ip>:3003

Product Backends

Product	Port	Health
PeakPulse	4010	http://<vm-ip>:4010/health
ChronoMind	4011	http://<vm-ip>:4011/health
JarvisJr	4012	http://<vm-ip>:4012/health
NomGap	4013	http://<vm-ip>:4013/health
MindLyst	4014	http://<vm-ip>:4014/health
LysnrAI	4015	http://<vm-ip>:4015/health
NoteLett	4016	http://<vm-ip>:4016/health
FlowMonk	4017	http://<vm-ip>:4017/health
ActionTrail	4018	http://<vm-ip>:4018/health
LocalMemGPT	4019	http://<vm-ip>:4019/health

Product Web Apps

Product	Port	URL
LysnrAI Dashboard	3002	http://<vm-ip>:3002
ChronoMind	3030	http://<vm-ip>:3030
JarvisJr	3035	http://<vm-ip>:3035
FlowMonk	3040	http://<vm-ip>:3040
NoteLett	3045	http://<vm-ip>:3045
MindLyst	3050	http://<vm-ip>:3050
NomGap	3055	http://<vm-ip>:3055
ActionTrail	3060	http://<vm-ip>:3060
LocalMemGPT	3070	http://<vm-ip>:3070

Post-Deployment Commands

# Check all service health
/opt/bytelyst/check-health.sh

# View logs for a specific service
docker compose -f /opt/bytelyst/learning_ai_common_plat/docker-compose.ecosystem.yml \
  logs -f platform-service

# Restart a specific service
docker compose -f /opt/bytelyst/learning_ai_common_plat/docker-compose.ecosystem.yml \
  restart flowmonk-backend

# Stop everything
docker compose -f /opt/bytelyst/learning_ai_common_plat/docker-compose.ecosystem.yml down

# Stop and wipe all data
docker compose -f /opt/bytelyst/learning_ai_common_plat/docker-compose.ecosystem.yml down -v

Troubleshooting

• Cosmos emulator slow: It needs 20-30s on first boot. Services wait via health checks.
• Out of memory: Use at least 32 GB RAM. The Cosmos emulator alone needs ~4 GB.
• Build failures: Check that Gitea is running (docker ps | grep gitea) and packages published (curl http://localhost:3300/api/packages/bytelyst/npm/).
• Port conflicts: Ensure nothing else runs on the listed ports before deploying.