{"id":44495919,"url":"https://github.com/xraph/ctrlplane","last_synced_at":"2026-04-02T18:05:17.888Z","repository":{"id":338090194,"uuid":"1156493294","full_name":"xraph/ctrlplane","owner":"xraph","description":"Ctrl Plane is a composable Go library that gives you instance lifecycle management, zero-downtime deployments, health monitoring, and multi-tenant isolation — backed by any cloud provider.","archived":false,"fork":false,"pushed_at":"2026-02-16T19:54:55.000Z","size":426,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-17T02:20:35.043Z","etag":null,"topics":["deployment","forge","saas"],"latest_commit_sha":null,"homepage":"https://ctrl.xraph.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xraph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T17:58:19.000Z","updated_at":"2026-02-16T19:46:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xraph/ctrlplane","commit_stats":null,"previous_names":["xraph/ctrlplane"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/xraph/ctrlplane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fctrlplane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fctrlplane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fctrlplane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fctrlplane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xraph","download_url":"https://codeload.github.com/xraph/ctrlplane/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fctrlplane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29679049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T09:33:50.764Z","status":"ssl_error","status_checked_at":"2026-02-21T09:33:19.949Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deployment","forge","saas"],"created_at":"2026-02-13T05:08:36.305Z","updated_at":"2026-02-21T10:04:27.223Z","avatar_url":"https://github.com/xraph.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ctrl Plane\n\nA composable Go library for deploying and managing SaaS instances at scale.\n\nCtrl Plane handles instance lifecycle, zero-downtime deployments, health monitoring, secret management, traffic routing, and multi-tenant isolation. You bring a cloud provider and an auth system. Ctrl Plane wires everything together.\n\n## Overview\n\nCtrl Plane is a library, not a framework. You import Go packages, configure them with functional options, and embed them into your own application. It runs standalone or as a [Forge](https://github.com/xraph/forge) extension.\n\n```go\ncp, err := app.New(\n    app.WithStore(postgresStore),\n    app.WithProvider(\"k8s\", kubernetesProvider),\n    app.WithAuth(myAuthProvider),\n)\n\ncp.Start(ctx)\nhttp.ListenAndServe(\":8080\", api.New(cp).Handler())\n```\n\n**What it does:**\n\n- Provisions and manages tenant instances across any cloud provider (Docker, Kubernetes, AWS ECS, Fly.io, etc.)\n- Deploys with rolling, blue-green, canary, or recreate strategies\n- Runs HTTP, TCP, gRPC, and command-based health checks\n- Manages custom domains, TLS certificates, and traffic routing\n- Stores secrets with pluggable vault backends\n- Publishes lifecycle events and delivers webhooks\n- Collects metrics, logs, traces, and resource snapshots\n- Enforces tenant quotas and records audit trails\n\n## Install\n\n```bash\ngo get github.com/xraph/ctrlplane@latest\n```\n\nRequires Go 1.22 or later.\n\n## Quick start\n\nA minimal server with an in-memory store and Docker provider:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    \"net/http\"\n    \"os\"\n    \"os/signal\"\n    \"time\"\n\n    \"github.com/xraph/ctrlplane/api\"\n    \"github.com/xraph/ctrlplane/app\"\n    \"github.com/xraph/ctrlplane/auth\"\n    \"github.com/xraph/ctrlplane/provider/docker\"\n    \"github.com/xraph/ctrlplane/store/memory\"\n)\n\nfunc main() {\n    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)\n    defer stop()\n\n    memStore := memory.New()\n    dockerProv, err := docker.New(docker.Config{\n        Host: \"unix:///var/run/docker.sock\",\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    cp, err := app.New(\n        app.WithStore(memStore),\n        app.WithAuth(auth.NewNoopProvider()),\n        app.WithProvider(\"docker\", dockerProv),\n        app.WithDefaultProvider(\"docker\"),\n    )\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    if err := cp.Start(ctx); err != nil {\n        log.Fatal(err)\n    }\n    defer cp.Stop(context.Background())\n\n    srv := \u0026http.Server{\n        Addr:              \":8080\",\n        Handler:           api.New(cp).Handler(),\n        ReadHeaderTimeout: 10 * time.Second,\n    }\n\n    go func() {\n        \u003c-ctx.Done()\n        srv.Shutdown(context.Background())\n    }()\n\n    log.Println(\"ctrlplane listening on :8080\")\n    if err := srv.ListenAndServe(); err != http.ErrServerClosed {\n        log.Fatal(err)\n    }\n}\n```\n\nCreate a tenant:\n\n```bash\ncurl -X POST http://localhost:8080/v1/admin/tenants \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Acme Corp\", \"slug\": \"acme\", \"plan\": \"pro\"}'\n```\n\nCreate an instance:\n\n```bash\ncurl -X POST http://localhost:8080/v1/instances \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"tenant_id\": \"ten_...\",\n    \"name\": \"web-app\",\n    \"image\": \"nginx:alpine\",\n    \"provider_name\": \"docker\",\n    \"resources\": {\"cpu_millis\": 500, \"memory_mb\": 256},\n    \"ports\": [{\"container_port\": 80, \"protocol\": \"tcp\"}]\n  }'\n```\n\n## Package structure\n\n```\nctrlplane.go          Root package (Entity, Config, sentinel errors)\nid/                      TypeID-based identifiers (prefix-qualified, UUIDv7)\nauth/                    Authentication and authorization interface\ninstance/                Instance lifecycle management\ndeploy/                  Deployments, releases, and strategies\nhealth/                  Health checks (HTTP, TCP, gRPC, command)\nnetwork/                 Domains, routes, TLS certificates\nsecrets/                 Secret management with pluggable vault\ntelemetry/               Metrics, logs, traces, resource snapshots\nadmin/                   Tenant management, quotas, audit\nevent/                   Event bus and webhooks\nworker/                  Background task scheduler\nprovider/                Cloud provider abstraction\n  docker/                Docker provider (implemented)\n  kubernetes/            Kubernetes (interface defined)\n  aws/, gcp/, azure/     Cloud providers (interface defined)\n  nomad/, fly/           Additional providers (interface defined)\nstore/                   Persistence layer\n  memory/                In-memory (tests and development)\n  sqlite/                SQLite (standalone deployments)\n  postgres/              PostgreSQL (production)\napi/                     HTTP handlers and middleware\napp/                     Root orchestrator (wires everything together)\nextension/               Forge extension adapter\ncmd/ctrlplane/        Reference binary\n```\n\n## Key interfaces\n\nEvery subsystem is defined by Go interfaces. Swap out any piece with your own implementation.\n\n| Interface | Package | Purpose |\n|-----------|---------|---------|\n| `provider.Provider` | `provider/` | Cloud orchestrator abstraction |\n| `instance.Service` | `instance/` | Instance CRUD and lifecycle |\n| `deploy.Service` | `deploy/` | Deployment orchestration |\n| `deploy.Strategy` | `deploy/` | Pluggable deployment strategy |\n| `health.Checker` | `health/` | Health check implementation |\n| `network.Router` | `network/` | Traffic routing abstraction |\n| `secrets.Vault` | `secrets/` | Backend secret storage |\n| `telemetry.Collector` | `telemetry/` | Custom telemetry source |\n| `event.Bus` | `event/` | Event publish/subscribe |\n| `auth.Provider` | `auth/` | Authentication and authorization |\n| `store.Store` | `store/` | Aggregate persistence |\n\n## Forge extension\n\nMount Ctrl Plane into a Forge application:\n\n```go\napp := forge.New()\napp.Use(cpext.New(\n    cpext.WithProvider(\"k8s\", kubernetesProvider),\n    cpext.WithAuthProvider(authsomeAdapter),\n))\napp.Run()\n```\n\n## Documentation\n\nFull documentation is available in the `docs/` directory and covers architecture, core concepts, every subsystem, guides for writing custom providers and deployment strategies, and the complete HTTP API reference.\n\n## Development\n\n```bash\ngo build ./...\ngo test ./...\ngolangci-lint run ./...\ngoimports -w -local github.com/xraph/ctrlplane .\n```\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fctrlplane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxraph%2Fctrlplane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fctrlplane/lists"}