About¶
Why lairkit exists¶
Running your own git, CI and deployment stack is possible with mature open-source tools. Making them work together is the hard part:
- Each tool has its own install, upgrade and backup procedure.
- Secrets end up in shell history, CI variables and
.envfiles. - Deployments depend on a laptop and a sequence of commands that only one person knows.
- Backups are assumed to work until the day someone tries to restore one.
Most alternatives swing too far the other way. Kubernetes solves this with a control plane most small teams do not want to operate. The middle ground — a few good tools, wired once, with a small operator surface — is what lairkit packages.
The approach¶
lairkit renders repositories. It is not a runtime, an agent or a control plane.
| Choice | Why |
|---|---|
| Kamal is the deployment engine | One command performs one change, and its exit code is the result. No second orchestrator to learn or debug. |
| Tailscale is the private network | Services are named, not addressed. Access is granted per Service, not per host or IP. |
| Forgejo and Infisical hold the state | Code, CI runs and secrets live in systems built for them. Git is the source of truth. |
| One facts file | config/instance.yml holds the instance's answers. Kamal renders it directly, so there is no second copy. |
| Backups on by default | Every instance backs up to S3 and includes a rehearsed restore path. |
| Evidence, not promises | A mutating action writes one evidence/* git tag with its reason and result. |
Design principles¶
- Everything is declared. If it is not in git, it is drift.
- No clickops in the operating path. Browser steps exist only at day 0.
- The tailnet is the boundary. The core has no public listener.
- Least privilege by construction. CI can read and tag evidence; it cannot rotate secrets or deploy elsewhere.
- One host per core. No cluster, no scheduler, no multi-region. Apps may share that host.
- Small tech. Bash and Kamal first; Python only where an API client is needed.
Who it is for¶
lairkit is built for the owner-operator: one technical person with a Linux host, a domain, a tailnet and a small team to support. It is also designed for the person who inherits the instance later — the repository, the tags and one status command should be enough to take over.
What it refuses to do¶
- Expose a core service to the public internet.
- Store secrets in git, tags, issues or logs.
- Keep a separate state file that can disagree with reality.
- Offer a second way to deploy, roll back or restore.
- Replace Kamal's command line with a proprietary tool.
Status¶
These docs describe the templates as written. They are not a claim that a particular instance has been deployed. Treat a fresh render as planned (or degraded when the host is unreachable) until you run the install and see it become live.
Every instance ships its own generated runbooks (INSTALL.md, BACKUP.md, RECOVERY.md, SECRETS.md and others). When those disagree with this site, the rendered repository is the authority for your instance.