### Daemon Configuration Example

Source: https://github.com/borgbase/vykar/blob/main/docs/src/daemon.md

Example YAML configuration for the Vykar daemon's scheduling.

```yaml
schedule:
  enabled: true
  every: "6h"                  # fixed interval
  # cron: "0 3 * * *"         # OR 5-field cron (mutually exclusive with every)
  on_startup: false
  jitter_seconds: 0
```

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

### Minimal Configuration Example for Windows

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

This example shows a minimal Vykar configuration using Windows-style paths. Note the use of single quotes for paths containing backslashes.

```yaml
repositories:
  - url: 'D:\Backups\repo'

sources:
  - 'C:\Users\me\Documents'
```

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

### Enable and Start Vykar systemd Service

Source: https://github.com/borgbase/vykar/blob/main/docs/src/daemon.md

Commands to reload systemd, enable the Vykar service to start on boot, and start it immediately.

```bash
systemctl daemon-reload
systemctl enable --now vykar

```

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

### Start Vykar Server

Source: https://github.com/borgbase/vykar/blob/main/docs/src/server-setup.md

Start the Vykar server with specified data directory, append-only mode, and storage quota. Ensure the VYKAR_TOKEN environment variable is set.

```bash
export VYKAR_TOKEN="some-secret-token"
vykar-server --data-dir /var/lib/vykar --append-only --quota 10G
```

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

### Minimal Configuration Example

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

A basic configuration requires at least repositories and sources defined. Encryption defaults to 'auto'.

```yaml
repositories:
  - url: "/backup/repo"

sources:
  - "/home/user/documents"
```

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

### Install libxdo for Vykar GUI on Debian/Ubuntu

Source: https://github.com/borgbase/vykar/blob/main/docs/src/gui.md

Install the libxdo3 library, which is a system dependency for the bare `vykar-gui` binary on Debian/Ubuntu systems.

```bash
sudo apt install libxdo3
```

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

### Install Vykar via curl

Source: https://github.com/borgbase/vykar/blob/main/README.md

Installs Vykar using a shell script from the official website. This is a quick way to get started.

```bash
curl -fsSL https://vykar.borgbase.com/install.sh | sh
```

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

### Start Daemon with HTTP Status Page

Source: https://github.com/borgbase/vykar/blob/main/docs/src/daemon.md

Starts the Vykar daemon and enables the read-only HTTP status page on a specified address.

```bash
vykar daemon --http-listen 127.0.0.1:7575
```

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

### Pack File Configuration Example

Source: https://github.com/borgbase/vykar/blob/main/docs/src/architecture.md

Illustrates the configuration for setting minimum and maximum pack file sizes in MiB for repositories. These values control the dynamic sizing of data packs.

```yaml
repositories:
  - url: /backups/repo
    min_pack_size: 33554432     # 32 MiB (floor, default)
    max_pack_size: 201326592    # 192 MiB (default)
```

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

### Install Git Hooks with Prek

Source: https://github.com/borgbase/vykar/blob/main/CONTRIBUTING.md

Install the project's Git hooks using the prek tool. This ensures code quality checks are performed automatically.

```bash
prek install
```

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

### Install cargo-fuzz and Nightly Toolchain

Source: https://github.com/borgbase/vykar/blob/main/fuzz/README.md

Prerequisites for local fuzzing. Ensure you have cargo-fuzz installed and a nightly Rust toolchain available.

```bash
cargo install cargo-fuzz
rustup toolchain install nightly
```

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

### Basic Repository and Source Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/goals.md

Defines the repository URL and paths to be backed up. This is the minimum configuration required to start using Vykar.

```yaml
repositories:
  - url: /backups/myrepo
sources:
  - path: /home/user/documents
  - path: /home/user/photos
```

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

### Run Vykar GUI AppImage on Linux

Source: https://github.com/borgbase/vykar/blob/main/docs/src/gui.md

Make the AppImage executable and run it. This is the primary method for installing the GUI on Linux.

```bash
chmod +x vykar-gui-*-x86_64.AppImage
./vykar-gui-*-x86_64.AppImage
```

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

### Client Configuration for RestBackend

Source: https://github.com/borgbase/vykar/blob/main/docs/src/server-internals.md

Example client configuration for connecting to a remote repository using the RestBackend. Ensure the 'access_token' is kept secure.

```yaml
repositories:
  - label: server
    url: https://backup.example.com
    access_token: "secret-token-here"
```

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

### Example .db.env File Content

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Illustrates the format of a `.db.env` file, which can contain key-value pairs, exported variables, and quoted values.

