Architecture & Stack
Kuberfy was built from the ground up to challenge the convention that a self-hosted PaaS needs multiple server processes, separate databases, and heavy cache brokers.
The Tech Stack
| Layer | Choice | Why We Chose It |
|---|---|---|
| Backend API | Bun + Hono | Minimal runtime and framework footprint without Node.js overhead. |
| Database | SQLite (bun:sqlite) + Drizzle ORM | Embedded inside the single process. Zero database servers to manage or backup. |
| Frontend | Astro + React Islands (shadcn/ui) | Pure static HTML output by default; React islands only hydrate interactive components. |
| Authentication | Better Auth | Secure email/password authentication, admin roles, and session tokens. |
| Reverse Proxy & SSL | Traefik v3 | Dynamic auto-discovery via Docker labels and automated Let's Encrypt certificates. |
| Orchestrator | Docker Swarm (Single-node) | Native zero-downtime rolling updates and service mesh with zero extra daemon weight. |
| Deploy Engine | dockerode + simple-git | Interacts with the Docker socket directly via typed APIs (no insecure shell command generation). |
Data Model
The database structure is designed to be clear and extensible:
User (Better Auth) ──▶ Project ──▶ Application ──▶ Deployment
│
└──▶ Domain- Projects: Logical groups for related applications (e.g. backend, frontend, worker).
- Applications: Service configurations including Git repository or Docker image, build strategy, environment variables, and internal port.
- Deployments: Immutable historical records of every build and rollout with build logs and status indicators.
- Domains: Custom hostnames mapped to applications via Traefik labels.
Why Docker Swarm (Single Node)?
Kuberfy uses Docker Swarm in single-node mode. Unlike Kubernetes or Nomad which require separate control planes and significant memory, Docker Swarm is built directly into dockerd:
- Zero-Downtime Rollouts: When deploying a new version, Swarm starts the new container, verifies health, and seamlessly terminates the old one.
- Zero Additional RAM: Initializing Swarm adds 0 MB of extra daemon footprint.
- Shared Network Mesh: All applications connect to
kuberfy-network, allowing Traefik to route traffic internally without publishing host ports.
Security Architecture
No Shell Injection: Kuberfy never constructs or executes shell commands with user inputs to control Docker. All container operations (pulling images, creating services, inspecting tasks, tailing logs) are executed through typed HTTP calls over the Docker Unix socket via dockerode.