Important
MADFAM-ENCLII-FIRST-LEGACY-RAW v1: This document contains legacy raw infrastructure command examples.
Routine production operations must use Enclii web, API, or CLI. Treat raw
kubectl, helm, SSH, provider CLI/API, docker exec, and direct container
access as platform bootstrap or documented break-glass only, and record any
missing Enclii adapter gap.
Deploy, scale, and operate — on infrastructure you own. Open source DevOps platform with production-grade Kubernetes on Hetzner + Cloudflare.
Status: Production-running beta | Production Checklist → Authentication: OIDC via Janua SSO (RS256 JWT) - Integrated Infrastructure: Hetzner Dedicated + Cloudflare - Running
Enclii is an open source DevOps platform for deploying, scaling, and operating containerized services with enterprise-grade security, GitOps automation, and zero vendor lock-in.
"We run our entire platform on Enclii, authenticated by Janua. We are our own most demanding customer."
Production Services:
- ✅ Control Plane API (
api.enclii.dev) - ✅ Web Dashboard (
app.enclii.dev) - ✅ Admin Platform (
admin.enclii.dev) - ✅ Authentication (
auth.madfam.io) → Janua SSO (OIDC) - ✅ Documentation (
docs.enclii.dev) - ✅ Landing Page (
enclii.dev) - ✅ Status Page (
status.enclii.dev,status.madfam.io)
All services deploy via zero-touch onboarding — K8s manifests and CI workflows live in each repo, not here. See onboarding guide →
Enclii is the required control plane for MADFAM DevOps and provisioning:
- Enclii web, API, and CLI are mandatory for routine production provisioning, deployment, observability, domains, secrets, provider operations, scaling, rollback, and remediation.
enclii opsreplaces routinekubectl, ArgoCD, Longhorn, Kyverno, ExternalSecrets, Vault, and ARC manipulation.enclii providersreplaces routinegh, Cloudflare, Porkbun, and Hetzner manipulation.- Switchyard API is the agent-facing contract Selva and other agents should call.
- Raw
kubectl,helm, SSH, provider CLIs/APIs,docker exec, and direct container access are allowed only for platform bootstrap or documented break-glass emergencies when Enclii is unavailable or lacks an implemented adapter. - Missing adapter gaps must be recorded and remediated in Enclii rather than normalized as routine operator procedure.
Current Hetzner Topology:
| Surface | Role | Hardware |
|---|---|---|
| The Sanctuary | Production workloads | Hetzner dedicated server |
| The Forge | CI/CD builder capacity | Hetzner Cloud VPS |
Cost-Optimized Stack:
- Cloudflare Tunnel - Zero-trust ingress (replaces load balancers)
- Cloudflare for SaaS - 100 custom domains FREE
- Cloudflare R2 - Zero-egress object storage
- Self-hosted PostgreSQL - In-cluster with persistent storage
- Self-hosted Redis - In-cluster caching (Sentinel ready for multi-node)
Builder Node Targeting: Build workloads are isolated on "The Forge" via Kubernetes taints (
builder=true:NoSchedule). Production apps run exclusively on "The Sanctuary".
Infrastructure Audit (Jan 2026): Evaluated Ubicloud managed PostgreSQL and Redis Sentinel. Decision: NOT NEEDED for 99.5% SLA / 24-hour RPO. Sentinel manifests staged for future multi-node deployment.
Self-hosted infrastructure is significantly cheaper than equivalent SaaS platforms, but the platform is still a production-running beta until the remaining blockers below are closed.
OIDC/OAuth 2.0 - Full Implementation:
- ✅ Janua SSO Integration - Self-hosted OAuth 2.0/OIDC provider
- ✅ RS256 JWT Signing - RSA 2048-bit keys with JWKS rotation
- ✅ External JWKS Validation - Federated identity support
- ✅ PKCE Support - Secure authorization code flow
- ✅ Token Refresh - Automatic refresh with rotation
Social & Enterprise Auth:
- ✅ GitHub OAuth - Repository imports with linked accounts
- ✅ Google OAuth - One-click sign-in
- ✅ Microsoft OAuth - Azure AD integration ready
- ✅ SAML 2.0 SSO - Enterprise IdP support via Janua
Access Control:
- ✅ RBAC - Admin/Developer/Viewer roles with granular permissions
- ✅ Multi-Tenant Organizations - Namespace isolation per tenant
- ✅ API Keys - Service accounts for CI/CD pipelines
- ✅ Session Management - Redis-backed with secure cookies
Security Hardening:
- ✅ Rate Limiting - 1,000-10,000 req/min tiers
- ✅ Security Headers - HSTS, CSP, X-Frame-Options
- ✅ Audit Logging - Immutable security event trail
- ✅ RP-Initiated Logout - Full SSO session termination
Cost Advantage:
- ✅ $0/month vs Auth0 ($220+) or Clerk ($300+)
- ✅ No per-MAU pricing - Unlimited users
- ✅ No vendor lock-in - Own your auth infrastructure
Cloudflare for SaaS enables unlimited custom domains:
- ✅ First 100 domains FREE
- ✅ $0.10/domain after that
- ✅ Auto-provisioned SSL in ~30 seconds
- ✅ No cert-manager rate limits
- ✅ No Kubernetes overhead
Perfect for: SaaS platforms serving multiple customers with custom domains.
Developer Experience:
- Intuitive CLI (
enclii init,enclii up,enclii deploy) - Auto-detect buildpacks (Nixpacks, Buildpacks, Dockerfile)
- Preview environments on every PR
- Real-time log streaming
Security & Compliance:
- RS256 JWT authentication with RSA signing
- RBAC with admin/developer/viewer roles
- Rate limiting (1,000-10,000 req/min)
- Security headers (HSTS, CSP, X-Frame-Options)
- Audit logging with immutable trail
- Image signing (Cosign) + SBOM (CycloneDX)
Operations:
- Canary deployments with auto-rollback
- Blue-green deployment strategy
- Horizontal pod autoscaling (HPA)
- Redis caching with tag-based invalidation
- PgBouncer connection pooling
- Prometheus + Grafana monitoring
Multi-Tenancy:
- NetworkPolicies (zero-trust networking)
- ResourceQuotas per tenant
- Per-tenant metrics and logging
- Cost tracking and showback
enclii/
├── apps/
│ ├── switchyard-api/ # Control plane API (Go)
│ ├── switchyard-ui/ # Web dashboard (Next.js)
│ └── roundhouse/ # Build workers (Go)
├── packages/
│ └── cli/ # `enclii` CLI (Go)
├── infra/
│ ├── k8s/ # Kubernetes manifests
│ │ ├── base/ # Core infrastructure
│ │ ├── staging/ # Staging overlays
│ │ └── production/ # Production overlays
│ └── terraform/ # Infrastructure as Code
├── docs/ # Documentation
└── examples/ # Sample service specs
Production Names (all railroad-themed 🚂):
- Switchyard - Control plane API
- Conductor - CLI (
encliicommand) - Roundhouse - Build/provenance/signing workers
- Junctions - Ingress/routing/DNS/TLS
- Timetable - Cron jobs and scheduled tasks
- Lockbox - Secrets management (Vault client + ESO in production)
- Signal - Observability (implemented:
/v1/observability/*, Prometheus + Grafana) - Waybill - Infrastructure cost metering and usage showback
From PRODUCTION_CHECKLIST.md:
Infrastructure (Complete):
- ✅ Hetzner Cloud k3s cluster running
- ✅ Cloudflare Tunnel integration
- ✅ PostgreSQL with health checks
- ✅ Redis for caching/sessions
- ✅ NetworkPolicies for zero-trust
Authentication (Complete):
- ✅ OIDC via Janua SSO (RS256 JWT)
- ✅ External JWKS validation
- ✅ GitHub OAuth linked accounts
- ✅ RBAC with role-based access
Build Pipeline (Complete):
- ✅ GitHub webhook CI/CD
- ✅ Buildpacks/Dockerfile detection
- ✅ Container registry push (ghcr.io)
- ✅ Real deployments (not simulated)
Remaining blockers before full production-ready status:
⚠️ Load testing validation against expected production traffic and failure modes⚠️ Final security audit with documented remediation status⚠️ Documented backup restore drill for PostgreSQL, Redis, and critical platform state⚠️ HA/multi-node expansion plan and failover runbook for components that still depend on single-instance capacity
If you just want to ship an app to Enclii, the fastest path is:
VERSION=v1.0.0-alpha.1
OS=linux # use darwin for macOS
ARCH=amd64 # use arm64 on Apple Silicon or ARM Linux
curl -LO "https://github.com/madfam-org/enclii/releases/download/${VERSION}/enclii_${VERSION}_${OS}_${ARCH}.tar.gz"
tar -xzf "enclii_${VERSION}_${OS}_${ARCH}.tar.gz"
sudo install -m 0755 "enclii_${VERSION}_${OS}_${ARCH}/enclii" /usr/local/bin/enclii
enclii login
cd my-app && enclii init
enclii deploy
# → Live at https://dev.my-app.enclii.devFull 5-minute quickstart → docs.enclii.dev/quickstart
Migrating from another platform?
This repository contains the full source for Enclii itself. If you're bootstrapping a self-hosted cluster (bare-metal or cloud), continue below. Most users don't need to do this — app.enclii.dev is the hosted control plane.
Local development prerequisites
Core:
- Docker ≥ 24
- kubectl ≥ 1.29
- kind ≥ 0.23 (for local dev)
- Helm ≥ 3.14
Languages:
- Go ≥ 1.22
- Node.js ≥ 20
- pnpm ≥ 9
macOS:
brew install go node pnpm kind helm kubectl dockerNPM Registry Configuration
Enclii uses MADFAM's private npm registry for internal packages. Configure your .npmrc:
# Add to your project's .npmrc or ~/.npmrc
@madfam:registry=https://npm.madfam.io
@enclii:registry=https://npm.madfam.io
@janua:registry=https://npm.madfam.io
# Auth token only needed for publishing (not for installing @enclii/* or @janua/* packages)
//npm.madfam.io/:_authToken=${NPM_MADFAM_TOKEN}@enclii/* and @janua/* packages have public read access — no token required for npm install. The NPM_MADFAM_TOKEN is only needed for publishing or installing private scopes (@madfam/*, @dhanam/*, etc.).
See NPM Registry for details.
Local development (10 minutes)
# 1. Clone and bootstrap
git clone https://github.com/madfam-org/enclii
cd enclii
make bootstrap # Install dependencies
# 2. Start local Kubernetes
make kind-up # Create kind cluster
make infra-dev # Install NGINX Ingress, cert-manager, Prometheus
make dns-dev # Configure dev DNS
# 3. Run the platform
make run-switchyard # Control plane API on :8001
make run-ui # Web UI on http://localhost:8030
# 4. Try the CLI
make build-cli
./bin/enclii init # Scaffold a service
./bin/enclii up # Deploy preview environment
./bin/enclii deploy --env prod # Deploy to production
./bin/enclii logs api -f # Tail logsSelf-hosted production deployment
See Production Deployment Roadmap for the complete 8-week implementation plan.
Bootstrap:
# Provision Hetzner cluster
hcloud server create --name enclii-node-{1,2,3} --type cpx31
# Configure Cloudflare Tunnel
cloudflared tunnel create enclii-production
# Bootstrap-only: first cluster/platform install before Enclii can manage itself.
kubectl apply -k infra/k8s/productionenclii init # Scaffold a new service from template
enclii up # Build & deploy current branch (preview)
enclii deploy # Deploy to production with canary
enclii logs <service> # Stream logs
enclii ps # List services, versions, health
enclii scale # Configure autoscaling
enclii secrets set # Manage secrets
enclii rollback # Revert to previous release
enclii auth login # Authenticate via Janua OAuthCommon workflows:
# Deploy with canary strategy
enclii deploy --env prod --strategy canary --wait
# Set secrets
enclii secrets set DATABASE_URL=postgres://... --env prod
# Custom domain
enclii routes add --host api.example.com --service api --env prod
# Scale to 5 replicas
enclii scale --min 5 --max 10 --service api --env prod📚 Complete Documentation Index →
Getting Started:
- 5-minute Quickstart - Deploy your first service
- Template Catalog - Starter templates by framework
- Migration Index - From Vercel / Railway / Heroku
- Onboarding Guide - Zero-touch repo onboarding
- Platform Contributor Setup - Local dev in 10 minutes
- Production Deployment Roadmap - 8-week plan
Architecture:
- Architecture Overview - System design
- API Documentation - REST API reference
- Development Guide - Contributing guide
Infrastructure (Jan 2026):
- GitOps with ArgoCD - App-of-Apps pattern, self-heal
- Storage with Longhorn - Replicated CSI storage
- Cloudflare Integration - Zero-trust tunnel routing
- External Secrets - Secret synchronization
Audits & Reports:
- Audit Navigation - Browse all audit reports
- Master Audit Report - Comprehensive overview
Operations:
- Deployment Guide - Production ops
- Secrets Management - Lockbox integration
| Feature | Railway | Enclii |
|---|---|---|
| Cost | Expensive | Self-hosted (fraction of SaaS cost) |
| Custom Domains | Limited, expensive | 100 FREE (Cloudflare for SaaS) |
| Vendor Lock-In | Full lock-in | None (portable Kubernetes) |
| Auth | Bring your own (expensive) | Janua included |
| Bandwidth | Expensive egress | Zero egress (Cloudflare R2) |
| Multi-Tenancy | Not designed for it | Built-in (NetworkPolicies, quotas) |
| Self-Hosting | Impossible | Fully self-hosted |
| Feature | Vercel + Clerk | Enclii |
|---|---|---|
| Cost | Expensive | Self-hosted (fraction of cost) |
| Backend Support | Limited (Functions) | Full container support |
| Database | Bring your own | Self-hosted PostgreSQL included |
| Auth | Clerk (expensive) | Janua included |
| Control | SaaS (no control) | Full control (self-hosted) |
Why self-hosted infrastructure matters:
- Cost Control - Fraction of equivalent SaaS cost
- No Vendor Lock-In - Portable Kubernetes, standard tools
- Data Sovereignty - Your infrastructure, your rules
- Unlimited Scale - No artificial SaaS limits
- Self-Hosted Auth - No Auth0/Clerk dependency
- Custom Compliance - Meet any regulatory requirement
- ✅ Control plane API (Switchyard)
- ✅ CLI (
enclii init/up/deploy/logs) - ✅ Web UI (Next.js dashboard)
- ✅ JWT authentication (RS256)
- ✅ RBAC (admin/developer/viewer)
- ✅ Preview environments
- ✅ Kubernetes reconciliation (embedded in control plane)
- ✅ Cloudflare Tunnel integration
- ✅ Redis caching
- ✅ OIDC/JWKS provider via Janua
- ✅ External JWKS validation
- ✅ OAuth 2.0 handlers
- ✅ Frontend OIDC integration
- ✅ Janua running at auth.madfam.io
- ✅ GitHub OAuth linked accounts
- ✅ Self-hosted (Enclii deploys itself)
- ✅ Real build pipeline (Buildpacks/Dockerfile)
- ✅ GitHub webhook CI/CD
- ✅ Container registry push (ghcr.io)
- ✅ ArgoCD GitOps deployment (Jan 2026)
- ✅ Longhorn CSI storage (Jan 2026)
- ✅ Cloudflare tunnel route automation (Jan 2026)
- ✅ Product bets A/B/C staging-proven (May 2026)
⚠️ Security release sign-off — SECURITY_RELEASE_PR.md⚠️ 30-day SLO window — pending Wave 0+1
Master plan: COMMERCIAL_GA_MASTER_PLAN.md · Target announce: ~2026-07-14
- Wave 0–1: Ops closure (security, DR, Vault)
- Wave 2: Monetization QA (signup, pricing, Dhanam)
- Wave 3: 30-day SLO → Stability GA
- Wave 4: SLA, support, legal publish → Commercial GA
Post-GA: multi-region, managed DB marketplace, KEDA custom metrics, full SOC 2 attestation.
See CONTRIBUTING.md for the full guide. Quick checklist:
Boundary checkpoint (2026-06-04, platform owner): this public quick-start only
links the repository boundary policy and keeps private operational topology,
credential, cost, and incident detail in internal-devops. Policy:
docs/PUBLIC_REPO_BOUNDARY.md and
repo-boundary contract.
Keep implementation guidance public-safe. If a detail is private/sensitive, place it in internal-devops and link from here with a sanitized summary.
- Read CLAUDE.md for project conventions
- Run
make precommitbefore pushing - Use conventional commits for changelog
- Open draft PR early for feedback
Supply Chain Security:
- SBOM generation (CycloneDX format)
- Image signing (Cosign with RSA keys)
- Base image rotation every 30 days
- Vulnerability scanning (Trivy)
Runtime Security:
- Zero-trust networking (NetworkPolicies)
- Non-root containers (UID 65532)
- Read-only root filesystem
- Dropped Linux capabilities
- Seccomp profiles enabled
Responsible Disclosure: Email: security@enclii.dev
We run our entire production infrastructure on Enclii, authenticated by Janua.
When prospects ask "Can Enclii handle production?" — we answer with verifiable proof:
"We run our entire production on Enclii. Here's our status page showing 99.95% uptime. We deploy 10-20 times per day with zero downtime using our own platform."
Production services running today:
- Control Plane API at api.enclii.dev
- Web Dashboard at app.enclii.dev
- Admin Platform at admin.enclii.dev
- Janua Auth at auth.madfam.io
- Status pages at status.enclii.dev, status.madfam.io
Why this matters:
- Customer confidence: "If they trust it, we can too"
- Product quality: We find bugs before customers do
- Sales credibility: Authentic production usage metrics
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) to protect the sovereignty of the infrastructure and ensure that all modifications remain open source when deployed as a network service.
Copyright (C) 2025 Innovaciones MADFAM SAS de CV
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see LICENSE or visit https://www.gnu.org/licenses/agpl-3.0.html.
The AGPL-3.0 license ensures that:
- Network Copyleft: Anyone running a modified version of Enclii as a network service must provide the source code to users
- Infrastructure Sovereignty: No vendor can take this code, modify it, and offer it as a proprietary service without sharing improvements
- Community Protection: All improvements and modifications must be contributed back to the community
- Freedom Preservation: Users retain the freedom to study, modify, and distribute the software
This aligns with the MADFAM Manifesto Section IV: protecting open infrastructure from proprietary capture.
This repository includes machine-readable context files following the llmstxt.org spec:
- llms.txt — Compact overview with links to all key documentation
- llms-full.txt — Full inline context including architecture, commands, debugging, and infrastructure details
- Website: enclii.dev
- Documentation: docs.enclii.dev
- Status Page: status.enclii.dev
- Janua (Auth): janua.dev | GitHub
- Production Roadmap: PRODUCTION_DEPLOYMENT_ROADMAP.md
- Onboarding Guide: ONBOARDING_GUIDE.md
Questions? Open an issue or contact the team at engineering@enclii.dev
Ready to deploy? Start with PRODUCTION_DEPLOYMENT_ROADMAP.md 🚀