```dotenv
DB_USER=myuser
DB_PASSWORD=s3cret
DB_DATABASE=myapp
```

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

### Example Hook Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

This snippet shows how to configure 'failed' and 'after_backup' hooks. The 'failed' hook sends a notification with error details, while the 'after_backup' hook logs a success message.

```yaml
hooks:
  failed:
    - 'notify-send "vykar {command} failed: {error}"'
  after_backup:
    - 'echo "Backed up {source_label} to {repository}"'
```

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

### Verify Vykar Installation

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Checks if the Vykar installation was successful by displaying the installed version.

```bash
vykar --version
```

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

### Start Daemon with Public HTTP Access

Source: https://github.com/borgbase/vykar/blob/main/docs/src/daemon.md

Starts the Vykar daemon with HTTP status page accessible on a public interface, requiring explicit permission.

```bash
vykar daemon --http-listen 0.0.0.0:7575 --http-allow-public
```

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

### Install Vykar Binary on Linux/macOS

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Extracts the Vykar archive and copies the binary to a system-wide location for Linux and macOS.

```bash
# Example for Linux/macOS
tar xzf vykar-*.tar.gz
sudo cp vykar /usr/local/bin/
```

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

### Install Vykar Binary on Windows

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Extracts the Vykar zip archive and moves the executable to the user's bin directory on Windows.

```powershell
Expand-Archive vykar-*.zip -DestinationPath .
Move-Item .\vykar.exe "$env:USERPROFILE\bin\vykar.exe"
```

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

### Build Vykar GUI from Source on Linux

Source: https://github.com/borgbase/vykar/blob/main/docs/src/gui.md

Install necessary development headers and build the GUI from source using Cargo. This is for developers who need to compile the GUI themselves.

```bash
sudo apt install libxdo-dev libgtk-3-dev libxkbcommon-dev libayatana-appindicator3-dev
cargo build --release -p vykar-gui
```

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

### Install FUSE 2 for AppImage on Linux

Source: https://github.com/borgbase/vykar/blob/main/docs/src/gui.md

Install the FUSE 2 library if you encounter FUSE-related errors when running the AppImage. This command is for Debian/Ubuntu-based systems.

```bash
sudo apt install libfuse2t64
```

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

### Ansible Role Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Example of how to configure the `vykar` Ansible role with repository, encryption, sources, and schedule settings.

```yaml
- hosts: myserver
  roles:
    - role: vykar
      vars:
        vykar_config:
          repositories:
            - url: "/backup/repo"
          encryption:
            passphrase: "mysuperduperpassword"
          sources:
            - "/home"
            - "/etc"
          schedule:
            enabled: true
            every: "24h"
```

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

### Dockerfile to Extend Vykar Image

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Example Dockerfile to extend the base Vykar image with additional tools like SQLite.

```dockerfile
FROM ghcr.io/borgbase/vykar
RUN apk add --no-cache sqlite
```

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

### Docker Compose Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Example Docker Compose configuration for running Vykar. This includes service definition, environment variables, and volume mounts.

```yaml
services:
  vykar:
    image: ghcr.io/borgbase/vykar:latest
    hostname: my-server
    restart: unless-stopped
    environment:
      - VYKAR_PASSPHRASE
      - TZ=UTC
    volumes:
      - ./vykar.yaml:/etc/vykar/config.yaml:ro
      - /home/user/documents:/data/documents:ro
      - vykar-cache:/cache
volumes:
  vykar-cache:
```

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

### Run Vykar Daemon in Docker

Source: https://github.com/borgbase/vykar/blob/main/docs/src/daemon.md

Example command to run the Vykar daemon in a Docker container, exposing the status page and mounting configuration.

```bash
docker run -d --name vykar-daemon \
  -p 7575:7575 \
  -e VYKAR_HTTP_LISTEN=0.0.0.0:7575 \
  -e VYKAR_HTTP_ALLOW_PUBLIC=1 \
  -v /etc/vykar:/etc/vykar:ro \
  vykar

```

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

### Schedule Configuration with Interval

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Enables scheduled backups to run every 6 hours, starting immediately on daemon startup. This configuration uses the 'every' field for interval-based scheduling.

```yaml
schedule:
  enabled: true
  every: "6h"
  on_startup: true
```

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

### Perform First Backup and List Files

Source: https://github.com/borgbase/vykar/blob/main/docs/src/init-setup.md

Run an initial backup and then list the files in the repository to verify the backup process.

```bash
vykar backup
vykar list
```

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

### Initialize Repository

Source: https://github.com/borgbase/vykar/blob/main/docs/src/init-setup.md

