### Install Kula (Guided with Verification)

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

Downloads the installer, verifies its checksum, and then executes it. This method provides an extra layer of security.

```bash
KULA_INSTALL=$(mktemp)
curl -o ${KULA_INSTALL} -fsSL https://kula.ovh/install
echo "c70f6f070a1f93e278f07f7efb7d662a48bc16f43909df7889d8778430dde1b6 ${KULA_INSTALL}" | sha256sum -c || rm -f ${KULA_INSTALL}
bash ${KULA_INSTALL}
rm -f ${KULA_INSTALL}
```

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

### Setup QEMU Environment with Alpine ISO

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

Installs necessary QEMU packages and downloads the Alpine Linux ISO. Verifies the ISO integrity and then launches a QEMU instance with the specified ISO, memory, and network configuration.

```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
```

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

### Deploy Kula using OpenRC and Runit

Source: https://context7.com/c0m4r/kula/llms.txt

Provides commands to install and start Kula using OpenRC and runit init systems. Ensure the init scripts are copied to the correct locations.

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

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

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

### Kula Configuration File Example

Source: https://context7.com/c0m4r/kula/llms.txt

A comprehensive example of the `config.yaml` file, illustrating settings for global options, collection intervals, storage directories, web server configuration, and TUI preferences.

```yaml
# config.yaml — full example with all major sections

global:
  hostname: ""           # Override reported hostname (default: system hostname)
  show_system_info: true # Display OS/Kernel/Arch info in dashboard
  show_version: true     # Show Kula version in dashboard
  default_theme: auto    # light | dark | auto

collection:
  interval: 1s           # Allowed: 1s, 2s, 5s, 10s, 15s, 30s
  mounts_detection: auto # auto | host | self
  # devices: ["sda", "nvme0n1"]
  # interfaces: ["eth0", "wlan0"]

storage:
  directory: /var/lib/kula
  tiers:
    - resolution: 1s
      max_size: 250MB
    - resolution: 1m
      max_size: 150MB
    - resolution: 5m
      max_size: 50MB

web:
  enabled: true
  ui: true
  listen: ""           # "" = dual-stack; "[::1]" = IPv6 only; "127.0.0.1" = IPv4 only
  port: 27960
  enable_compression: true
  trust_proxy: false   # Set true when behind nginx/caddy to respect X-Forwarded-Proto
  join_metrics: false  # false = display gaps; true = connect data across gaps
  default_aggregation: max  # avg | min | max
  max_websocket_conns: 100
  max_websocket_conns_per_ip: 5
  lang:
    default: en
    force: false
  graphs:
    network:
      max_mode: "auto"   # off | on | auto
      max_value: 1000    # Mbps
    cpu_temp:
      max_mode: "off"
      max_value: 100
  logging:
    enabled: true
    level: "perf"        # access | perf | debug

tui:
  refresh_rate: 1s

```

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

### Install Kula on Alpine Linux

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

Follow these steps to download, verify, extract, and install Kula on an Alpine Linux system. This includes creating a user, setting up directories, copying configuration, and starting the service.

```bash
cd /opt
wget https://github.com/c0m4r/kula/releases/download/0.14.0/kula-0.14.0-amd64.tar.gz
echo "e2434759e6903a32f4cf27b9c6d97a11f2c33bf8c6e51f659e86683e77a97944 kula-0.14.0-amd64.tar.gz" | sha256sum -c || rm -f kula-0.14.0-amd64.tar.gz
tar -xvf kula-0.14.0-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

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

Starts the Kula service. The dashboard will be accessible at the default port.

```bash
./kula
```

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

### Start Kula Server

Source: https://context7.com/c0m4r/kula/llms.txt

Start Kula in its default mode, which includes the web server and background metric collection. You can also explicitly use the 'serve' subcommand or specify a configuration file.

```bash
./kula
```

```bash
./kula serve
```

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

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

### Enable and Start Kula Service with runit

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

Use these commands to copy the runit service directory and symlink it for activation.

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

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

### Enable and Start Kula Service with systemd

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

Use these commands to copy the systemd service file and enable/start the Kula service.

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

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

### Install Kula Application on Void Linux

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

Installs the 'kula' application by downloading, verifying, extracting, and configuring it. This includes setting up user accounts, system paths, and service management.

```bash
cd /opt
wget https://github.com/c0m4r/kula/releases/download/0.14.0/kula-0.14.0-amd64.tar.gz
echo "e2434759e6903a32f4cf27b9c6d97a11f2c33bf8c6e51f659e86683e77a97944 kula-0.14.0-amd64.tar.gz" | sha256sum -c || rm -f kula-0.14.0-amd64.tar.gz
tar -xvf kula-0.14.0-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 Kula using wget

