Orbit (Self-Hosted PaaS)

(Click the diagram to open it in full screen for zooming and panning)

Orbit is an open-source, self-hosted Platform-as-a-Service (PaaS) designed to emulate the developer experience of Vercel. It is built to run efficiently on resource-constrained hardware (like an older laptop) while providing magical, zero-downtime deployments.

Architecture & Tech Stack

• CLI & Daemon: Built with Node.js and TypeScript.
• Containerization: dockerode programmatically builds and manages Docker containers.
• Reverse Proxy: Caddy runs inside a Docker container, providing automatic, zero-downtime routing via a dynamically generated Caddyfile.
• Database: SQLite3 (data.sqlite) is used to locally store project metadata, environments, and deployment history.

Blazing Fast Performance ⚡

With optimized port-binding and caching strategies, Orbit is extremely fast. Once dependencies and base Docker images are cached locally, deployment overhead is minimal. Benchmark: A production Vite React application completes a full zero-downtime deployment in just ~25 seconds!

---

Prerequisites

Before using the CLI, ensure you have the following installed and running on your host machine:

1. Node.js (v18+)
2. Docker Desktop (or Docker Engine). The daemon must be running for deployments to succeed.

---

Installation & Setup

1. Clone the repository (or navigate to the project folder).
2. Install dependencies:

   npm install

3. Build the TypeScript files:

   npm run build

4. Link the CLI globally:

   npm link

   You can now run orbit from anywhere in your terminal.

---

Getting Started: Deploying Your First Project

Follow these exact steps in order to deploy your first project from a GitHub repository:

1. Start the background daemon:

   orbit start-daemon

2. Create an account:

   orbit signup

   (Or orbit login if you already have an account)
3. Connect your GitHub account:

   orbit github connect

4. Import a GitHub repo and link it as a project:

   orbit import

5. Deploy the project:

   orbit deploy

6. Check the status and get your URL:

   orbit list

   (Your app will be available at https://your-project-name.localhost)

---

Available Commands

orbit start-daemon

Spawns the background Express server (the Control Plane) and ensures the Caddy reverse proxy Docker container is running. This must be run once before you start deploying apps.

orbit signup

Creates a persistent local account secured with bcrypt-hashed password. Saves a session token to ~/.orbit-auth.json.

orbit login

Authenticates with your local account and updates the saved session.

orbit logout

Destroys the current session.

orbit whoami

Shows the currently logged-in account email and user ID.

orbit github connect

Links your GitHub account via Personal Access Token (AES-256 encrypted). Requires scopes: repo, admin:repo_hook.

orbit github status

Shows whether a GitHub account is currently linked.

orbit github disconnect

Removes the stored GitHub credentials.

orbit github oauth

Alternative OAuth flow (requires GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in .env).

orbit import

Interactively lists your GitHub repositories and links a selected repo as a project. Auto-registers the GitHub webhook.

orbit link [options]

Registers the current working directory as a project in the database.

• -n, --name <name>: Override the default project name (which defaults to the folder name).
• -r, --repo <repo>: Provide a GitHub repository URL for future webhook integration.

orbit deploy

Manually triggers a build and deployment for the current directory.

1. Zero-Config Framework Auto-Detection: Inspects package.json and optionally minivercel.json to detect Next.js, Vite, Create React App, or generic Node.js apps. If a Dockerfile or .dockerignore is missing, optimized standalone or multi-stage assets are automatically written to the root directory.
2. Packages the directory and builds the Docker image.
3. Finds a random available host port and starts the new container.
4. Dynamically updates the Caddyfile and executes caddy reload for a seamless blue-green deployment.
5. Graceful Cleanup: Gracefully shuts down and removes previous running containers for the project.
6. Proxies the app to http://<project-name>.localhost:8080.

Custom Configuration (minivercel.json)

You can place a minivercel.json file in your project root to override auto-detection defaults:

{
  "buildCommand": "npm run build",
  "installCommand": "npm install",
  "outputDirectory": "dist"
}

orbit env add <key> <value>

Securely store an environment variable for the linked project in the SQLite database.

orbit env rm <key>

Remove a stored environment variable.

orbit env pull

Query the database and write all stored environment variables to a .env file in the current project directory.

orbit logs [project-name]

View the recent stdout/stderr logs from the running project container.

• -f, --follow: Stream live log output continuously to your terminal.

orbit list

Queries the database and prints a formatted table of all active projects, their statuses, and their local URLs.

orbit domain add <domain>

Set a custom domain for the current project.

orbit domain rm

Remove the custom domain from the current project.

orbit rollback

Roll back to the previous deployment.

orbit caddy trust

Install Caddy local CA into the system trust store (run once, local mode only).

orbit caddy mode

Show current Caddy TLS mode and port configuration.

---

Project Roadmap

This project is being built in stages. Stages 1–6 are complete and shipped on main. V2 phases are the next evolution of the platform.

✅ Completed Stages (V1)

• Stage 1: Foundation & Core CLI — SQLite, base CLI commands
• Stage 2: Basic Deployment Engine — Dockerode integration, Caddy proxy container
• Stage 3: Zero-Config Framework Detection — Auto-generating Dockerfiles for Next.js, Vite, Node
• Stage 4: Continuous Delivery — GitHub Webhooks & FIFO Build Queue
• Stage 5: Environment Variables & Logs — Managing secrets
• Stage 6: Advanced PaaS Features — Rollbacks, PR Previews, Custom Domains

---

🚀 V2 Platform Architecture (In Progress)

The V2 roadmap shifts from a folder-centric model to an identity-centric platform. See pipeline-v2.md for full technical specs.

Priority	Phase	Description	Status
Phase 1 — Real Local Identity	Replace random-UUID login with persistent signup/login/logout backed by bcrypt + sessions	✅ Done
Phase 2 — Project Ownership	Projects belong to users; all mutations require ownership validation	✅ Done
Phase 3 — Session Auth Middleware	Daemon-side verifySessionToken middleware protects all destructive routes	✅ Done
Phase 4 — GitHub Account Linking	orbit github connect — PAT-based linking (AES-256 encrypted), repo list, webhook auto-registration, import command	✅ Done
Phase 5 — Real HTTPS	Caddy local CA (tls internal) for localhost + automatic Let's Encrypt for public domains; caddy trust & caddy mode commands	✅ Done
Phase 6 — Local Project Dashboard	Web UI at http://localhost:4000/dashboard with live SSE log streaming, rollback controls, build queue state	🔲 Planned
Phase 7 — Deployment Management Commands	status, stop, restart, rollback, ps — full lifecycle control from the CLI	🔲 Planned
Phase 8 — Container Resource Safety	Hard memory/CPU limits on every container; per-project overrides via minivercel.json; health-check-gated blue-green	🔲 Planned
Phase 9 — Smarter Build System	Docker layer caching, BuildKit, auto .dockerignore, incremental deploys via commit SHA	🔲 Planned
Phase 10 — Dev Mode (File Watch)	orbit dev — chokidar-powered file watcher with debounced auto-redeploy	🔲 Planned
Phase 11 — Better Domain System	Relational domains table, multi-domain per project, domain add/rm/list/verify suite, DNS propagation check	🔲 Planned
Phase 12 — Plugin / Framework Adapter System	Extensible adapter pattern replacing hardcoded framework detection; community adapter support via orbit.adapters.json	🔲 Planned