blissful-infra spins up a real enterprise-shaped stack on your laptop. A Spring Boot backend, a local Kubernetes cluster provisioned by Terraform, ArgoCD syncing your services from a real git repo, Argo Rollouts running canary deploys and a dashboard where you watch traffic shift and press Promote.
The point is that you should be able to try an architecture pattern, throw it away and try the next one in the time it usually takes to read the docs for one of them.
npm install -g @blissful-infra/cliblissful-infra initinit walks you through your first tenant, project and service, then brings it all up. Get started
Off the boilerplate
One command scaffolds compose files, ports, networks, database schemas and a git repo.
Observability (Prometheus scrape, Grafana dashboards, Loki, Tempo) is wired in from the start. Jenkins pipeline pre-configured. AI agent connected over MCP.
The experiment is the first thing you touch, not the last.
Closer to the infrastructure
The pieces are real. Real Kafka, real Postgres, real ArgoCD. Nothing is mocked when an open-source equivalent exists.
Config files are plain (docker-compose.yaml, Jenkinsfile, rollout.yaml). Read them, modify them, fork them. Watch a consumer group actually rebalance. Watch a Rollout hold at 25% until you promote it.
When the experiment raises a question about the architecture, the answer is in the repo.
Everything hangs off a three-level hierarchy that mirrors how cloud providers structure things and how DDD structures domains.
| Level | Maps to | Owns |
|---|---|---|
| Tenant | Organization | Dashboard, Jenkins, observability stack and optionally a local Kubernetes cluster |
| Project | Domain | Kafka event bus, Postgres, API gateway, isolated Docker network, plus a runtime: compose or kubernetes |
| Service | Bounded context | One process. Own DB schema. Talks to the world through the project’s event bus or gateway |
blissful-infra use <tenant>/<project> sets a persistent context so you rarely retype the path. Ports are allocated deterministically per level, so collisions are impossible by construction.
Compose (default)
Every service is a container on the project’s isolated Docker network. Backends get a dedicated Postgres schema, Kafka bootstrap servers, Prometheus scrape labels and Loki log shipping.
Fast to start, nothing to install beyond Docker.
Kubernetes
The tenant owns a kind cluster provisioned by Terraform, running ArgoCD, Argo Rollouts and Gitea. Projects are namespaces. Deploys are GitOps for real: manifests are pushed to the in-cluster Gitea repo and ArgoCD syncs them.
One toolchain. Pick the entry point that matches what you are trying to do.
Build
Prototype-first. You have an architecture experiment or a product idea to validate. One command to a real stack you can pull apart.
Learn
Go deeper. Students and engineers who want to understand how production systems work without a cloud bill. Kafka, Postgres, CI/CD, observability, GitOps and progressive delivery. The same stack real teams run.
Deliver
Many projects, one laptop. Indie studios and small teams. Each tenant gets its own isolated stack with its own Kafka, Postgres, observability and CI. No SaaS bill stacking up per project.
Curious why blissful-infra runs real open-source services instead of bundling managed-service emulators? Read the philosophy
A tenant brings up its own observability and CI stack. A project brings up its own data infrastructure. Ports are derived from the tenant and project index, so a second tenant lands one port up from the first and never collides.
| Service | Level | First tenant lands on |
|---|---|---|
| Dashboard | Host (one for all tenants) | localhost:3002 |
| Grafana | Tenant | localhost:3000 |
| Loki | Tenant | localhost:3100 |
| Tempo | Tenant | localhost:3200 |
| Prometheus | Tenant | localhost:9090 |
| Jenkins | Tenant | localhost:8081 |
| ArgoCD | Tenant (kubernetes runtime) | localhost:8440 |
| Gitea | Tenant (kubernetes runtime) | localhost:3300 |
| Kafka | Project | localhost:9092 |
| Postgres | Project | localhost:5432 |
| Redis | Project | localhost:6379 |
| API gateway | Project | localhost:8080 |
Run blissful-infra status at any time to see the ports your tenants actually got.
blissful-infra runs entirely on your laptop. Docker Desktop is the only hard dependency; the Kubernetes runtime additionally needs kind, kubectl and terraform, all installable with one brew install. Nothing requires a cloud account and no per-hour costs tick up while you work.
Spin up a tenant, experiment, blow it away, start fresh. The whole stack is isolated, reproducible and disposable on demand.
Local kind is the rehearsal. When a service is ready to ship for real, promote it to Cloudflare:
blissful-infra service add orders --type backend --template honoblissful-infra service up orders # runs in a container locallyblissful-infra deploy orders --target cloudflare # WorkersThe hono template keeps its application code free of node:* imports, so the same source runs under Node in the container and on Cloudflare Workers with no rewrite. Frontends go to Pages the same way.
That is opt-in and needs your own Cloudflare account. Note that a promoted service leaves the project’s Kafka and Postgres behind, which deploy explains in full.
The Kubernetes runtime runs real canary deploys. A rollout walks 10%, 25%, 50%, then 100%, pausing at each step so you can promote early or abort:
blissful-infra deploy orders # build, kind load, gitops push, ArgoCD syncblissful-infra canary status orders # 10% canary / 90% stable, step 1/7blissful-infra canary promote orders --fullblissful-infra rollback orders # git revert in the gitops repo; ArgoCD converges backEvery deploy is a commit in the tenant’s Gitea repo. Open it to see the audit trail ArgoCD syncs from. The dashboard’s Environments tab shows the same rollout with a live weight bar and Promote / Abort buttons.