Source: https://github.com/c0m4r/kula/blob/main/landing/index.html

Use this command to download and execute the Kula installation script with wget. Ensure you have execute permissions for the script.

```bash
bash -c "$(wget -qO- https://raw.githubusercontent.com/c0m4r/kula/refs/heads/main/addons/install.sh)"
```

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

### 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
```

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

### Start Kula with Custom Listen Address and Port

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

Starts Kula with custom network settings defined by environment variables. Useful for specific network configurations.

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

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

### Install Kula (.rpm)

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

Downloads and installs the Kula .rpm package for RHEL-based systems, followed by a command to view logs.

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

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

### Install Kula on Debian/Ubuntu

Source: https://context7.com/c0m4r/kula/llms.txt

Install Kula on Debian or Ubuntu systems using the provided .deb package.

```bash
wget https://github.com/c0m4r/kula/releases/download/0.15.0/kula-0.15.0-amd64.deb
sudo dpkg -i kula-0.15.0-amd64.deb
```

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

### Install Kula (Arch Linux AUR)

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

Clones the Kula AUR repository, builds, and installs the package. Requires `git` and `base-devel`.

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

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

### Install Kula (.deb)

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

Downloads and installs the Kula .deb package for Debian/Ubuntu systems, followed by a command to view logs.

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

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

### Build Kula from Source Inside Chroot

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

Instructions for building Kula from source within the chroot. This involves setting up the Go environment, cloning the repository, installing dependencies, and compiling the binary using `go build`. It also includes steps for installing auxiliary tools like golangci-lint and govulncheck.

```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
cd kula
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/go1.26.1 /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
```

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

### Enable and Start Kula Service with OpenRC

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

Use these commands to copy the OpenRC init script and add Kula to the default run level.

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

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

### Install Kula using curl

Source: https://github.com/c0m4r/kula/blob/main/landing/index.html

Use this command to download and execute the Kula installation script with curl. Ensure you have execute permissions for the script.

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

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

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

Source: https://context7.com/c0m4r/kula/llms.txt

Install Kula on RHEL-based systems using the provided .rpm package.

```bash
wget https://github.com/c0m4r/kula/releases/download/0.15.0/kula-0.15.0-x86_64.rpm
sudo rpm -i kula-0.15.0-x86_64.rpm
```

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

### Set Up QEMU Environment for Void Linux ISO Testing

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

Installs necessary QEMU packages and downloads a Void Linux ISO. It includes checksum verification and launches a QEMU virtual machine with the ISO as a bootable CD-ROM.

```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
```

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

### Deploy Kula using Systemd

Source: https://context7.com/c0m4r/kula/llms.txt

Installs and enables Kula as a systemd service for automatic startup and management. Requires root privileges for installation.

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

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

### Enable and Start NVIDIA Exporter Service

Source: https://context7.com/c0m4r/kula/llms.txt

Reload the systemd daemon, then enable and start the Kula NVIDIA exporter service. This makes the service active and ensures it runs on system startup.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now kula-nvidia-exporter
```

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

### Install Kula (Standalone amd64)

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

Downloads the amd64 tarball, verifies its checksum, extracts, and runs Kula. Suitable for direct deployment.

```bash
wget https://github.com/c0m4r/kula/releases/download/0.15.0/kula-0.15.0-amd64.tar.gz
echo "92a189984672566cc3f31deee22926c25fbbf6370ba361f9b326fe43010b5d60 kula-0.15.0-amd64.tar.gz" | sha256sum -c || rm -f kula-0.15.0-amd64.tar.gz
tar -xvf kula-0.15.0-amd64.tar.gz
cd kula
./kula
```

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

