### Install Snapcraft and LXD on Ubuntu

Source: https://github.com/c0m4r/kula/wiki/Snap

Standard installation commands for Ubuntu systems.

```bash
sudo snap install snapcraft --classic
sudo snap install lxd
sudo lxd init --auto
sudo usermod -aG lxd "$USER"   # log out/in so the group takes effect
```

--------------------------------

### Configure OpenRC service

Source: https://github.com/c0m4r/kula/blob/main/docs/user/15-service-management.md

Install and start the OpenRC init script.

```bash
sudo cp addons/init/openrc/kula /etc/init.d/
sudo rc-update add kula default
sudo rc-service kula start
```

--------------------------------

### Run the guided installer

Source: https://github.com/c0m4r/kula/blob/main/docs/user/02-installation.md

Executes the automated installation script which detects the distribution and verifies checksums.

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/c0m4r/kula/refs/heads/main/addons/install_v2.sh)"
```

--------------------------------

### Common CLI Examples

Source: https://github.com/c0m4r/kula/blob/main/docs/user/14-cli-reference.md

Practical examples for custom configuration, environment variable overrides, and maintenance tasks.

```bash
# Start with a custom config
kula -config /etc/kula/config.yaml

# Quick run on a specific address/port without editing config
KULA_LISTEN=127.0.0.1 KULA_PORT=9000 kula

# Inspect storage health
kula inspect

# Generate a password hash
kula hash-password
```

--------------------------------

### Install on Debian or Ubuntu

Source: https://github.com/c0m4r/kula/blob/main/docs/user/02-installation.md

Downloads and installs the .deb package, then monitors the systemd service logs.

```bash
wget https://github.com/c0m4r/kula/releases/download/<version>/kula-<version>-amd64.deb
echo "<sha256>  kula-<version>-amd64.deb" | sha256sum -c || rm -f kula-<version>-amd64.deb
sudo dpkg -i kula-<version>-amd64.deb
journalctl -f -t kula
```

--------------------------------

### Verify and run the installer manually

Source: https://github.com/c0m4r/kula/blob/main/docs/user/02-installation.md

Downloads the installation script and performs a manual SHA-256 checksum verification before execution.

```bash
KULA_INSTALL=$(mktemp)
curl -o ${KULA_INSTALL} -fsSL https://raw.githubusercontent.com/c0m4r/kula/refs/heads/main/addons/install_v2.sh
# Replace the hash below with the one published for the release you want
echo "<sha256>  ${KULA_INSTALL}" | sha256sum -c || rm -f ${KULA_INSTALL}
bash ${KULA_INSTALL}
rm -f ${KULA_INSTALL}
```

--------------------------------

### Start Monitoring Daemon

Source: https://github.com/c0m4r/kula/blob/main/docs/user/14-cli-reference.md

Starts the collector and web server. Running the command without arguments defaults to this action.

```bash
kula              # same as: kula serve
kula serve
```

--------------------------------

### Install via Snap

Source: https://github.com/c0m4r/kula/blob/main/docs/user/02-installation.md

Installs Kula using the snap package manager.

```bash
sudo snap install kula
```

--------------------------------

### Install Snapd on Arch Linux

Source: https://github.com/c0m4r/kula/wiki/Snap

Build and install snapd from the AUR.

```bash
git clone https://aur.archlinux.org/snapd.git
cd snapd
makepkg -si
```

--------------------------------

### Install Kula with Verification

Source: https://github.com/c0m4r/kula/blob/main/README.md

Downloads and verifies the installer script checksum before execution.

```bash
KULA_INSTALL=$(mktemp)
curl -o ${KULA_INSTALL} -fsSL https://raw.githubusercontent.com/c0m4r/kula/refs/heads/main/addons/install_v2.sh
echo "bad61ee9eed4595d20fa7e613bd27c3b8700c67f8a5fcac756d282a811705398 ${KULA_INSTALL}" | sha256sum -c || rm -f ${KULA_INSTALL}
bash ${KULA_INSTALL}
rm -f ${KULA_INSTALL}
```

--------------------------------

### Install on RHEL, Fedora, CentOS, or Rocky

Source: https://github.com/c0m4r/kula/blob/main/docs/user/02-installation.md

Downloads and installs the .rpm package, then monitors the systemd service logs.

```bash
wget https://github.com/c0m4r/kula/releases/download/<version>/kula-<version>-x86_64.rpm
echo "<sha256>  kula-<version>-x86_64.rpm" | sha256sum -c || rm -f kula-<version>-x86_64.rpm
sudo rpm -i kula-<version>-x86_64.rpm
journalctl -f -t kula
```

--------------------------------

### View Backup Startup Log

Source: https://github.com/c0m4r/kula/blob/main/docs/user/12-backups.md

Example log output confirming the active backup configuration on startup.

```text
Backup enabled (schedule "0 0 * * *", maxtier 3, retention 1d, compress true)
```

--------------------------------

### Install Kula on Debian/Ubuntu

Source: https://github.com/c0m4r/kula/blob/main/README.md

Downloads and installs the .deb package using dpkg.

```bash
wget https://github.com/c0m4r/kula/releases/download/0.18.6/kula-0.18.6-amd64.deb
echo "2d1aba6a839a0144fb27f0fb7a8ef695f7073700d504cae8efd2ab17eeb6a5f0 kula-0.18.6-amd64.deb" | sha256sum -c || rm -f kula-0.18.6-amd64.deb
sudo dpkg -i kula-0.18.6-amd64.deb
journalctl -f -t kula
```

--------------------------------

### Install Snapd on Manjaro

Source: https://github.com/c0m4r/kula/wiki/Snap

Install snapd using the pacman package manager.

```bash
pacman -S snapd
```

--------------------------------

### Install and Configure Kula Snap

Source: https://github.com/c0m4r/kula/wiki/Snap

Commands to install the Kula snap, connect required observation interfaces, and launch the dashboard.

```bash
# 1. Install
sudo snap install kula