Create the repository structure at the configured URL. You will be prompted for a passphrase if encryption is enabled.

```bash
vykar init
```

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

### Generate Default Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/init-setup.md

Use this command to create a starter configuration file for vykar.

```bash
vykar config
```

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

### Run Comparative Benchmark

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Initiates a comparative benchmark harness, comparing Vykar with other tools. Local repositories are created under /mnt/repos.

```bash
uv run --project scripts/testbench benchmark --runs 3
```

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

### Basic Vykar CLI Commands

Source: https://github.com/borgbase/vykar/blob/main/README.md

Demonstrates essential Vykar commands for configuration, initialization, backup, and listing snapshots. Ensure you have generated and edited the config file first.

```bash
# Generate a starter config and edit it
vykar config

# Initialize the repository and run a backup
vykar init
vykar backup

# List snapshots
vykar list
```

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

### Configure Repositories and Sources

Source: https://github.com/borgbase/vykar/blob/main/docs/src/init-setup.md

Define repository URLs and the directories to be backed up in the configuration file.

```yaml
repositories:
  - label: "main"
    url: "/backup/repo"

sources:
  - "/home/user/documents"
  - "/home/user/photos"
```

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

### Build Vykar from Source

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Clones the Vykar repository, navigates into the directory, and builds the release binary using Cargo.

```bash
git clone https://github.com/borgbase/vykar.git
cd vykar
cargo build --release
```

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

### Loading .env Files for Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Shows how to load environment variables from one or more `.env` files before configuration parsing. This is useful for managing credentials and settings.

```yaml
env_file: .db.env
# or multiple files:
# env_file:
#   - .db.env
#   - .app.env

repositories:
  - url: /backup/repo

sources:
  - label: databases
    command_dumps:
      - name: db.sql
        command: "mysqldump -u '${DB_USER}' -p'${DB_PASSWORD}' '${DB_DATABASE}'"
```

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

### Initialize Specific Repository

Source: https://github.com/borgbase/vykar/blob/main/docs/src/init-setup.md

If your configuration includes multiple repositories, use this command to initialize a single entry by its label.

```bash
vykar init --repo main
```

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

### Manage Vykar Systemd Service

Source: https://github.com/borgbase/vykar/blob/main/docs/src/server-setup.md

Commands to reload the systemd daemon, enable and start the Vykar server service, and check its status.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now vykar-server.service
sudo systemctl status vykar-server.service
```

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

### VM Disk Image Backup with Filesystem Freeze

Source: https://github.com/borgbase/vykar/blob/main/docs/src/recipes.md

Back up virtual machine disk images using Vykar, with hooks to freeze and thaw the guest filesystem via QEMU guest agent.

```yaml
sources:
  - label: vm-images
    path: /var/lib/libvirt/images
    hooks:
      before: >
        echo '{"execute":"guest-fsfreeze-freeze"}' |
        socat - unix-connect:/tmp/qga.sock
      finally: >
        echo '{"execute":"guest-fsfreeze-thaw"}' |
        socat - unix-connect:/tmp/qga.sock
```

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

### Build and Test Vykar Project

Source: https://github.com/borgbase/vykar/blob/main/CONTRIBUTING.md

Use these commands to build the project in release mode, run tests, and perform pre-commit checks including formatting, linting, and documentation checks.

```bash
cargo build --release
cargo test
make pre-commit          # fmt-check + clippy + doc-check + tests
```

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

### Configure simple sources

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Define backup sources as a list of paths. Multiple simple string entries are grouped into a single source and snapshot.

```yaml
sources:
  - /home/user/documents
  - /home/user/photos
```

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

### Simple Source Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Define backup sources using a list of filesystem paths. Multiple paths are grouped into a single source labeled 'default'.

```yaml
sources:
  - "/home/user/documents"
  - "/home/user/photos"
  # Windows:
  # - 'C:\Users\me\Documents'
  # - 'C:\Users\me\Photos'
```

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

### Backup Docker Volume with Downtime

Source: https://github.com/borgbase/vykar/blob/main/docs/src/recipes.md

Backs up a Docker volume by stopping the container before backup and starting it afterward, suitable for applications that write to the volume and can tolerate brief downtime.

```yaml
sources:
  - label: wiki
    path: /var/lib/docker/volumes/wiki_data/_data
    hooks:
      before: "docker stop wiki"
      finally: "docker start wiki"
