Installation

This page covers every way to get kipuka running: pulling a pre-built container image, building from source, and installing as a systemd service.

Prerequisites

Container (fastest)

Pre-built images are published to the kipuka container registry for both x86_64 and aarch64:

# x86_64 (default)
podman pull registry.kipuka.dev/kipuka:latest

# Apple Silicon / ARM servers
podman pull registry.kipuka.dev/kipuka:latest-arm64

Run the container with a bind-mounted configuration directory:

podman run -d \
  --name kipuka \
  -p 9443:9443 \
  -v /etc/kipuka:/etc/kipuka:ro \
  -v /var/lib/kipuka:/var/lib/kipuka:rw \
  registry.kipuka.dev/kipuka:latest \
  kipuka --config /etc/kipuka/kipuka.toml

The container image ships a minimal filesystem. All state lives in /var/lib/kipuka (database, OTP records) and all configuration is read from /etc/kipuka. TLS certificates and CA key material are expected under /etc/kipuka/tls/ and /etc/kipuka/ca/ respectively.

Tip: For Kubernetes or OpenShift deployments, mount the configuration as a ConfigMap and secrets (TLS keys, CA keys) as Secret volumes.

Building from source

Clone the repository and build in release mode:

git clone https://codeberg.org/czinda/kipuka.git
cd kipuka
cargo build --release

The workspace contains six crates:

The final binary is at target/release/kipuka.

OS-specific build dependencies

Fedora / RHEL / CentOS Stream

sudo dnf install openssl-devel clang cmake pkg-config

Debian / Ubuntu

sudo apt install libssl-dev clang cmake pkg-config

macOS

brew install openssl cmake
export OPENSSL_DIR=$(brew --prefix openssl)

Installing the binary

Copy the release binary to a location on $PATH:

sudo cp target/release/kipuka /usr/local/bin/
sudo chmod 755 /usr/local/bin/kipuka

Verify the installation:

kipuka --version

systemd service

Create a dedicated service account:

sudo useradd -r -s /sbin/nologin -d /var/lib/kipuka kipuka
sudo mkdir -p /var/lib/kipuka /var/log/kipuka /etc/kipuka
sudo chown kipuka:kipuka /var/lib/kipuka /var/log/kipuka

Install the unit file at /etc/systemd/system/kipuka.service:

[Unit]
Description=kipuka EST enrollment server
Documentation=https://codeberg.org/czinda/kipuka
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=kipuka
Group=kipuka
ExecStart=/usr/local/bin/kipuka --config /etc/kipuka/kipuka.toml
Restart=on-failure
RestartSec=5s

# Security hardening
PrivateTmp=true
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
ReadWritePaths=/var/lib/kipuka /var/log/kipuka
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=kipuka

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now kipuka
sudo systemctl status kipuka

Note: The CAP_NET_BIND_SERVICE capability allows kipuka to bind to port 443 without running as root. If you run on a high port (e.g., 9443) you can remove both CapabilityBoundingSet and AmbientCapabilities lines.

Running tests

The full test suite runs against an in-memory SQLite database and does not require any external services:

cargo test

To run tests for a specific crate:

cargo test -p kipuka-est
cargo test -p kipuka-hsm

Integration tests that require a running EST server are gated behind a feature flag:

cargo test --features integration

Next: First Run walks you through creating a minimal configuration and starting the server.