# 2. Connect the observation interfaces (network/network-bind auto-connect; the
#    rest are manual — see the table further down for what each one unlocks)
sudo snap connect kula:system-observe
sudo snap connect kula:hardware-observe
sudo snap connect kula:mount-observe
sudo snap connect kula:network-observe

# 3. Open the dashboard
xdg-open http://localhost:27960    # or just browse to it
```

--------------------------------

### Configure QEMU for Alpine ISO

Source: https://github.com/c0m4r/kula/wiki/Alpine-Linux

Installs QEMU dependencies, downloads the Alpine ISO, and launches a virtual machine instance.

```bash
sudo pacman -S --needed qemu-system-x86 qemu-desktop
wget https://dl-cdn.alpinelinux.org/alpine/v3.23/releases/x86_64/alpine-standard-3.23.3-x86_64.iso
echo "966d6bf4d4c79958d43abde84a3e5bbeb4f8c757c164a49d3ec8432be6d36f16 alpine-standard-3.23.3-x86_64.iso" | sha256sum -c || rm -f alpine-standard-3.23.3-x86_64.iso
qemu-system-x86_64 \
    -cdrom alpine-standard-3.23.3-x86_64.iso \
    -m 512 -boot d --enable-kvm \
    -netdev user,id=net0 -device virtio-net-pci,netdev=net0
```

--------------------------------

### Install Kula on RHEL/Fedora/CentOS/Rocky/Alma

Source: https://github.com/c0m4r/kula/blob/main/README.md

Downloads and installs the .rpm package using rpm.

```bash
wget https://github.com/c0m4r/kula/releases/download/0.18.6/kula-0.18.6-x86_64.rpm
echo "89dc22ed3d58c74e6c3ce5dc24c52abdedd6be53549bab2998c644995ce4b8d4 kula-0.18.6-x86_64.rpm" | sha256sum -c || rm -f kula-0.18.6-x86_64.rpm
sudo rpm -i kula-0.18.6-x86_64.rpm
journalctl -f -t kula
```

--------------------------------

### Configure Snapd Environment

Source: https://github.com/c0m4r/kula/wiki/Snap

Post-installation setup required for snapd functionality.

```bash
sudo systemctl enable --now snapd.socket
sudo ln -s /var/lib/snapd/snap /snap     # so /snap/bin works
reboot # required
sudo snap install snapcraft --classic
sudo snap install lxd && sudo lxd init --auto
sudo usermod -aG lxd "$USER"   # re-login afterwards
```

--------------------------------

### Configure runit service

Source: https://github.com/c0m4r/kula/blob/main/docs/user/15-service-management.md

Install and link the runit service directory.

```bash
sudo cp -r addons/init/runit/kula /etc/sv/
sudo ln -s /etc/sv/kula /var/service/
```

--------------------------------

### Install local snap builds

Source: https://github.com/c0m4r/kula/wiki/Snap

Install unsigned snap packages using dangerous and devmode flags for initial testing or strict confinement verification.

```bash
# First a no-confinement smoke test — does the app even run?
sudo snap install dist/kula-*-amd64.snap --dangerous --devmode