```

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

### Session Marker JSON Structure

Source: https://github.com/borgbase/vykar/blob/main/docs/src/architecture.md

Example structure of a session marker JSON file used for concurrent backup uploads. This marker is written to `sessions/<session_id>.json`.

```json
{
  "hostname": "example.com",
  "pid": 12345,
  "registered_at": "2023-10-27T10:00:00Z",
  "last_refresh": "2023-10-27T10:15:00Z"
}
```

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

### Configure Vykar Systemd Environment

Source: https://github.com/borgbase/vykar/blob/main/docs/src/server-setup.md

Create and secure an environment file for the Vykar systemd service, containing the authentication token. This file should have restricted permissions.

```bash
sudo mkdir -p /etc/vykar
echo 'VYKAR_TOKEN=some-secret-token' | sudo tee /etc/vykar/vykar-server.env
sudo chmod 600 /etc/vykar/vykar-server.env
sudo chown vykar:vykar /etc/vykar/vykar-server.env
```

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

### Run Churn Scenario with Local Backend

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Executes a 5x churn scenario with a local backend and specifies the number of runs.

```bash
uv run --project scripts/testbench scenario scripts/scenarios/5xchurn.yaml --backend local --runs 3
```

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

### List all snapshots

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Display a list of all available snapshots.

```bash
# List all snapshots
vykar list
```

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

### Allowing Insecure HTTP for Remote Repositories

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

When using remote repositories with HTTP, set `allow_insecure_http: true` to permit plaintext transport. This is often used for local or development setups.

```yaml
repositories:
  - url: "http://localhost:8484"
    allow_insecure_http: true
```

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

### Listing and Restoring Snapshots by Label

Source: https://github.com/borgbase/vykar/blob/main/docs/src/goals.md

Demonstrates listing recent snapshots for a specific source label and restoring the latest snapshot for another label.

```bash
vykar list -S databases --last 5
```

```bash
vykar restore --source personal latest
```

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

### Storage Object Routes

Source: https://github.com/borgbase/vykar/blob/main/docs/src/server-internals.md

These endpoints provide standard CRUD operations for storage objects, allowing clients to get, check existence, put, delete, list, and create directories for objects within the repository.

```APIDOC
## GET /{path}

### Description
Retrieves a storage object.

### Method
GET

### Endpoint
`/{*path}`

### Parameters
#### Query Parameters
- **list** (boolean) - Optional - If present, lists objects matching the prefix.

#### Request Headers
- **Range** (string) - Optional - For ranged reads, returns `206`.

### Response
#### Success Response (200)
- Body: The content of the storage object.
#### Success Response (206)
- Body: The content of the storage object within the specified range.
#### Not Found Response (404)
- Indicates the object does not exist.
```

```APIDOC
## HEAD /{path}

### Description
Checks for the existence of a storage object and retrieves its metadata.

### Method
HEAD

### Endpoint
`/{*path}`

### Response
#### Success Response (200)
- Headers: Metadata about the object.
#### Not Found Response (404)
- Indicates the object does not exist.
```

```APIDOC
## PUT /{path}

### Description
Uploads or updates a storage object.

### Method
PUT

### Endpoint
`/{*path}`

### Parameters
#### Request Body
- **data** (bytes) - Required - The raw bytes of the object.

#### Request Headers
- **X-Content-BLAKE2b** (string) - Required - The BLAKE2b hash of the content for verification.

### Response
#### Success Response (200)
- Indicates the object was successfully written.
#### Forbidden Response (403)
- Returned if the server is in append-only mode and the key is not on the mutable-allowlist.
```

```APIDOC
## DELETE /{path}

### Description
Deletes a storage object.

### Method
DELETE

### Endpoint
`/{*path}`

### Response
#### Success Response (204)
- Indicates the object was successfully deleted.
#### Not Found Response (404)
- Indicates the object does not exist.
#### Forbidden Response (403)
- Returned if the server is in append-only mode.
```

```APIDOC
## POST /{path}?mkdir

### Description
Creates directory scaffolding for a given path.

### Method
POST

### Endpoint
`/{*path}?mkdir`

### Response
#### Success Response (200)
- Indicates the directory scaffolding was created.
```

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

### Listing All Backups

Source: https://github.com/borgbase/vykar/blob/main/docs/src/goals.md

Displays a list of all available backups.

```bash
vykar list
```

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

### Set Default Object Lock Retention Policy

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backends.md

Configure a default retention rule for the bucket. This example sets a GOVERNANCE mode with a 30-day retention period, allowing users with specific permissions to bypass retention if necessary.

```bash
# Set a default retention policy (GOVERNANCE mode, 30-day retention)
aws s3api put-object-lock-configuration \
  --bucket my-backup-bucket \
  --object-lock-configuration '{ 
    "ObjectLockEnabled": "Enabled", 
    "Rule": { 
      "DefaultRetention": { 
        "Mode": "GOVERNANCE", 
        "Days": 30 
      } 
    } 
  }'