### Start Ollama with Extended Context

Source: https://context7.com/c0m4r/kula/llms.txt

Set the OLLAMA_CONTEXT_LENGTH environment variable to a sufficient value before starting the Ollama server. This is crucial for handling larger contexts required by AI models.

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

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

### Build and Run Kula with Docker Compose

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

Build the Docker image for Kula and start the services using Docker Compose.

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

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

### 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
```

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

### 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
```

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

### 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
```

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

### Check NVIDIA Driver and nvidia-smi Availability

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

Verify that the NVIDIA driver is installed and that the `nvidia-smi` command is accessible in your system's PATH.

```bash
which nvidia-smi && nvidia-smi --query-gpu=name --format=csv,noheader
```

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

### 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 Kula Arch Linux Package (AUR)

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

Build and install the Kula package from the AUR for Arch Linux and Manjaro.

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

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

### Configure Alpine Linux Inside QEMU

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

Commands to run inside the QEMU Alpine Linux environment to set up repositories, configure network interfaces, obtain an IP address, and install essential packages.

```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
```

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

### Manage systemd Service for NVIDIA Exporter

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

Commands to reload the systemd daemon, enable and start the `kula-nvidia-exporter` service, and check its status.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now kula-nvidia-exporter
sudo systemctl status kula-nvidia-exporter
```

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

### Create PKGBUILD for AUR

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

Script to generate a PKGBUILD for an AUR package for Arch Linux. This involves similar setup steps as the .deb package.

```bash
Create also a script that will make a PKGBUILD for AUR package for Arch Linux 
(it should create /etc/kula/config.example.yaml, use /var/lib/kula for data and also install bash completion script)
```

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

### 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
```

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

### Run and Debug Kula

Source: https://context7.com/c0m4r/kula/llms.txt

Start the Kula application. Use the KULA_LOGLEVEL environment variable to enable debug logging for troubleshooting Ollama communication issues.

```bash
./kula
```

```bash
KULA_LOGLEVEL=debug ./kula
```

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

### Install Kula using Standalone Tarball

Source: https://context7.com/c0m4r/kula/llms.txt

Download, verify, and extract the standalone tarball for Kula on amd64. After extraction, navigate to the directory and run the Kula binary. The dashboard will be available at http://localhost:27960.

```bash
wget https://github.com/c0m4r/kula/releases/download/0.15.0/kula-0.15.0-amd64.tar.gz
echo "92a189984672566cc3f31deee22926c25fbbf6370ba361f9b326fe43010b5d60 kula-0.15.0-amd64.tar.gz" | sha256sum -c
tar -xvf kula-0.15.0-amd64.tar.gz
cd kula && ./kula
```

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

### Prometheus Configuration with Bearer Token

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

Example `prometheus.yml` to scrape metrics from Kula when an authentication token is configured. Ensure `credentials` match the `token` in `config.yaml`.

```yaml
scrape_configs:
  - job_name: kula
    static_configs:
      - targets: ["localhost:27960"]
    authorization:
      type: Bearer
      credentials: "your-metrics-token"
```

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

### Install and Run Kula Inside Chroot

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

Commands to execute within the Alpine Linux chroot environment. This includes setting the PATH, downloading the Kula binary, verifying its integrity with sha256sum, extracting it, making it executable, and running it.

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

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

### 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 Kula from Source

Source: https://context7.com/c0m4r/kula/llms.txt

Clone the Kula repository and build the application from source using Go.

```bash
git clone https://github.com/c0m4r/kula.git && cd kula
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -buildvcs=false -o kula ./cmd/kula/
```

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

### Initialize and Update System Inside Void Linux ISO

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

Commands to run inside a QEMU-launched Void Linux ISO. It sources bashrc, waits, checks network configuration, and updates the package manager.

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

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

### Build Kula Addons

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

Run this script to build Kula addons.

```bash
./addonsh.build.sh
```

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

### Run Kula Storage Benchmark Suite

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

Execute the full storage benchmark suite. The default duration for each benchmark is 3 seconds.

```bash
./addons/benchmark.sh
```

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

### Build Kula RPM Package (.rpm)

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

Build an RPM package for Kula and list the generated .rpm files.

```bash
./addons/build_rpm.sh
ls -1 dist/kula-*.rpm
```

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

### Systemd Service for NVIDIA Exporter

Source: https://context7.com/c0m4r/kula/llms.txt

Configure a systemd service to run the NVIDIA exporter automatically. This ensures the exporter starts on boot and restarts if it fails.

```ini
# /etc/systemd/system/kula-nvidia-exporter.service
[Unit]
Description=Kula NVIDIA GPU Metrics Exporter
After=network.target