# Then the real thing — strict confinement, exactly as users get it:
sudo snap remove --purge kula
sudo snap install dist/kula-*-amd64.snap --dangerous
```

--------------------------------

### Prepare Docker Integration

Source: https://github.com/c0m4r/kula/wiki/Prompts

Instructions for setting up Docker integration, including a Dockerfile, build script, and docker-compose example for host system monitoring.

```bash
prepare docker integration inside ./docker/ with Dockerfile, build.sh script, docker-compose.yml example to monitor host system
```

--------------------------------

### Install Kula on Alpine Linux

Source: https://github.com/c0m4r/kula/wiki/Alpine-Linux

Downloads, verifies, and installs the Kula binary, sets up the user/group, and configures the OpenRC service.

```bash
cd /opt
wget https://github.com/c0m4r/kula/releases/download/0.18.5/kula-0.18.5-amd64.tar.gz
echo "3f0a134eeb161486ef5151dc39b5ca181300da73a73fe09586c114eb56ae9c74 kula-0.18.5-amd64.tar.gz" | sha256sum -c || rm -f kula-0.18.5-amd64.tar.gz
tar -xvf kula-0.18.5-amd64.tar.gz
cd kula
adduser -DS kula
addgroup kula
cp kula /usr/bin/
mkdir -p /etc/kula /var/lib/kula
chown kula:kula /etc/kula /var/lib/kula /usr/bin/kula
cp config.example.yaml /etc/kula/config.yaml
cp init/openrc/kula /etc/init.d/
rc-update add kula
rc-service kula start
```

--------------------------------

### Start Kula Service

Source: https://github.com/c0m4r/kula/blob/main/docs/user/03-quick-start.md

Launches the default Kula service including the collector, storage engine, sandbox, and web server.

```bash
./kula
```

--------------------------------

### Configure systemd service

Source: https://github.com/c0m4r/kula/blob/main/docs/user/15-service-management.md

Install and enable the systemd unit file for Kula.

```bash
sudo cp addons/init/systemd/kula.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now kula
```

--------------------------------

### Run Void Linux ISO in QEMU

Source: https://github.com/c0m4r/kula/wiki/Void-Linux

Installs QEMU dependencies and launches the Void Linux ISO with KVM acceleration and virtio networking.

```bash
sudo pacman -S --needed qemu-system-x86 qemu-desktop
wget https://repo-default.voidlinux.org/live/current/void-live-x86_64-20250202-base.iso
echo "0f7439f500740f62dd18972cae448cec7d8a85032c7eb8f1bf946100d9a92161 void-live-x86_64-20250202-base.iso" | sha256sum -c || rm -f void-live-x86_64-20250202-base.iso
qemu-system-x86_64 \
    -cdrom void-live-x86_64-20250202-base.iso \
    -m 2048 -boot d --enable-kvm \
    -netdev user,id=net0 -device virtio-net-pci,netdev=net0
```

--------------------------------

### kula-scan Execution Examples

Source: https://github.com/c0m4r/kula/blob/main/cmd/kula-scan/README.md

Various command-line examples for performing different types of scans, including authenticated, targeted, and fuzzing operations.

```bash
# Quick non-destructive scan
kula-scan http://localhost:27960

# Full authenticated scan over TLS
kula-scan -username admin -password 'hunter2' https://mon.example.com

# Only header / traversal / CORS checks
kula-scan -only headers,traversal,cors http://10.0.0.5:27960

# Include disruptive checks (rate-limit + connection floods)
kula-scan -aggressive -username admin -password 'hunter2' http://localhost:27960

# Blind fault-injection fuzzing (reproducible with -seed)
kula-scan -fuzz -fuzz-iter 500 -username admin -password 'hunter2' http://localhost:27960
kula-scan -fuzz -seed 12345 -only fuzz http://localhost:27960   # replay a finding