```

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

### Run Simple Backup Scenario

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Executes a simple backup scenario using the YAML-driven end-to-end scenario runner.

```bash
uv run --project scripts/testbench scenario scripts/scenarios/simple-backup.yaml
```

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

### Profile Backup with Local Backend

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Uses the heaptrack/perf profiler wrapper to profile a backup operation with a local backend.

```bash
uv run --project scripts/testbench profile --mode backup --backend local
```

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

### Run and Log Pre-commit Checks

Source: https://github.com/borgbase/vykar/blob/main/AGENTS.md

Execute the `make pre-commit` command, which includes formatting, linting, documentation checks, and tests. Redirect all output to a log file for later inspection.

```bash
make pre-commit 2>&1 | tee /tmp/vykar-pre-commit.log
```

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

### Restore Pipeline Steps

Source: https://github.com/borgbase/vykar/blob/main/docs/src/architecture.md

Detailed textual description of the repository restore process, outlining each stage from opening the repository to restoring metadata.

```text
open repository without index (`open_without_index`)
  → resolve snapshot
  → try mmap restore cache (validated by index_generation)
  → load item stream:
    → preferred: lookup tree-pack chunk locations via restore cache
    → fallback: load full index and read item stream normally
  → stream-decode items in two passes:
    → pass 1 create directories
    → pass 2 create symlinks and plan file chunk writes
  → build coalesced pack read groups via the full index
  → parallel coalesced range reads by pack/offset
    (merge when gap <= 256 KiB and merged range <= 16 MiB)
    → `limits.connections` reader workers fetch groups, decrypt + decompress-with-size-hint chunks
    → validate plaintext size and write to all targets (max 16 open files per worker)
  → restore file metadata (mode, mtime, optional xattrs)
```

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

### Phase 1: Upload Process Details

Source: https://github.com/borgbase/vykar/blob/main/docs/src/architecture.md

Detailed textual description of the upload phase, covering session ID generation, session registration, repository opening, journal recovery, and file source walking with caching and pipelining strategies.

```text
generate session_id (128-bit random hex)
register_session() → write sessions/<session_id>.json, probe for active lock
open repo (full index loaded once)
begin_write_session(session_id) → journal key = sessions/<session_id>.index
  → prune stale local file-cache entries
  → recover own sessions/<session_id>.index if present (batch-verify packs, promote into dedup structures)
  → enable tiered dedup mode (mmap cache + xor filter, fallback to dedup HashMap)
  → derive upload/pipeline limits from `limits.connections` + `limits.threads`
  → execute `command_dumps` first:
    → stream each command's stdout directly into chunk storage
    → add virtual items under `vykar-dumps/` to the item stream
    → abort backup on non-zero exit or timeout
  → walk sources with excludes + one_file_system + exclude_if_present
    → cache-hit path: reuse cached ChunkRefs and bump refs
    → cache-miss path:
      → pipeline path (if effective worker threads > 1):
        → walk emits regular files and segmented large files
          (segmentation applies when file_size > 64 MiB;
           segment size is min(64 MiB, pipeline_buffer_bytes))
        → worker threads read/chunk/hash and classify each chunk:
          - xor prefilter says "maybe present" → hash-only chunk
          - xor prefilter miss (or no filter) → compress + encrypt prepacked chunk
        → sequential consumer validates segment order, performs dedup checks
          (persistent dedup tier + pending pack writers), commits new chunks,
          and handles xor false positives via inline transform
        → ByteBudget enforces pipeline_buffer_bytes as a hard in-flight memory cap
          (64 MiB × effective threads, clamped to 64 MiB..1 GiB)
      → sequential fallback path (effective worker threads == 1)
  → serialize items incrementally into item-stream chunks (tree packs)
  → pack SnapshotMeta in memory (do not write snapshots/<id> yet)
```

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

### Configure Compression Algorithm and Level

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Specify the compression algorithm and Zstd level. LZ4 is the default for speed, while Zstd offers better compression ratios.

```yaml
compression:
  algorithm: "zstd"
  zstd_level: 6
```

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

### Shell Expansion in Command Dumps

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Demonstrates sourcing a `.env` file directly within a command to perform shell-level variable expansion at runtime. This method works without `env_file` but may result in silent errors for missing variables.

```yaml
command_dumps:
  - name: db.sql
    command: ". /path/to/.db.env && mysqldump -u $DB_USER -p$DB_PASSWORD $DB_DATABASE"