[Service]
Type=simple
ExecStart=/usr/share/kula/scripts/nvidia-exporter.sh /var/lib/kula 1
Restart=always
RestartSec=5
User=kula

[Install]
WantedBy=multi-user.target
```

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

### Prometheus Configuration for Scraping Kula (No Token)

Source: https://context7.com/c0m4r/kula/llms.txt

Example `prometheus.yml` configuration to scrape metrics from Kula without authentication. Assumes Kula is accessible at `myserver:27960`.

```yaml
# prometheus.yml — scrape without token
scrape_configs:
  - job_name: kula
    static_configs:
      - targets: ["myserver:27960"]
```

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

### Build Kula from Source

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

Clones the Kula repository and executes the build script. This is for compiling Kula from its source code.

```bash
git clone https://github.com/c0m4r/kula.git
cd kula
./addons/build.sh
```

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

### Landlock Sandbox Enforcement Log

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

This log entry shows an example of Landlock sandbox enforcement, detailing the paths and network access that are restricted or allowed.

```bash
2026/03/07 12:02:18 Landlock sandbox enforced (paths: /proc[ro] /sys[ro] /home/kula/config.yaml[ro] /var/lib/kula[rw], net: bind TCP/27960)
```

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

### Configuring Listen Addresses

Source: https://github.com/c0m4r/kula/wiki/Listening-IP:PORT-considerations

Demonstrates various ways to configure the listen address for dual-stack, IPv6-only, or IPv4-only listening.

```yaml
listen: ""           # Dual-stack, listening on all available v4 and v6 addresses (0.0.0.0 + [::])
```

```yaml
listen: "[::]"       # all v6 or v6/v4 (kernel decides based on net.ipv6.bindv6only)
```

```yaml
listen: "0.0.0.0"    # single tcp4 listener (v4 only)
```

```yaml
listen: "127.0.0.1"  # single tcp4 listener bound to that address (in this case v4 localhost)
```

```yaml
listen: "[::1]"      # single tcp6 listener bound to that address (in this case v6 localhost)
```

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

### Run Kula Lint and Test Suite

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

Execute the check script to lint and run the test suite for Kula.

```bash
./addons/check.sh
```

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

### Run NVIDIA Exporter as a Specific User

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

If Kula is installed via a package manager, run the exporter script as the same user Kula uses, typically 'kula'.

```bash
sudo -u kula "./scripts/nvidia-exporter.sh"
```

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

### Prepare Alpine Linux Chroot for Kula

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

This script prepares an Alpine Linux chroot environment. It handles cleanup of previous mounts, downloads the mini root filesystem if not present, extracts it, and sets up necessary mounts and network configuration before entering the chroot.

```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
```

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

### Docker Health Check Configuration

Source: https://context7.com/c0m4r/kula/llms.txt

Example Dockerfile `HEALTHCHECK` instruction to periodically check Kula's health endpoint. Ensures containers are running and responsive.

```dockerfile
# HEALTHCHECK --interval=30s --timeout=5s \
#   CMD curl -f http://localhost:27960/health || exit 1
```

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

### Get Configuration

Source: https://context7.com/c0m4r/kula/llms.txt

Retrieves the active dashboard configuration used by the frontend. This includes feature flags, graph settings, custom metric definitions, and Ollama status.

```APIDOC
## GET /api/config

### Description
Returns the active dashboard configuration used by the frontend, including feature flags, graph settings, custom metric definitions, and Ollama status.

