cleargrow/devplatform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
devplatform/ARCHITECTURE.md
CI System 368ac8ab1f docs: update ARCHITECTURE.md and fix paths 
- Add ARCHITECTURE.md with full 4-VPS infrastructure details
- Update vps-agents specs: 16GB RAM, 8 dedicated vCPUs
- Fix vps-ci specs in diagrams (8GB not 4GB)
- Update monthly cost to $228
- Fix /root/cleargrow paths to /opt/repos in CLAUDE.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-10 15:55:40 -07:00

17 KiB
Raw Permalink Blame History

ClearGrow DevPlatform Architecture

Overview

Distributed 4-VPS architecture on Linode for the ClearGrow IoT development platform.

Monthly Cost: $228

Migration Status

VPS Status Public IP Deployed
vps-git ACTIVE 139.144.29.179 2025-12-10
vps-track ACTIVE 170.187.143.45 2025-12-10
vps-ci ACTIVE 173.230.138.66 2025-12-10
vps-agents ACTIVE 45.79.204.236 2025-12-10

Migration Complete - All services distributed across 4 VPS.

Infrastructure Diagram

                              INTERNET
                                  │
                    ┌─────────────┴─────────────┐
                    │      Cloudflare DNS       │
                    │                           │
                    │   git.cleargrow.io ───────┼──► vps-git
                    │   track.cleargrow.io ─────┼──► vps-track
                    │   ci.cleargrow.io ────────┼──► vps-ci
                    │   agents.cleargrow.io ────┼──► vps-agents (internal)
                    └───────────────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        │            LINODE PRIVATE VLAN (10.0.0.0/24)      │
        │                         │                         │
   ┌────┴────┐  ┌────────┐  ┌─────┴─────┐  ┌──────────────┐│
   │         │  │        │  │           │  │              ││
   │ vps-git │  │vps-    │  │  vps-ci   │  │ vps-agents   ││
   │         │  │track   │  │           │  │              ││
   │10.0.0.10│  │10.0.0.20  │ 10.0.0.30 │  │  10.0.0.40   ││
   └─────────┘  └────────┘  └───────────┘  └──────────────┘│
        │                                                   │
        └───────────────────────────────────────────────────┘

VPS Specifications

vps-git (Shared 2GB) - $12/mo - ACTIVE

Resource Value
Plan Linode 2GB Shared
RAM 2 GB
CPU 1 vCPU (shared)
Storage 50 GB SSD
Transfer 2 TB
Public IP 139.144.29.179
Private IP 10.0.0.10 (pending VLAN setup)
Public DNS git.cleargrow.io

Services:

  • Nginx (reverse proxy + SSL termination)
  • PostgreSQL 15 (databases for Gitea)
  • Gitea (Git hosting)

Management:

# SSH access
ssh -i ~/.ssh/cleargrow_ed25519 root@139.144.29.179

# Service control
systemctl status vps-git
systemctl restart vps-git

# Docker management
docker compose -f /opt/devplatform/docker-compose.yml ps
docker compose -f /opt/devplatform/docker-compose.yml logs -f

vps-track (Shared 4GB) - $24/mo - ACTIVE

Resource Value
Plan Linode 4GB Shared
RAM 4 GB
CPU 2 vCPU (shared)
Storage 80 GB SSD
Transfer 4 TB
Public IP 170.187.143.45
Private IP 10.0.0.20 (pending VLAN setup)
Public DNS track.cleargrow.io

Services:

  • Nginx (reverse proxy + SSL termination)
  • YouTrack (issue tracking, embedded database)

JVM Configuration:

  • Heap: 2.5GB (-Xmx2560m)

Management:

# SSH access
ssh -i ~/.ssh/cleargrow_ed25519 root@170.187.143.45

# Service control
systemctl status vps-track
systemctl restart vps-track

# Docker management
docker compose -f /opt/devplatform/docker-compose.yml ps
docker compose -f /opt/devplatform/docker-compose.yml logs -f

vps-ci (Shared 8GB) - $48/mo - ACTIVE

Resource Value
Plan Linode 8GB Shared
RAM 8 GB
CPU 4 vCPU (shared)
Storage 160 GB SSD
Transfer 5 TB
Public IP 173.230.138.66
Private IP 10.0.0.30 (pending VLAN setup)
Public DNS ci.cleargrow.io