```

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

### Environment Variable Expansion in Config

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Demonstrates using environment variable placeholders in configuration values. Supports `${VAR}` for required variables and `${VAR:-default}` for optional variables with a default value.

```yaml
repositories:
  - url: "${VYKAR_REPO_URL:-/backup/repo}"
    # access_token: "${VYKAR_ACCESS_TOKEN}"
```

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

### List snapshots for a specific source

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Display snapshots associated with the source labeled 'docs'.

```bash
# List snapshots for a specific source
vykar list --source docs
```

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

### Performing a Backup

Source: https://github.com/borgbase/vykar/blob/main/docs/src/goals.md

Initiates a backup operation.

```bash
vykar backup
```

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

### Combine Paths and Command Dumps in a Source

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Include command dumps in the same snapshot as filesystem paths by adding both to a single source entry.

```yaml
sources:
  - label: server
    paths:
      - /etc
      - /var/www
    command_dumps:
      - name: postgres.sql
        command: pg_dump -U myuser mydb
```

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

### Configure Multiple Backup Repositories

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Define multiple backup destinations by adding entries to the 'repositories' list. Each repository can override default settings for encryption, compression, retention, and limits.

```yaml
repositories:
  - label: "local"
    url: "/backups/local"

  - label: "remote"
    url: "s3://s3.us-east-1.amazonaws.com/bucket/remote"
    region: "us-east-1"
    access_key_id: "AKIA..."
    secret_access_key: "..."
    encryption:
      passcommand: "pass show vykar-remote"
    compression:
      algorithm: "zstd"             # Better ratio for remote
    retention:
      keep_daily: 30                 # Keep more on remote
    limits:
      connections: 2
      upload_mib_per_sec: 25
```

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

### Rich Source Configuration (Single Path)

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Configure a single source with a label, path, exclusion patterns, and retention policy. Each path entry creates its own snapshot.

```yaml
sources:
  - label: "docs"
    path: "/home/user/documents"
    exclude: ["*.tmp", ".cache/**"]
    # exclude_if_present: [".nobackup", "CACHEDIR.TAG"]
    # one_file_system: true
    # git_ignore: false
    repos: ["main"]                  # Only back up to this repo (default: all)
    retention:
      keep_daily: 7
    hooks:
      before: "echo starting docs backup"
```

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

### Local Filesystem Repository Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backends.md

Configure a repository to store backups on a local or mounted disk. No additional configuration beyond the URL is typically needed.

```yaml
repositories:
  - label: "local"
    url: "/backups/repo"
```

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

### Rich Source Configuration (Multiple Paths)

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Group multiple directories into a single source snapshot using the 'paths' key. An explicit 'label' is required for multi-path sources.

```yaml
sources:
  - label: "writing"
    paths:
      - "/home/user/documents"
      - "/home/user/notes"
    exclude: ["*.tmp"]
```

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

### Local Repository Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Configure a local directory as a backup repository. For Windows paths, use single quotes or no quotes to avoid YAML escape sequence issues.

```yaml
repositories:
  - label: "local"
    url: "/backups/repo"
    # Windows: url: 'D:\Backups\repo'
```

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

### Copy Built Binary to PATH

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Copies the compiled Vykar binary from the target release directory to a system PATH location.

```bash
cp target/release/vykar /usr/local/bin/
```

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

### Configure command dumps for database backups

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Define sources to capture the stdout of shell commands, such as database dumps, as virtual files within the snapshot. Requires an explicit label for the source.

```yaml
sources:
  - label: databases
    command_dumps:
      - name: postgres.sql
        command: pg_dump -U myuser mydb
      - name: redis.rdb
        command: redis-cli --rdb - 
```

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

### Database Backup Hook Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/goals.md

Configures hooks to run before and after a backup. The 'before' hook captures database output, and the 'after' hook cleans up temporary files.

```yaml
sources:
  - label: databases
    path: /var/backups/db
    hooks:
      before: "pg_dump -Fc mydb > /var/backups/db/mydb.dump"
      after:  "rm -f /var/backups/db/mydb.dump"
```

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

### Configure rich sources with labels and overrides

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Define backup sources with explicit labels for separate snapshots. Supports path grouping, exclude patterns, and pre-backup hooks.

```yaml
sources:
  - label: "photos"
    path: "/home/user/photos"
  - label: "docs"
    paths:
      - "/home/user/documents"
      - "/home/user/notes"
    exclude: ["*.tmp"]
    hooks:
      before: "echo starting docs backup"