### Method
GET

### Endpoint
/api/config

### Request Example
```bash
curl -s http://localhost:27960/api/config | jq .
```

### Response
#### Success Response (200)
- **auth_enabled** (boolean) - Indicates if authentication is enabled.
- **hostname** (string) - The hostname of the server.
- **os** (string) - The operating system distribution.
- **kernel** (string) - The kernel version.
- **arch** (string) - The system architecture.
- **version** (string) - The Kula version.
- **theme** (string) - The UI theme setting.
- **aggregation** (string) - The metric aggregation method.
- **join_metrics** (boolean) - Whether to join metrics.
- **ollama_enabled** (boolean) - Indicates if Ollama integration is enabled.
- **graphs** (object) - Configuration for various graphs.
- **lang** (object) - Language settings.

#### Response Example
```json
{
  "auth_enabled": false,
  "hostname": "myserver",
  "os": "Ubuntu 24.04",
  "kernel": "6.8.0-51-generic",
  "arch": "amd64",
  "version": "0.15.0",
  "theme": "auto",
  "aggregation": "max",
  "join_metrics": false,
  "ollama_enabled": false,
  "graphs": {
    "network": { "mode": "auto", "value": 1000, "auto": 1000 },
    "cpu_temp": { "mode": "off", "value": 100, "auto": 95 },
    "split": { "network": false, "disk_io": false, "gpu": false }
  },
  "lang": { "default": "en", "force": false }
}
```
```

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

### Get Current Metrics

Source: https://context7.com/c0m4r/kula/llms.txt

Retrieves the most recently collected metrics sample as a single JSON object. This endpoint provides a snapshot of all subsystem readings at a given moment.

```APIDOC
## GET /api/current

### Description
Returns the most recently collected metrics sample as a single JSON object with all subsystem readings.

### Method
GET

### Endpoint
/api/current

### Request Example
```bash
# No authentication
curl -s http://localhost:27960/api/current | jq .

# With session token (when auth is enabled)
curl -s -H "Authorization: Bearer <session-token>" \
  http://localhost:27960/api/current | jq '{ 
    cpu_pct: .cpu.pct,
    mem_used_mb: (.memory.used / 1048576 | round),
    net_rx_mbps: .network.rx_mbps,
    disk_read_bps: .disks[0].read_bytes_s,
    load_1m: .load_avg.load1,
    uptime_s: .system.uptime
  }'
```

### Response
#### Success Response (200)
- **cpu_pct** (number) - Percentage of CPU utilization.
- **mem_used_mb** (number) - Used memory in megabytes.
- **net_rx_mbps** (number) - Network receive rate in megabits per second.
- **disk_read_bps** (number) - Disk read rate in bytes per second.
- **load_1m** (number) - System load average for the last 1 minute.
- **uptime_s** (number) - System uptime in seconds.

#### Response Example
```json
{
  "cpu_pct": 14.3,
  "mem_used_mb": 3842,
  "net_rx_mbps": 1.24,
  "disk_read_bps": 204800,
  "load_1m": 0.87,
  "uptime_s": 864231
}
```
```

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

### Build Kula Production Binary

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

Build the optimized Kula binary for production. This results in a smaller binary size (~12MB, ~4MB compressed with xz).

```bash
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -buildvcs=false -o kula ./cmd/kula/
```

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

### Add Usage Message and Man Page

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

Enhancements for the binary's command-line interface, including a proper usage message for the --help flag and a man page for detailed documentation.

```bash
The binary is missing proper usage message when --help flag is provided
```

```bash
Add man page for the binary
```

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

### Create .deb Package Script

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

Script to generate a .deb package for Debian/Ubuntu systems. This includes setting up configuration files, data directories, and installing the bash completion script.

```bash
Create a script that will make .deb package for Debian/Ubuntu systems 
(it should create /etc/kula/config.example.yaml, use /var/lib/kula for data and also install bash completion script)
```

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

### Prometheus Configuration for Scraping Kula (With Bearer Token)

Source: https://context7.com/c0m4r/kula/llms.txt

Example `prometheus.yml` configuration to scrape metrics from Kula using a bearer token for authentication. Specifies the token in the `authorization` section.

```yaml
# prometheus.yml — scrape with bearer token
scrape_configs:
  - job_name: kula
    static_configs:
      - targets: ["myserver:27960"]
    authorization:
      type: Bearer
      credentials: "my-secret-token"