Services:

  • Nginx (reverse proxy + SSL termination)
  • TeamCity Server (internal HSQLDB)
  • TeamCity Build Agent
  • Docker Registry (pull-through cache)

JVM Configuration:

  • TeamCity Server Heap: 3GB (-Xmx3g)

Management:

# SSH access
ssh -i ~/.ssh/cleargrow_ed25519 root@173.230.138.66

# Service control
systemctl status vps-ci
systemctl restart vps-ci

# Docker management
docker compose -f /opt/devplatform/docker-compose.yml ps
docker compose -f /opt/devplatform/docker-compose.yml logs -f

vps-agents (Dedicated 8 vCPU) - $144/mo - ACTIVE

Resource Value
Plan Linode Dedicated 16GB
RAM 16 GB
CPU 8 vCPU (dedicated AMD EPYC)
Storage 320 GB SSD
Transfer 6 TB
Public IP 45.79.204.236
Private IP 10.0.0.40 (pending VLAN setup)
Public DNS agents.cleargrow.io (internal only)

Services:

  • Agent Runner (Python daemon)
  • Claude Code (10 concurrent instances max)
  • Git repositories (working copies at /opt/repos/)
  • ESP-IDF toolchain (~2GB)
  • Zephyr SDK + nRF Connect SDK (~25GB)

Resource Allocation:

Component RAM CPU
OS + overhead 512MB -
Agent Runner 256MB 0.5
Claude Code (10x) 10GB 6
Toolchains 1GB -
Buffer 4GB 1.5

Management:

# This is the local server - no SSH needed

# Agent runner control
sudo systemctl status cleargrow-agent-runner
sudo systemctl restart cleargrow-agent-runner
sudo journalctl -u cleargrow-agent-runner -f

# Repository locations
ls /opt/repos/  # controller, probe, docs

Network Architecture

Public Ports

VPS Port Service Access
vps-git 443 HTTPS (Gitea) Public
vps-git 2222 SSH (Git) Public
vps-track 443 HTTPS (YouTrack) Public
vps-ci 443 HTTPS (TeamCity) Public

Private Network (VLAN)

All inter-service communication uses Linode Private VLAN (free, no transfer costs).

Source Destination Port Purpose
vps-agents vps-git 5432 PostgreSQL (if needed)
vps-agents vps-git 2222 Git SSH (clone/push)
vps-agents vps-track 8080 YouTrack API
vps-agents vps-ci 8111 TeamCity API
vps-ci vps-git 2222 Git SSH (clone for builds)
vps-track vps-agents 8765 Webhook (issue events)

Firewall Rules

vps-git

# Public
ALLOW TCP 443 from 0.0.0.0/0      # HTTPS
ALLOW TCP 2222 from 0.0.0.0/0     # Git SSH

# Private VLAN
ALLOW TCP 5432 from 10.0.0.0/24   # PostgreSQL
ALLOW ALL from 10.0.0.0/24        # Internal

# Default
DENY ALL

vps-track

# Public
ALLOW TCP 443 from 0.0.0.0/0      # HTTPS

# Private VLAN
ALLOW ALL from 10.0.0.0/24        # Internal

# Default
DENY ALL

vps-ci

# Public
ALLOW TCP 443 from 0.0.0.0/0      # HTTPS

# Private VLAN
ALLOW ALL from 10.0.0.0/24        # Internal

# Default
DENY ALL

vps-agents

# Public
ALLOW TCP 22 from <admin-ips>     # SSH (restricted)

# Private VLAN
ALLOW ALL from 10.0.0.0/24        # Internal

# Outbound
ALLOW TCP 443 to api.anthropic.com  # Claude API

# Default
DENY ALL inbound from public

Service Distribution