```

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

### Target Specific Repository with CLI

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Use the --repo or -R flag to direct commands to a single repository when multiple are configured. This is useful for managing or inspecting individual backup destinations.

```bash
vykar list --repo local
```

```bash
vykar list -R /backups/local
```

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

### Run Stress Test with Local Backend

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Initiates the autonomous stress tester with a specified number of iterations and a local backend.

```bash
uv run --project scripts/testbench stress --iterations 100 --backend local
```

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

### Perform an ad-hoc backup with a label

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Create an ad-hoc backup of a specified path and assign it a label for later identification. The `--label` flag is only valid with explicit path arguments.

```bash
vykar backup --label before-upgrade /var/www
```

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

### Profile Backup with Perf and Skip Build

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Profiles a backup operation using the 'perf' profiler and skips the build process.

```bash
uv run --project scripts/testbench profile --mode backup --profiler perf --skip-build
```

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

### Enter Nix Development Shell

Source: https://github.com/borgbase/vykar/blob/main/CONTRIBUTING.md

For users of Nix with flakes, this command enters the development shell, providing a consistent development environment.

```bash
nix develop
```

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

### Validate Repository Creation

Source: https://github.com/borgbase/vykar/blob/main/docs/src/init-setup.md

Confirm that the repository has been successfully created by checking its information.

```bash
vykar info
```

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

### SQLite Database Backup with Hooks

Source: https://github.com/borgbase/vykar/blob/main/docs/src/recipes.md

Uses hooks to back up an SQLite database by creating a copy, as direct file copying while the database is running can lead to corruption.

```yaml
sources:
  - label: app-database
    path: /var/backups/sqlite
    hooks:
      before: >
        mkdir -p /var/backups/sqlite &&
        sqlite3 /var/lib/myapp/app.db ".backup '/var/backups/sqlite/app.db'"
      after: "rm -rf /var/backups/sqlite"
```

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

### Backup a specific source to a specific repository

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Perform a backup targeting the 'docs' source and the 'local' repository.

```bash
vykar backup --repo local --source docs
```

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

### Create Btrfs Snapshot Parent Directory

Source: https://github.com/borgbase/vykar/blob/main/docs/src/recipes.md

Ensure the parent directory for Btrfs snapshots exists before the first backup.

```bash
mkdir -p /mnt/.snapshots
```

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

### Compact Settings Configuration

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Set the threshold for triggering a repack operation based on the percentage of unused space. The default value is 20%.

```yaml
compact:
  threshold: 30
```

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

### Generate All Benchmark Reports

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Generates all benchmark charts for a given timestamped benchmark directory.

```bash
uv run --project scripts/testbench bench-report all ~/runtime/benchmarks/<STAMP>
```

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

### ZFS Filesystem Snapshot and Backup

Source: https://github.com/borgbase/vykar/blob/main/docs/src/recipes.md

Configure Vykar to back up ZFS filesystems by creating a snapshot before backup and destroying it afterwards.

```yaml
sources:
  - label: data
    path: /tank/data/.zfs/snapshot/vykar-tmp
    hooks:
      before: "zfs snapshot tank/data@vykar-tmp"
      after:  "zfs destroy tank/data@vykar-tmp"
```

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

### Trigger Immediate Backup in Docker

Source: https://github.com/borgbase/vykar/blob/main/docs/src/daemon.md

Command to send a USR1 signal to the Vykar container to trigger an immediate backup.

```bash
docker kill --signal=USR1 vykar-daemon
# or with Compose:
docker compose kill -s USR1 vykar

```

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

### Docker Run with Read-only Status Page

Source: https://github.com/borgbase/vykar/blob/main/docs/src/install.md

Run Vykar as a daemon and expose a read-only status page by setting environment variables and publishing the port.

```bash
docker run -d \
  --name vykar-daemon \
  -p 7575:7575 \
  -e VYKAR_HTTP_LISTEN=0.0.0.0:7575 \
  -e VYKAR_HTTP_ALLOW_PUBLIC=1 \
  -v /path/to/vykar.yaml:/etc/vykar/config.yaml:ro \
  -v vykar-cache:/cache \
  ghcr.io/borgbase/vykar
```

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

### Run Benchmark with Vykar Tool

Source: https://github.com/borgbase/vykar/blob/main/scripts/README.md

Runs a comparative benchmark specifically targeting the Vykar tool, specifying the number of runs.

```bash
uv run --project scripts/testbench benchmark --runs 5 --tool vykar
```

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

### Client Configuration (REST Backend)

Source: https://github.com/borgbase/vykar/blob/main/docs/src/server-setup.md

Configure Vykar clients to connect to a remote repository via REST. Includes repository URL, access token, encryption mode, and source directories.

```yaml
repositories:
  - label: "server"
    url: "https://backup.example.com"
    access_token: "some-secret-token"