```

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

### Run Kula with Docker and Environment Variables

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

Shows how to pass environment variables to a Kula Docker container using the -e flag for runtime configuration.

```bash
docker run --rm -it \
  -e KULA_LOGLEVEL="debug" \
  -e KULA_PORT=1234 \
  --name kula --pid host --network host \
  -v /proc:/proc:ro c0m4r/kula:latest
```

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

### Build Kula Development Binary

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

Build the Kula binary for development. This results in a larger binary size (~17MB).

```bash
CGO_ENABLED=0 go build -o kula ./cmd/kula/
```

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

### Runtime Smoke Test for Kula Serve

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

Starts the Kula server in the background and performs a basic check by curling the API endpoint. Verifies that the API returns valid JSON data.

```bash
# Run collector and check output
./kula serve &
sleep 3
curl http://localhost:8080/api/current | python3 -m json.tool
# Should return valid JSON with CPU, memory, network data
kill %1
```

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

### Query Configuration via REST API

Source: https://context7.com/c0m4r/kula/llms.txt

Fetches the active dashboard configuration, including feature flags, graph settings, and Ollama status. Useful for understanding the current frontend setup.

```bash
curl -s http://localhost:27960/api/config | jq .
```

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

### Build Kula Executable

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

Compiles the Kula project into an executable binary. Ensure this command completes without errors.

```bash
go build -o kula ./cmd/kula/
```

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

### Verify Container Socket Discovery

Source: https://context7.com/c0m4r/kula/llms.txt

Check Kula's startup logs to confirm container monitoring is enabled and using socket discovery. This command filters the last 20 lines of the Kula service log for container-related messages.

```bash
# Verify socket discovery mode at Kula startup in logs
journalctl -u kula -n 20 | grep containers
# [containers] monitoring enabled (mode: socket)
# [containers] monitoring enabled (mode: cgroups)  # fallback if no socket
```

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

### Get Historical Metrics

Source: https://context7.com/c0m4r/kula/llms.txt

Queries historical metrics from the tiered ring-buffer storage for a specified time window. This endpoint automatically selects the appropriate storage tier and downsamples data points.

```APIDOC
## GET /api/history

### Description
Queries historical metrics from the tiered ring-buffer storage for a time window, automatically selecting the appropriate tier and downsampling to the requested number of data points.

### Method
GET

### Endpoint
/api/history

### Parameters
#### Query Parameters
- **from** (string) - Optional - The start of the time window in ISO 8601 format (e.g., `YYYY-MM-DDTHH:MM:SSZ`). Defaults to the earliest available data.
- **to** (string) - Optional - The end of the time window in ISO 8601 format (e.g., `YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time.
- **points** (integer) - Optional - The desired number of data points. Defaults to 450. Maximum is 5000.

### Request Example
```bash
# Last 5 minutes with 300 data points (default)
curl -s "http://localhost:27960/api/history" | jq '{ 
  tier: .tier,
  resolution: .resolution,
  sample_count: (.samples | length),
  first_ts: .samples[0].timestamp,
  last_cpu: .samples[-1].cpu.pct
}'

# Custom time range — last 1 hour with 200 points
curl -s "http://localhost:27960/api/history?\
from=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)\
&to=$(date -u +%Y-%m-%dT%H:%M:%SZ)\
&points=200" | jq '{ 
  tier: .tier,
  resolution: .resolution,
  count: (.samples | length)
}'
```

### Response
#### Success Response (200)
- **tier** (integer) - The storage tier used for the data.
- **resolution** (string) - The time resolution of the data points (e.g., "1m").
- **samples** (array) - An array of metric samples, each containing a timestamp and various readings.

#### Response Example
```json
{
  "tier": 2,
  "resolution": "1m",
  "count": 60
}
```

### Constraints
- Max time range: 31 days
- Max points: 5000
```

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