# Machine-readable output for CI
kula-scan -json https://mon.example.com > report.json
```

--------------------------------

### Configure Keyring for Headless Environments

Source: https://github.com/c0m4r/kula/wiki/Snap

Installs and initializes a gnome-keyring daemon to allow interactive login on headless systems.

```bash
sudo apt update && sudo apt install -y gnome-keyring
dbus-run-session -- bash                 # sub-shell with a D-Bus session
  gnome-keyring-daemon --unlock <<< ''   # unlock with an empty password
  snapcraft login                        # now succeeds; stored in the keyring
  snapcraft upload --release=stable dist/kula-0.17.2-amd64.snap
```

--------------------------------

### Build and Run Docker Container

Source: https://github.com/c0m4r/kula/blob/main/README.md

Builds the Docker image and starts the services using Docker Compose.

```bash
./addons/docker/build.sh
docker compose -f addons/docker/docker-compose.yml up -d
```

--------------------------------

### Build Kula from Source

Source: https://github.com/c0m4r/kula/wiki/Kula-inside-chroot

Installs build dependencies and compiles Kula from the source repository.

```bash
export PATH="/root/go/bin:/bin:/usr/bin:/sbin:/usr/sbin"
cd /opt
apk add bash git go
git clone https://github.com/c0m4r/kula.git kula_source
cd kula_source
GO_VER=$(grep ^go go.mod | awk '{print $2}')
go install golang.org/dl/go${GO_VER}@latest
# build via alias
alias go='go${GO_VER}'
go download
go get -u ./...
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -buildvcs=false -o kula ./cmd/kula/
# or build via symlink
ln -s /root/go/bin/go${GO_VER} /root/go/bin/go
./addons/build.sh
# check
go install golang.org/x/vuln/cmd/govulncheck@latest
cd /root/go
wget -O- -nv https://golangci-lint.run/install.sh | sh -s v2.11.3
cd -
./addons/check.sh
```

--------------------------------

### Create system user

Source: https://github.com/c0m4r/kula/blob/main/docs/user/15-service-management.md

Create the unprivileged system user required for manual service setup.

```bash
sudo useradd --system --home-dir /var/lib/kula --shell /usr/sbin/nologin kula
```

--------------------------------

### Deploy Kula on Void Linux

Source: https://github.com/c0m4r/kula/wiki/Void-Linux

Downloads, verifies, and installs the Kula binary, sets up the service user, and enables the service via runit.

```bash
cd /opt
wget https://github.com/c0m4r/kula/releases/download/0.18.5/kula-0.18.5-amd64.tar.gz
echo "3f0a134eeb161486ef5151dc39b5ca181300da73a73fe09586c114eb56ae9c74 kula-0.18.5-amd64.tar.gz" | sha256sum -c || rm -f kula-0.18.5-amd64.tar.gz
tar -xvf kula-0.18.5-amd64.tar.gz
cd kula
useradd kula
cp kula /usr/bin/
mkdir -p /etc/kula /var/lib/kula
chown kula:kula /etc/kula /var/lib/kula /usr/bin/kula
cp config.example.yaml /etc/kula/config.yaml
cp -r init/runit/kula /etc/sv/
ln -s /etc/sv/kula /var/service
sv up kula
sv start kula
ss -ltup | grep kula
```

--------------------------------

### Install via standalone tarball

Source: https://github.com/c0m4r/kula/blob/main/docs/user/02-installation.md

Downloads, verifies, and extracts the Kula binary manually.

```bash
wget https://github.com/c0m4r/kula/releases/download/<version>/kula-<version>-amd64.tar.gz
echo "<sha256>  kula-<version>-amd64.tar.gz" | sha256sum -c || rm -f kula-<version>-amd64.tar.gz
tar -xvf kula-<version>-amd64.tar.gz
cd kula
./kula
```

--------------------------------

### Start Kula Web Server

Source: https://github.com/c0m4r/kula/wiki/Prompts

Launches the Kula monitoring tool with a web server. Access the dashboard via a web browser to verify charts, data updates, and interactive features.

```bash
./kula serve
```

--------------------------------

### Build Snap Package

Source: https://github.com/c0m4r/kula/blob/main/README.md

Installs required snapcraft dependencies and builds the snap package for host or cross-platform architectures.

```bash
snap install snapcraft --classic
snap install lxd
lxd init --auto
./addons/build_snap.sh            # host arch, into dist/
./addons/build_snap.sh cross      # cross-build amd64/arm64/riscv64 locally
ls -1 dist/kula-*.snap
```

--------------------------------

### Run Kula Server Mode

Source: https://github.com/c0m4r/kula/wiki/Prompts

Starts the Kula application in server mode, collecting and serving metrics. Requires a configuration file.

```bash
./kula --config=config.yaml serve
```

--------------------------------

### Install via AUR for Arch Linux

Source: https://github.com/c0m4r/kula/blob/main/docs/user/02-installation.md

Clones the AUR repository and builds the package locally.

```bash
git clone https://aur.archlinux.org/kula.git
cd kula
makepkg -si
```

--------------------------------

### Launch Terminal UI

Source: https://github.com/c0m4r/kula/blob/main/docs/user/03-quick-start.md

Starts the interactive terminal dashboard for real-time system monitoring.

```bash
./kula tui
```

--------------------------------

### Manage Kula as a Service

Source: https://github.com/c0m4r/kula/blob/main/README.md

Commands to install and enable Kula using systemd, OpenRC, or runit init systems.

```bash
# systemd
sudo cp addons/init/systemd/kula.service /etc/systemd/system/
sudo systemctl enable --now kula