encryption:
  mode: "auto"

sources:
  - "/home/user/documents"
```

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

### Restore Pipeline Flowchart

Source: https://github.com/borgbase/vykar/blob/main/docs/src/architecture.md

Visual representation of the steps involved in restoring a repository from a snapshot.

```mermaid
flowchart LR
    open["Open repo<br/>no index"] --> resolve["Resolve snapshot"]
    resolve --> cache{"Restore cache<br/>valid?"}
    cache -- yes --> items1["Load items<br/>via cache"]
    cache -- no --> items2["Load full index<br/>+ items"]
    items1 --> decode["Stream-decode<br/>two passes"]
    items2 --> decode
    decode --> plan["Plan coalesced<br/>read groups"]
    plan --> read["Parallel reads<br/>decrypt + write"]
    read --> meta["Restore metadata"]
```

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

### Schedule Configuration with Cron

Source: https://github.com/borgbase/vykar/blob/main/docs/src/configuration.md

Enables scheduled backups to run daily at 3:00 AM with a 60-second jitter. This configuration uses the 'cron' field for cron-based scheduling.

```yaml
schedule:
  enabled: true
  cron: "0 3 * * *"          # daily at 3:00 AM
  jitter_seconds: 60
```

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

### Mount Snapshots via WebDAV

Source: https://github.com/borgbase/vykar/blob/main/docs/src/restore.md

Makes snapshot contents accessible via a local read-only WebDAV server and a browser UI. Can serve all snapshots, a single snapshot, or filter by source, and allows custom listen addresses.

```bash
vykar mount
```

```bash
vykar mount --snapshot a1b2c3d4
```

```bash
vykar mount --source docs
```

```bash
vykar mount --address 127.0.0.1:9090
```

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

### Vykar Compact Algorithm Flowchart

Source: https://github.com/borgbase/vykar/blob/main/docs/src/architecture.md

Visual representation of the two main phases: Analysis and Repack. This flowchart illustrates the sequence of operations involved in the compacting process.

```mermaid
flowchart TB
    subgraph Phase1["Phase 1: Analysis (read-only)"]
        direction LR
        enum["Enumerate packs"] --> size["Query pack sizes"]
        size --> live["Compute live/dead bytes"]
        live --> filter["Filter by threshold"]
    end

    subgraph Phase2["Phase 2: Repack"]
        direction LR
        repack["Read live blobs"] --> write["Write new pack"]
        write --> save["Save index"]
        save --> delete["Delete old pack"]
    end

    Phase1 --> Phase2
```

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

### Generate Configuration to Specific Path

Source: https://github.com/borgbase/vykar/blob/main/docs/src/init-setup.md

Specify a destination path to save the vykar configuration file.

```bash
vykar config --dest ~/.config/vykar/config.yaml
```

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

### Backup a specific source by label

Source: https://github.com/borgbase/vykar/blob/main/docs/src/backup.md

Perform a backup targeting only the source labeled 'docs'.

```bash
vykar backup --source docs
```

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

### Phase 1: Upload Flowchart

Source: https://github.com/borgbase/vykar/blob/main/docs/src/architecture.md

Visual representation of the upload process in Vykar, showing the sequence of operations from session registration to staging snapshot metadata.

```mermaid
flowchart LR
    register["Register session"] --> recover["Recover journal"]
    recover --> upload["Upload packs"]
    upload --> journal["Refresh journal"]
    journal --> stage["Stage SnapshotMeta"]
```

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

### systemd Service Unit for Vykar

Source: https://github.com/borgbase/vykar/blob/main/docs/src/daemon.md

Create this unit file to manage the Vykar daemon as a systemd service. Ensure local repository paths are added to ReadWritePaths if used.

```ini
[Unit]
Description=Vykar Backup Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStartPre=+/bin/mkdir -p %h/.cache/vykar %h/.config/vykar
ExecStart=/usr/local/bin/vykar --config /etc/vykar/config.yaml daemon
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=60

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=%h/.cache/vykar %h/.config/vykar
# If backing up to a local path, add it here too, e.g.:
# ReadWritePaths=%h/.cache/vykar %h/.config/vykar /mnt/backup/vykar
PrivateTmp=true
PrivateDevices=true

# Passphrase via environment file (optional)
# EnvironmentFile=/etc/vykar/env

[Install]
WantedBy=multi-user.target

```