┌─────────────────────────────────────────────────────────────────────────────┐
│                              vps-git (2GB)                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────────┐  ┌─────────────────────────────────┐  │
│  │   Nginx     │  │   PostgreSQL    │  │            Gitea                │  │
│  │   :443      │  │     :5432       │  │           :3000                 │  │
│  │   :80       │  │                 │  │           :22                   │  │
│  └─────────────┘  └─────────────────┘  └─────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                             vps-track (4GB)                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────────────────────────────────────────────┐   │
│  │   Nginx     │  │                    YouTrack                         │   │
│  │   :443      │  │                     :8080                           │   │
│  │   :80       │  │               (embedded database)                   │   │
│  └─────────────┘  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              vps-ci (8GB)                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌───────────────────┐  ┌────────────┐  ┌──────────────┐  │
│  │   Nginx     │  │  TeamCity Server  │  │  TC Agent  │  │   Registry   │  │
│  │   :443      │  │      :8111        │  │            │  │    :5000     │  │
│  │   :80       │  │                   │  │            │  │              │  │
│  └─────────────┘  └───────────────────┘  └────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                           vps-agents (16GB)                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────────────────────────────────────┐   │
│  │  Agent Runner   │  │              Claude Code Pool                   │   │
│  │     :8765       │  │           (10 concurrent max)                   │   │
│  │   (webhook)     │  │                                                 │   │
│  └─────────────────┘  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                         Toolchains                                   │    │
│  │   /opt/esp-idf  /opt/ncs  /opt/zephyr-sdk  /opt/repos               │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘

Data Flow

Issue Processing Flow

1. Developer creates issue in YouTrack (vps-track)
2. Issue moved to "Ready" state
3. YouTrack webhook → Agent Runner (vps-agents:8765)
4. Agent Runner spawns Claude Code instance
5. Claude Code:
   - Clones repo from Gitea (vps-git:2222)
   - Analyzes code, implements fix
   - Commits and pushes to Gitea
6. Gitea webhook → TeamCity (vps-ci)
7. TeamCity runs CI pipeline
8. Agent Runner updates YouTrack issue status

Interactive Development Flow

1. Developer SSH → vps-agents
2. cd /opt/repos/controller
3. claude (interactive session)
4. Claude Code reads/writes code
5. Developer reviews and commits
6. git push → Gitea (vps-git)

Backup Strategy

VPS Data Method Frequency Retention
vps-git PostgreSQL pg_dump → S3 Daily 30 days
vps-git Gitea repos Already in Git N/A N/A
vps-track YouTrack Built-in backup → S3 Daily 30 days
vps-ci TeamCity config Built-in backup → S3 Weekly 4 weeks
vps-agents Repos Working copies (disposable) N/A N/A

Linode Backup Service: Optional $2-5/mo per VPS for full image snapshots.

Scaling Considerations

Vertical Scaling

VPS Current Next Tier Trigger
vps-git 2GB 4GB >1000 repos or slow clones
vps-track 4GB 8GB >50 concurrent users
vps-ci 8GB 16GB Build queue backing up
vps-agents 16GB 32GB Need >10 concurrent agents

Horizontal Scaling

  • vps-agents: Can add vps-agents-2 with queue-based work distribution (requires Redis)
  • vps-ci: Can add additional TeamCity agents on separate VPS

Cost Summary

Component Monthly
vps-git (Shared 2GB) $12
vps-track (Shared 4GB) $24
vps-ci (Shared 8GB) $48
vps-agents (Dedicated 16GB) $144
Subtotal (Compute) $228
Linode Backups (optional) ~$10
Object Storage for backups ~$5
Total (with backups) ~$243

Domain Configuration

DNS Records (Cloudflare)

git.cleargrow.io      A     139.144.29.179           (DNS only, Let's Encrypt)
track.cleargrow.io    A     170.187.143.45           (DNS only, Let's Encrypt)
ci.cleargrow.io       A     173.230.138.66           (DNS only, Let's Encrypt)
agents.cleargrow.io   A     45.79.204.236            (internal use only)

SSL Certificates

  • vps-git: Let's Encrypt (certbot, auto-renew enabled, expires 2026-03-10)
  • vps-track: Let's Encrypt (certbot, auto-renew enabled, expires 2026-03-10)
  • vps-ci: Let's Encrypt (certbot, auto-renew enabled, expires 2026-03-10)
  • vps-agents: No SSL needed (internal services only)

SSH Keys

The cleargrow_ed25519 key is used for inter-server communication:

# Public key (add to new servers)
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBRfOE6jOtIE07fSbs8eb5Rd5S/jwmcQEU3ryvvrx9/G cleargrow-controller

# Key location on vps-agents
~/.ssh/cleargrow_ed25519
Reference in New Issue View Git Blame Copy Permalink