⬡  ⬡  ⬡
  ⬡  ⬡  ⬡
   ⬡  ⬡  ⬡

🪐 Orbit

A lightweight, beautiful Docker & Compose management UI.
Compose-first. No agents. No complexity. Just your containers.

✨ Vibe coded with Claude — built through conversation, not configuration.

---

What is Orbit?

Orbit is a self-hosted Docker management web app — a modern, opinionated alternative to Portainer. It's designed for people who live in docker compose and want a clean UI without the enterprise overhead.

Key ideas:

• 🧱 Compose-first — stacks are the primary unit, not individual containers
• 📦 Template library — one-click deploy with Portainer-compatible template support
• 🔴 Live updates — WebSocket-driven dashboard, no manual refresh
• 🔒 Simple auth — JWT-based, multi-user with roles
• 🪶 Lightweight — ~10 MB images, no database, no agents

---

Screenshots

Dashboard

Live container grid with status and health overview.

Stacks

Deploy & manage Compose stacks seamlessly.

Templates

One-click application deployments with Portainer template compatibility.

---

Quick Start

# 1. Clone
git clone https://github.com/fatihbtw/orbit.git
cd orbit

# 2. Configure (optional)
cp .env.example .env
# edit .env — set a strong ORBIT_SECRET and ORBIT_ADMIN_PASSWORD

# 3. Launch
docker compose up -d

# 4. Open
open http://localhost:3000
# Login: admin / orbit-change-me  (change this!)

Note: Orbit needs access to the Docker socket (/var/run/docker.sock).
It runs as root inside the container — see Security for hardening options.

---

Configuration

All config via environment variables or .env file:

Variable	Default	Description
ORBIT_ADMIN_PASSWORD	orbit-change-me	Admin password — change this
ORBIT_SECRET	CHANGE_ME_...	JWT signing secret — use 32+ random chars
ORBIT_PORT	3000	Host port for the web UI
LOG_LEVEL	info	Backend log level (debug, info, warn)
STACKS_DIR	/data/stacks	Where stack YAML files are stored

# .env example
ORBIT_ADMIN_PASSWORD=my-super-secret-password
ORBIT_SECRET=change-me-to-a-long-random-string-here
ORBIT_PORT=3000

---

Architecture

Browser
  │
  ▼
┌─────────────────────┐
│  nginx (port 3000)  │  ← only external port
│  serves index.html  │
│  proxies /api/ & /ws│
└────────┬────────────┘
         │ internal Docker network
         ▼
┌─────────────────────┐
│  Node.js backend    │  ← no external port exposed
│  Hono framework     │
│  port 4000 (intern) │
└────────┬────────────┘
         │
         ▼
   Docker socket
   /var/run/docker.sock

Why is the backend port internal-only?
nginx already proxies all /api/ and /ws traffic to the backend over the internal Docker network. There's no reason to expose port 4000 to the host. You can uncomment the ports: section in docker-compose.yml if you need direct backend access for debugging.

Stack storage:
Compose files live in a named Docker volume (orbit-stacks). Settings (users, template URLs) are stored in /data/settings.json on the same volume — no external database needed.

---

Features

🖥 Dashboard

• Live container grid with status, image, ports, compose project
• Health bar (% running)
• Real-time Docker events feed via WebSocket

📦 Stacks

• Create, edit, deploy and remove Compose stacks
• Live deploy log stream (docker compose up output in real-time)
• Stop individual stacks
• View stack logs

📋 Templates

• 10+ built-in templates (Nginx, PostgreSQL, MySQL, Redis, WordPress, Gitea, Nextcloud, Traefik, Grafana, Uptime Kuma, Vaultwarden)
• Portainer-compatible — import any Portainer v1/v2 template JSON URL
• Grid & list view toggle (preference saved in browser)
• Category filters
• Full deploy dialog with tabs:
  • Environment — edit all env vars with labels, defaults, dropdowns for select fields
  • Volumes — edit host paths, container paths, read/write mode
  • Ports — override published ports
  • YAML Editor — full compose YAML editor, auto-synced from other tabs