# OpenRC
sudo cp addons/init/openrc/kula /etc/init.d/
sudo rc-update add kula default

# runit
sudo cp -r addons/init/runit/kula /etc/sv/
sudo ln -s /etc/sv/kula /var/service/
```

--------------------------------

### Install Kula Binary inside Chroot

Source: https://github.com/c0m4r/kula/wiki/Kula-inside-chroot

Downloads, verifies, and executes the Kula binary within the active chroot environment.

```bash
export PATH="/bin:/usr/bin"
cd /opt
mkdir kula
wget https://github.com/c0m4r/kula/releases/download/0.18.5/kula-0.18.5-amd64.tar.gz
echo "3f0a134eeb161486ef5151dc39b5ca181300da73a73fe09586c114eb56ae9c74 kula-0.18.5-amd64.tar.gz" | sha256sum -c || rm -f kula-0.18.5-amd64.tar.gz
tar -xvf kula-0.18.5-amd64.tar.gz
cd kula
chmod +x kula
./kula
```

--------------------------------

### Configure Listen Address and Port

Source: https://github.com/c0m4r/kula/blob/main/docs/user/03-quick-start.md

Overrides the default network settings using environment variables before starting the service.

```bash
export KULA_LISTEN="127.0.0.1"
export KULA_PORT="27960"
./kula
```

--------------------------------

### Poll and push metrics with a shell script

Source: https://github.com/c0m4r/kula/blob/main/docs/user/09-custom-metrics.md

A continuous loop example that reads system values and pushes them to the Kula socket.

```bash
SOCK=/var/lib/kula/kula.sock
while true; do
  rpm1=$(cat /sys/class/hwmon/hwmon0/fan1_input 2>/dev/null || echo 0)
  printf '{"custom":{"cpu_fans":[{"fan1":%s}]}}' "$rpm1" \
    | socat - UNIX-CONNECT:"$SOCK"
  sleep 1
done
```

--------------------------------

### Set Ollama Context Length and Serve

Source: https://github.com/c0m4r/kula/wiki/AI-assistant-with-Ollama

Configure Ollama to use a larger context length for better AI assistant performance and start the Ollama server. Ensure the specified model is pulled.

```bash
export OLLAMA_CONTEXT_LENGTH=32000
ollama serve
ollama pull gemma4:e4b
```

--------------------------------

### Add Init System Service Files

Source: https://github.com/c0m4r/kula/wiki/Prompts

Provide systemd, openrc, and runit service files for Kula in the ./addons/init/ directory.

```bash
add systemd service, openrc and runit files for kula in ./addons/init/
```

--------------------------------

### Set Environment Variables and Run Kula

Source: https://github.com/c0m4r/kula/wiki/Environment-variables

Demonstrates how to set environment variables like KULA_LOGLEVEL and KULA_PORT before executing the Kula binary.

```bash
export KULA_LOGLEVEL="debug"
export KULA_PORT=1234
./kula
```

--------------------------------

### Build the project

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/16-contributing.md

Execute the build script to compile the project.

```bash
./addons/build.sh
```

--------------------------------

### Secure Ansible Artifact Installation

Source: https://github.com/c0m4r/kula/blob/main/reviews/0.18.6/GPT-5.6-Terra-Max.md

Demonstrates using checksum verification for downloaded artifacts and installing packages without disabling GPG checks.

```yaml
- name: Fetch the reviewed Kula RPM
  ansible.builtin.get_url:
    url: "{{ kula_rpm_url }}"
    dest: /var/tmp/kula.rpm
    mode: "0644"
    checksum: "sha256:{{ kula_rpm_sha256 }}"

