Orchestra

Orchestra is an internal PaaS for managing physical servers. It eliminates "snowflake servers" by automating provisioning, cluster orchestration, and application deployment on bare metal.

Features

• Multi-Runtime Clusters — Kubernetes (K3s), Docker Swarm, or plain Docker
• Server Inventory — Auto-discovery and pre-flight checks (CPU, RAM, OS, Cgroups) via SSH
• Cluster Designer — Visual UI to designate manager/worker nodes and form clusters
• Application Deployment — Deploy from Git repos, Docker images, or manual paths
• Environment Management — Scoped env vars (production/staging/preview) pushed to servers
• Nginx Provisioning — Automatic reverse proxy + Let's Encrypt SSL setup
• Zero-Agent Architecture — Uses crypto/ssh; no permanent agent on nodes

Architecture

Orchestra/
├── core/           # Go — API server, background worker, provisioning engine
├── ui/             # Next.js — Dashboard, cluster designer, deploy wizard
└── docker-compose.yml

graph TD
    Client[Browser] -->|HTTP| UI[UI · Next.js]
    UI -->|REST API| Server[Core · API Server]
    Server -->|Persist| DB[(PostgreSQL)]
    Server -->|Queue| Redis[(Redis)]
    Worker[Core · Worker] -->|Consume| Redis
    Worker -->|SSH| Node1[Server 1]
    Worker -->|SSH| Node2[Server 2]
    Worker -->|K8s / Swarm| Cluster[Cluster]

Loading

Quick Start

Prerequisites

• Docker & Docker Compose v2
• make (optional)

Run

git clone https://github.com/enochcodes/orchestra.git
cd orchestra

# Start the full stack (PostgreSQL, Redis, Core, Worker, UI)
make up
# OR
docker compose up -d

Access the dashboard: http://localhost:3000

Service	URL / Address
UI	http://localhost:3000
API	http://localhost:8080
PostgreSQL	localhost:5432
Redis	localhost:6379

Default login (seeded on first run):

• Email: admin@orchestra.local
• Password: admin123

Stop:

make down        # Stop containers
make clean       # Stop + remove volumes

Production

Create a .env file:

ENCRYPTION_KEY=<64-hex-chars>   # openssl rand -hex 32
JWT_SECRET=<your-secret>
SKIP_AUTH=false

Development

Core (Go)

make dev-deps                    # Start DB + Redis only
cd core
cp .env.example .env             # Set ENCRYPTION_KEY
go run cmd/server/main.go        # API server
go run cmd/worker/main.go        # Background worker

UI (Next.js)

cd ui
cp .env.example .env
npm install
npm run dev

E2E Testing (Playwright)

# Start full stack first
docker compose up -d

cd ui
npx playwright install
npm run test:e2e

See ui/e2e/README.md and QA_TESTING.md for full QA and UAT guides.

Testing with Local Test Servers

Test Orchestra end-to-end without real hardware using Docker-based SSH containers:

# 1. Generate SSH keys (creates keys/id_rsa and keys/id_rsa.pub)
make generate-keys

# 2. Start Orchestra + 3 test server containers
make up-test-servers

# 3. Open http://localhost:3000, register servers with:
#    IP: test-server-1, test-server-2, test-server-3 | Port: 22 | User: orchestra | Key: paste keys/id_rsa
# 4. Design clusters and deploy apps

See TESTING_WITH_SERVERS.md for the full guide (key setup, registration steps, troubleshooting).

Testing for v1 Release

Orchestra v1 is ready for real-server testing. Use QA_TESTING.md for:

• Manual QA checklist (server registration, cluster design, app deployment)
• End-to-end UAT flow
• Troubleshooting guide

Contributing

author @enochCodes | henoksamson57@gmail.com

See CONTRIBUTING.md.

License

MIT — see LICENSE.