⚙️ Settings

• Users — create/edit/delete users with roles (admin, operator, viewer)
• Template Sources — add persistent Portainer-compatible template URLs (survive restarts)

📋 Logs

• Per-container log viewer (last 300 lines)

---

Portainer Template Compatibility

Orbit supports both Portainer template formats:

• v1 — plain JSON array of template objects
• v2 — { "version": "2", "templates": [...] }

Known working sources:

https://raw.githubusercontent.com/portainer/portainer-templates/master/templates-2.0.json
https://raw.githubusercontent.com/pi-hosted/pi-hosted/master/template/portainer-v2.json
https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json

Add them in Settings → Template Sources.

---

Roles

Role	Can do
admin	Everything — users, settings, deploy, delete
operator	Deploy stacks, start/stop containers, view all
viewer	Read-only — view containers, logs, stacks

---

Running on a Raspberry Pi

Pi 4 / Pi 5 — ✅ Fully supported

arm64 images for node:20-alpine and nginx:alpine are available on Docker Hub. Orbit runs well.

# Same as normal, just run it
docker compose up -d

Pi 3B+ — ⚠️ Works with caveats

• 1 GB RAM is tight but functional
• First build takes longer (arm compilation)
• Limit the backend memory if needed:

  # in docker-compose.yml under backend:
  deploy:
    resources:
      limits:
        memory: 256m

Pi Zero 2 W — ⚠️ Technically possible, not recommended

Spec	Pi Zero 2 W	Orbit requirement
CPU	1 GHz quad-core ARM Cortex-A53	Light — Hono is fast
RAM	512 MB	~100–150 MB at idle — tight
Arch	arm64 / armv7	✅ supported by base images
Storage	microSD	✅ (wear is a concern long-term)

The main constraint is RAM. The Node.js backend + nginx will use ~100–150 MB at idle. With Docker itself and the OS, you're close to the 512 MB ceiling, especially when deploying stacks. There's no swap by default on Raspberry Pi OS Lite.

If you want to try it:

# Enable swap first
sudo dphys-swapfile swapconf  # edit /etc/dphys-swapfile, set CONF_SWAPSIZE=512
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# Add memory limits to docker-compose.yml
# backend: deploy.resources.limits.memory: 200m
# frontend: deploy.resources.limits.memory: 64m

docker compose up -d

Bottom line: For a Pi Zero 2 W, Orbit will start but may struggle when actively deploying stacks or pulling images. A Pi 3B+ or Pi 4 is a much more comfortable experience.

---

Security

Current state (Phase 0): Orbit runs as root inside its container to access the Docker socket. This is the same approach used by Portainer and Dockge in their default configurations.

What this means: Anyone with access to the Orbit UI effectively has root on the host via Docker. Use Orbit only on trusted networks, behind a VPN, or behind an authenticated reverse proxy.

Planned hardening (Phase 1):

• docker-socket-proxy for fine-grained API restriction
• Switch to docker group GID mapping (non-root)
• HTTPS via Caddy/Traefik integration
• Token blocklist (Redis)
• LDAP / OIDC integration
• Audit log persistence

---

Development

# Backend (hot reload)
cd backend
npm install
node --watch src/index.js

# Frontend — just edit index.html, nginx serves it statically
# Rebuild containers after changes:
docker compose build --no-cache
docker compose up -d

---

About

Orbit was vibe coded — the entire codebase was built through conversation with Claude (Anthropic), iterating from a rough idea to a working app without writing a single line manually. The design, architecture, bug fixes, and feature additions were all done by describing what was needed and refining the result.

This is what "vibe coding" looks like in practice: fast, iterative, surprisingly capable — and a lot of fun.

---

License

MIT © 2025 — do whatever you want with it.

---

Made with 🪐 and vibes  ·  Built with Claude