# Prefer a repository/package signature. Do not disable RPM verification.
- name: Install verified Kula package
  ansible.builtin.dnf:
    name: /var/tmp/kula.rpm
    state: present
```

--------------------------------

### Verify nvidia-smi installation

Source: https://github.com/c0m4r/kula/wiki/GPU-monitoring

If `nvidia-smi` is not found, ensure the NVIDIA driver is installed and the `nvidia-smi` executable is in your system's PATH. This command checks for its presence.

```bash
which nvidia-smi
```

```bash
nvidia-smi
```

--------------------------------

### Prepare Alpine Linux Chroot

Source: https://github.com/c0m4r/kula/wiki/Kula-inside-chroot

Downloads the Alpine mini root filesystem, mounts necessary system directories, and enters the chroot environment.

```bash
kula_cleanup() {
  sudo umount -l kula-alpine/proc
  sudo umount -l kula-alpine/dev
  unalias rm
  if [ $(ls -1 kula-alpine/dev | wc -l) -eq 0 ]; then rm -rfv kula-alpine/dev ; fi
  if [ $(ls -1 kula-alpine/proc | wc -l) -eq 0 ]; then rm -rfv kula-alpine/proc ; fi
  if [ $(mount | grep kula-alpine | wc -l) -eq 0 ]; then sudo rm -rf kula-alpine && echo done ; else echo "umount first" ; fi
}
if [ -d "kula-alpine/dev" ] || [ -d "kula-alpine/proc" ]; then
  echo "already exists, do a cleanup first" ; kula_cleanup
else
  if [ ! -e alpine-minirootfs-3.23.3-x86_64.tar.gz ]; then wget https://dl-cdn.alpinelinux.org/alpine/v3.23/releases/x86_64/alpine-minirootfs-3.23.3-x86_64.tar.gz ; fi
  mkdir kula-alpine
  tar -C kula-alpine -xvf alpine-minirootfs-3.23.3-x86_64.tar.gz
  alias rm='echo not yet'
  sudo mount -t proc none kula-alpine/proc
  sudo mount -o bind /dev kula-alpine/dev
  cp /etc/resolv.conf kula-alpine/etc/
  sudo chroot kula-alpine /bin/sh
fi
```

--------------------------------

### GET /health

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Checks the liveness of the server.

```APIDOC
## GET /health

### Description
Returns 200 if the system is healthy.

### Method
GET

### Endpoint
/health
```

--------------------------------

### GET /metrics

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Exposes Prometheus metrics.

```APIDOC
## GET /metrics

### Description
Prometheus exposition endpoint.

### Method
GET

### Endpoint
/metrics
```

--------------------------------

### GET /api/current

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Retrieves the latest sample data.

```APIDOC
## GET /api/current

### Description
Returns the latest Sample as JSON. Returns a 503 status if no data is available yet.

### Method
GET

### Endpoint
/api/current
```

--------------------------------

### GET /api/i18n

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Retrieves the translation map for a specific language.

```APIDOC
## GET /api/i18n

### Description
Returns the translation map for the requested language.

### Method
GET

### Endpoint
/api/i18n

### Parameters
#### Query Parameters
- **lang** (string) - Required - The language code to retrieve.
```

--------------------------------

### GET /api/config

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Retrieves the current UI and system configuration.

```APIDOC
## GET /api/config

### Description
Returns UI configuration including auth status, system info, theme, and custom metric definitions.

### Method
GET

### Endpoint
/api/config
```

--------------------------------

### GET /api/current

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Retrieves the latest sample data from the collector.

```APIDOC
## GET /api/current

