Installation
Knecht is installed on a server you control. One script sets up Docker, the DDEV CLI, and the app itself. This page ends when the dashboard is reachable under your domain. What happens on the first visit is covered in Setup.
Requirements
Server
A fresh server with root access, used only for Knecht. This can be:
- A VPS, for example a Hetzner CX23 or CX33
- A dedicated server or a virtual machine
- A Mac, for example a Mac mini, through a Lima VM. See Install on macOS.
Operating System
- Ubuntu 24.04
- amd64 or arm64
The installer stops on other distributions. Other Ubuntu versions are not tested.
Hardware
Every running preview costs one web and one database container. More parallel previews need more RAM.
Domain and Network
- A domain or subdomain for the instance, for example
knecht.example.com - Access to its DNS, for two records you set after the install
- Ports 80 and 443 reachable from the internet
Install on Linux
As root on the fresh server:
curl -fsSL https://raw.githubusercontent.com/knecht-works/knecht-cloud/main/scripts/install.sh | bash
The installer asks for your domain and does the rest. It installs Docker and the pinned DDEV CLI, warms up the DDEV images, checks out the latest release under /opt/knecht, writes a .env, and starts the app together with the Caddy TLS entry point via Docker Compose. It takes a few minutes and is safe to re-run if something breaks halfway.
KNECHT_DOMAIN=knecht.example.com bash. Any further KNECHT_* variable, for example KNECHT_AI_KEY, is carried into the .env and locks that setting in the dashboard.Set the DNS Records
Two A records, both pointing at the server's IP:
knecht.example.com
*.preview.knecht.example.com
The wildcard serves the preview URLs. Every session gets its own hostname below preview.
Open Ports 80 and 443
Both must be reachable from the internet. On a cloud VPS this usually means a rule in the provider's firewall.
Open the Dashboard
Visit https://knecht.example.com. Caddy fetches the certificate on first start, so the first request can take a moment. The page that opens is the GitHub App setup, continued in Setup.
Install on macOS
The run substrate, host Docker plus DDEV, is Linux only. On a Mac the same setup runs inside a Lima VM. The template from the repo gives the VM 4 CPUs, 8 GB RAM, and 80 GB disk, and forwards ports 80 and 443 on all interfaces of the Mac.
Create the VM
brew install lima
limactl create --name=knecht https://raw.githubusercontent.com/knecht-works/knecht-cloud/main/scripts/lima-server.yaml
limactl start knecht
Run the Installer inside the VM
limactl shell knecht
curl -fsSL https://raw.githubusercontent.com/knecht-works/knecht-cloud/main/scripts/install.sh | sudo bash
The installer asks for the domain, the same as on Linux.
Make the Mac Reachable
The three steps from the Linux install apply unchanged: DNS records, ports, dashboard. On a home network, two things come on top:
- Forward TCP ports 80 and 443 on your router to the Mac, and give the Mac a fixed address in the router.
- Home connections change their public IP over time. Point the two DNS records at a dynamic DNS name, or get a static IP from your ISP.
After a Reboot
The VM does not start on its own. Run limactl start knecht after a macOS reboot, the containers inside come back up by themselves. /opt/knecht and /data/knecht live inside the VM, reachable through limactl shell knecht.
Local Domain for Testing
To try Knecht on a Mac without any DNS setup, install it under a local domain. GitHub cannot reach the instance then, so webhooks never arrive and GitHub triggers do not fire. Manual and scheduled triggers work.
Use lvh.me as the domain
lvh.me is a public domain that, together with all its subdomains, always resolves to 127.0.0.1. It needs no DNS setup and no entries in /etc/hosts. Enter lvh.me when the installer asks for the domain, then the dashboard and every preview subdomain work locally. Ports 80 and 443 on the Mac must be free.
Switch Caddy to its internal CA
Let's Encrypt cannot issue certificates for a local domain. Inside the VM, edit /opt/knecht/Caddyfile so both site blocks use tls internal:
{$KNECHT_BASE_DOMAIN} {
tls internal
reverse_proxy knecht:3000
}
https:// {
tls internal {
on_demand
}
reverse_proxy knecht:3000
}
Restart Caddy and open the dashboard
cd /opt/knecht && sudo docker compose restart caddy
Open https://lvh.me and accept the certificate warning.
Once the dashboard opens, continue with Setup. Updating, backups, and pre-releases are on Maintenance.