Install Hakopod
Prepare a dedicated Linux server and review the installation before it changes your host.
The installer targets a dedicated Linux server on AMD64 or ARM64. It installs K3s, the management API, the dashboard and a single-node PostgreSQL database. You choose the first administrator's identity in the setup screen; there is no default account or password.
Before you begin#
Use Ubuntu 24.04 or 26.04, or Debian 12 or 13, with systemd, cgroup v2, Python 3.10 or later and swap disabled. Start with at least 4 GiB RAM and 30 GiB free disk, plus capacity for your applications and rolling updates.
Use a fresh dedicated host. The installer refuses existing Kubernetes state, conflicting ports and paths it does not own. It does not adopt another cluster or database. The supported distribution and architecture list describes implementation scope; full installation and recovery still need acceptance on a disposable matching host.
Have these ready:
- An application domain and the node's reachable IPv4 address.
- DNS pointing the application names at the node, including any required NAT forwarding.
- A dashboard access choice: an SSH tunnel, or a separate HTTPS origin with your certificate and key.
- Storage and resource limits appropriate for the workloads you plan to run.
Review the installer#
The public entrypoint is being prepared at hakopod.com/scripts/installer.sh. Until a release is published there, use the checked-in installer and locally built release artifacts. Do not substitute a download from an unrelated host.
From a trusted checkout of hakopod/hakopod, with the repository's documented Go, Node and pnpm build prerequisites installed, restore the public component sources and build the artifacts:
python3 scripts/ui-source.py restore
pnpm --dir web install --frozen-lockfile
python3 release/build.py
python3 release/build-installer.py --version 0.1.0-dev
Review the installer guide and its prerequisites, then inspect a dry run on the target host:
bash scripts/install.sh --artifact-dir .local/installer-artifacts/0.1.0-dev --dry-run
sudo bash scripts/install.sh --artifact-dir .local/installer-artifacts/0.1.0-dev
The installer asks for configuration and prints a plan. Type install to accept it. Check artifact checksums through a trusted channel: a checksum beside a download checks consistency, not the publisher's identity.
Connect and claim setup#
The default dashboard mode binds to loopback and prints an SSH tunnel command. Open the exact localhost origin it gives you. HTTPS mode instead uses the reviewed dashboard origin and operator-supplied certificate.
After readiness checks, the installer prints a command to privately read /etc/hakopod/secrets/setup-token. Enter that proof in the setup screen, then choose your name, email and password. Keep the token private. Completing setup closes the first-owner claim.
DNS, TLS and ports#
Allow application HTTP/HTTPS on TCP 80/443. Restrict the Kubernetes supervisor and node ports to your administrators and enrolled nodes; do not expose Flannel VXLAN to the internet. The installer does not configure your firewall, DNS, SSH or swap.
Application TLS can use Let's Encrypt HTTP-01 after public DNS and port 80 are reachable. Staging certificates are not browser-trusted. The dashboard's supplied HTTPS certificate has a separate renewal responsibility. Wildcard DNS-01 automation is not installed.
Additional public TCP ports are self-hosted only. An administrator provisions them before an application can request a mapping. See Networking.
Keep the recovery material#
Preserve /etc/hakopod, the original installer configuration and artifacts, the authentication encryption key, consistent database backups, K3s state and application volumes. Adding worker nodes does not make the initial database or ingress highly available.
Resume requires the original configuration and artifact bytes. It is not an upgrade command. Test recovery on a disposable supported server before relying on an installation for production. See Backups for the narrower scope of dashboard-managed backups.