### Description
Returns the latest sample data from the system collector.

### Method
GET

### Endpoint
/api/current
```

--------------------------------

### GET /api/history

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Retrieves historical data for a specified time range.

```APIDOC
## GET /api/history

### Description
Retrieves time-range history data.

### Method
GET

### Endpoint
/api/history
```

--------------------------------

### Run tests, fuzzing, and benchmarks

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/03-building.md

Commands to execute the test suite, storage benchmarks, and fuzz targets.

```bash
# Unit tests with the race detector
go test -race ./...

# Storage benchmark suite (default 3s per bench, pretty output)
./addons/benchmark.sh

# Fuzz targets
./addons/fuzz.sh
```

--------------------------------

### Build Arch Linux Package

Source: https://github.com/c0m4r/kula/blob/main/README.md

Generates an AUR package and installs it using makepkg.

```bash
./addons/build_aur.sh
cd dist/aur && makepkg -si
```

--------------------------------

### Initialize Void Linux ISO Environment

Source: https://github.com/c0m4r/kula/wiki/Void-Linux

Configures the shell environment, ensures network connectivity, and updates the XBPS package manager inside the live ISO.

```bash
bash
source /etc/skel/.bashrc
sleep 10
ip a s | grep glo || dhcpcd
xbps-install -y -u xbps
xbps-install -S wget
```

--------------------------------

### Build the Kula binary

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/03-building.md

Commands for creating development and production builds of the Kula binary.

```bash
# Dev build (~20 MB, with symbols)
CGO_ENABLED=0 go build -o kula ./cmd/kula/

# Production build (~14 MB, ~4 MB xz-compressed)
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -buildvcs=false -o kula ./cmd/kula/
```

--------------------------------

### GET /api/history

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/07-web-server-api.md

Retrieves historical sample data within a specified time range.

```APIDOC
## GET /api/history

### Description
Returns historical samples, tier, and resolution. The window is capped at 31 days.

### Method
GET

### Endpoint
/api/history

### Parameters
#### Query Parameters
- **from** (string) - Optional - RFC 3339 timestamp. Default: to - 5m.
- **to** (string) - Optional - RFC 3339 timestamp. Default: now.
- **points** (integer) - Optional - Desired data points. Default: 450, capped at 5000 (min 1).

### Response
#### Success Response (200)
- **samples** (array) - List of samples
- **tier** (string) - Data tier used
- **resolution** (string) - Data resolution
```

--------------------------------

### Iterate on snap builds

Source: https://github.com/c0m4r/kula/wiki/Snap

Use the snap try command to test changes directly from the primed directory without needing to repack the snap.

```bash
snapcraft prime
sudo snap try prime/
sudo snap remove --purge kula     # when done
```

--------------------------------

### Prometheus Scrape Configuration

Source: https://github.com/c0m4r/kula/blob/main/docs/user/11-prometheus.md

Example configuration for a Prometheus server to scrape an authenticated Kula instance.

```yaml
scrape_configs:
  - job_name: kula
    authorization:
      type: Bearer
      credentials: "a-long-random-secret"
    static_configs:
      - targets: ["server:27960"]
```

--------------------------------

### Enable authentication

Source: https://github.com/c0m4r/kula/wiki/Snap

Generate a password hash and update the configuration file to enable authentication.

```bash
sudo snap run kula hash-password         # copy the printed hash
sudo nano /var/snap/kula/current/config.yaml   # paste under web.auth
sudo snap restart kula.daemon
```

--------------------------------

### Build Debian/Ubuntu Package

Source: https://github.com/c0m4r/kula/blob/main/README.md

Generates a .deb package and lists the output file.

```bash
./addons/build_deb.sh
ls -1 dist/kula-*.deb
```

--------------------------------

### Example Locale JSON Structure

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/11-i18n.md

Format for individual locale files, mapping keys to translated strings.

```json
{
  "sign_in": "Sign In",
  "username": "Username",
  "cpu": "CPU",
  "load_avg": "Load Avg (1m)",
  ...
}
```

--------------------------------

### Initialize and Use Translator

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/11-i18n.md

Create a new translator instance and retrieve a translated string with English fallback.

```go
t := i18n.NewTranslator(lang)   // "" → auto-detect via DetectLang()
s := t.Get("sign_in")           // returns the translation, English fallback
```

--------------------------------

### Prometheus Configuration without Token

Source: https://github.com/c0m4r/kula/wiki/Prometheus-metrics

Example `prometheus.yml` to scrape metrics from Kula when no authentication token is configured.

```yaml
scrape_configs:
  - job_name: kula
    static_configs:
      - targets: ["localhost:27960"]