### Configure Kula NVIDIA Exporter as a systemd Service

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

Set up the `nvidia-exporter.sh` script to run as a systemd service for automatic startup and restarts.

```ini
[Unit]
Description=Kula NVIDIA GPU Metrics Exporter
After=network.target

[Service]
Type=simple
ExecStart=/usr/share/kula/scripts/nvidia-exporter.sh /var/lib/kula 1
Restart=always
RestartSec=5
User=kula

[Install]
WantedBy=multi-user.target
```

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

### Remove Kula exporter lock file

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

If Kula reports that another instance is already running, it might be due to a stale lock file. Remove the lock file to allow a new instance to start.

```bash
rm /var/lib/kula/nvidia-exporter.lock
```

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

### Build Kula Debian Package (.deb)

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

Build a Debian package for Kula and list the generated .deb files.

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

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

### Push Custom Metrics via Unix Socket (Python)

Source: https://context7.com/c0m4r/kula/llms.txt

Send JSON-formatted metrics to the Kula Unix socket using Python's socket library. This example pushes application latency metrics.

```python
# Push from Python
import socket, json, time

sock_path = "/var/lib/kula/kula.sock"
while True:
    data = json.dumps({"custom": {"app_latency": [{"p50_ms": 12}, {"p99_ms": 87}]}})
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
        s.connect(sock_path)
        s.sendall(data.encode())
    time.sleep(1)
```

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

### Run Kula (Docker - Temporary)

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

Runs Kula in a Docker container without persistent storage. Useful for quick testing.

```bash
docker run --rm -it --name kula --pid host --network host -v /proc:/proc:ro c0m4r/kula:latest
```

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

### Check Kula nvidia.log file

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

Verify that the exporter is running and writing to the correct directory by checking the existence and content of the `nvidia.log` file. The file's modification time should be recent.

```bash
ls -la /var/lib/kula/nvidia.log
```

```bash
cat /var/lib/kula/nvidia.log
```

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

### Advanced Nginx Configuration with Rate Limiting and WebSockets

Source: https://github.com/c0m4r/kula/wiki/Running-behind-reverse-proxy-(nginx)

An advanced Nginx setup for Kula that includes rate limiting for requests and connections, and dedicated handling for WebSocket connections. It also configures security headers and logging.

```nginx
# Nginx Configuration for Kula behind reverse proxy
# This configuration includes rate limiting, connection limits, and WebSocket support.

# 1. Define Rate Limiting Zones
# Limit requests: 10 requests per second with a burst of 20
limit_req_zone $binary_remote_addr zone=kula_req_limit:10m rate=10r/s;

# Limit connections: 5 simultaneous connections per IP
limit_conn_zone $binary_remote_addr zone=kula_conn_limit:10m;

upstream kula_backend {
    server 127.0.0.1:27960;
    keepalive 32;
}

server {
    listen 80;
    server_name kula.example.com; # Replace with your domain

    # Security Headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Content-Security-Policy "default-src 'self'; style-src 'self' fonts.googleapis.com; font-src fonts.gstatic.com; script-src 'self'; connect-src 'self' ws: wss:;" always;

    # Logging
    access_log /var/log/nginx/kula_access.log;
    error_log /var/log/nginx/kula_error.log;

    # Apply Connection Limits Globally for this Server
    limit_conn kula_conn_limit 5;
    limit_conn_status 429;

    location / {
        proxy_pass http[://]kula_backend; # Added [://] to avoid tool parsing issues
        proxy_http_version 1.1;
        
        # Standard Proxy Headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        # Rate Limiting
        limit_req zone=kula_req_limit burst=20 nodelay;
        limit_req_status 429;
    }

    # WebSocket Support for real-time updates
    location /ws {
        proxy_pass http[://]kula_backend;
        proxy_http_version 1.1;

        # WebSocket Upgrade Headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSockets need longer timeouts to keep the connection alive
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;

        # Tightened Rate Limiting for WebSocket Upgrades
        limit_req zone=kula_req_limit burst=5 nodelay;
    }
}
```