```

--------------------------------

### Build Snap Artifacts

Source: https://github.com/c0m4r/kula/wiki/Snap

Commands to build the project snap for different architectures and environments.

```bash
./addons/build_snap.sh            # current host architecture
./addons/build_snap.sh cross      # cross-build amd64 + arm64 + riscv64 locally
./addons/build_snap.sh --remote   # native per-arch builds on Launchpad
./addons/build_snap.sh --help
```

--------------------------------

### Decoder Skip Logic Example

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/06-storage-codec.md

Conceptual representation of how the decoder skips sections when a flag bit is set to false.

```text
decodeVariable(hasApps=true, hasApache2=false, ...):
  nginx:       read 1 byte  → done
  containers:  read 2 bytes → done
  postgres:    read 1 byte  → done
  mysql:       read 1 byte  → done
  apache2:     flag FALSE → skip this section entirely   ← stays aligned
  custom:      read 2 bytes + groups → done
```

--------------------------------

### Define Configuration Structures

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/14-adding-metrics.md

Add the new metric configuration to the application configuration file.

```go
type FooConfig struct {
    Enabled   bool   `yaml:"enabled"`
    StatusURL string `yaml:"status_url"`
}

type ApplicationsConfig struct {
    // ...existing fields...
    Foo FooConfig `yaml:"foo"`
}
```

--------------------------------

### Connect Snap Interfaces

Source: https://github.com/c0m4r/kula/wiki/Snap

Manually grant access to system resources by connecting specific interfaces.

```bash
sudo snap connect kula:system-observe
```

```bash
sudo snap connect kula:hardware-observe
```

```bash
sudo snap connect kula:mount-observe
```

```bash
sudo snap connect kula:network-observe
```

```bash
sudo snap connect kula:docker
```

--------------------------------

### Run Tests and Benchmarks

Source: https://github.com/c0m4r/kula/blob/main/README.md

Commands for executing unit tests with race detection, running storage benchmarks, and linting Python scripts.

```bash
# Run unit tests with race detector
go test -race ./...

# Run the full storage benchmark suite (default: 3s per bench)
./addons/benchmark.sh

# Python scripts formatter and linters
black addons/*.py
pylint addons/*.py
mypy --strict addons/*.py
```

--------------------------------

### Register and Upload Snap Packages

Source: https://github.com/c0m4r/kula/wiki/Snap

Commands to register a snap name and upload specific architecture builds to the stable channel.

```bash
# One-time: claim the name (needs to be authenticated — see the next section)
snapcraft register kula

# Upload each architecture and release it to a channel
snapcraft upload --release=stable dist/kula-0.17.2-amd64.snap
snapcraft upload --release=stable dist/kula-0.17.2-arm64.snap
snapcraft upload --release=stable dist/kula-0.17.2-riscv64.snap
```

--------------------------------

### Package the project

Source: https://github.com/c0m4r/kula/blob/main/docs/dev/03-building.md

Commands to build various distribution and container packages.

```bash
./addons/build_deb.sh      # → dist/kula-*.deb
./addons/build_rpm.sh      # → dist/kula-*.rpm
./addons/build_aur.sh      # → dist/aur (then makepkg -si)
./addons/build_snap.sh     # → dist/kula-*.snap (needs snapcraft + LXD)
./addons/docker/build.sh   # Docker image
```

--------------------------------

### Configure Alpine ISO Environment

Source: https://github.com/c0m4r/kula/wiki/Alpine-Linux

Updates package repositories and installs essential utilities inside the running Alpine ISO environment.

```bash
echo "http://dl-cdn.alpinelinux.org/alpine/v3.23/main" >> /etc/apk/repositories
echo "http://dl-cdn.alpinelinux.org/alpine/v3.23/community" >> /etc/apk/repositories
setup-interfaces
ip link set eth0 up
udhcpc
apk update
apk add git curl wget bash
```