vykar.example.yaml

# vykar example configuration
# Copy this file to vykar.yaml and adjust to your needs.
#
# Main concepts:
#   1) sources      -> what gets backed up
#   2) repositories -> where backups are stored
#
# Top-level options (encryption/compression/retention/etc.) are defaults.
# Rich source/repository entries can override parts of those defaults.
#
# Environment variable expansion (before YAML parsing):
#   Use env placeholders in values (see docs for exact syntax).
#   Avoid writing placeholder syntax in comments, because expansion runs
#   before YAML parsing.
#
# Load variables from .env files (Docker-style KEY=VALUE):
# env_file: .db.env
# env_file:
#   - .db.env
#   - .app.env

# --- Minimal runnable config -------------------------------------------------

sources:
  - /home/user/documents

repositories:
  - label: main
    url: /backups/myrepo

# --- Common options many users enable ---------------------------------------

# Many users prefer zstd over lz4 for better compression ratio.
compression:
  algorithm: zstd                 # lz4|zstd|none
  zstd_level: 3

# Optional global hooks (run for backup/prune/check/compact):
#
# hooks:
#   before_backup:
#     - "echo starting backup for {repository}"
#   failed:
#     - "notify-send 'vykar {command} failed: {error}'"

# --- Sources (what to back up) ----------------------------------------------

# Windows paths: use single quotes or no quotes. Double quotes interpret
# backslashes as escape sequences and will cause a parse error.
#   - 'C:\Users\me\Documents'       # single quotes: OK
#   - C:\Users\me\Documents          # no quotes: OK
#   - "C:\Users\me\Documents"        # double quotes: FAILS (\U is a hex escape)

# Simple source form (path strings, label auto-derived from basename):
#
# sources:
#   - /home/user/documents
#   - /home/user/photos

# Rich source form (single path):
#
# sources:
#   - path: /home/user/documents
#     label: docs
#     exclude:
#       - "*.tmp"
#       - ".cache/**"
#     exclude_if_present:
#       - .nobackup
#       - CACHEDIR.TAG
#     one_file_system: false
#     git_ignore: false
#     xattrs:
#       enabled: false
#     repos:                 # only back up to these repos (default: all)
#       - main
#     retention:
#       keep_daily: 14
#       keep_weekly: 8
#     hooks:                 # source hooks: before/after/failed/finally
#       before: "echo starting docs backup"
#       after:
#         - "notify-send 'docs backup complete'"
#     command_dumps:
#       - name: postgres.sql
#         command: pg_dump -U myuser mydb

# Rich source form (multiple paths; requires explicit label):
#
# sources:
#   - paths:
#       - /home/user/documents
#       - /home/user/notes
#     label: writing
#     exclude:
#       - "*.tmp"
#
# Inside a multi-path source, each path's contents are prefixed in the
# snapshot by its full absolute path (leading `/` stripped on Unix,
# drive-letter colon dropped and backslashes converted on Windows). This
# lets paths with the same basename coexist:
#
# sources:
#   - paths:
#       - /etc
#       - /var/lib/machines/base/etc
#     label: etc-everywhere

# Dump-only source (no filesystem paths; label required):
#
# sources:
#   - label: databases
#     command_dumps:
#       - name: all-databases.sql
#         command: pg_dumpall -U postgres
#
# Using env_file with command_dumps for credentials:
#
# env_file: .db.env          # loads DB_USER, DB_PASSWORD, DB_DATABASE
# sources:
#   - label: databases
#     command_dumps:
#       - name: myapp.sql
#         command: "mysqldump -u '<DB_USER>' -p'<DB_PASSWORD>' '<DB_DATABASE>'"
#
# Replace each <NAME> above with an environment placeholder — see "Environment
# variable expansion" in the configuration docs for the exact spelling. It is
# not written out literally here because expansion rewrites comments too, so a
# real placeholder in this file would stop it loading whenever the variable is
# unset.

# --- Repositories (where backups go) ----------------------------------------

# URL formats:
#   Local: /backups/repo  or  file:///backups/repo
#   S3:    s3://endpoint:port/bucket/prefix
#          s3+http://endpoint:port/bucket/prefix  (requires allow_insecure_http: true)
#   SFTP:  sftp://user@host/path               (compile with feature 'backend-sftp')
#   REST:  https://backup.example.com/repo

# Simple repository form:
#
# repositories:
#   - label: main
#     url: /backups/myrepo

# Rich repository form (backend options + per-repo overrides):
#
# repositories:
#   - label: offsite
#     url: s3://s3.us-east-1.amazonaws.com/my-bucket/vykar
#     region: us-east-1
#     access_key_id: AWS_ACCESS_KEY_ID
#     secret_access_key: AWS_SECRET_ACCESS_KEY
#     # sftp_key: ~/.ssh/id_ed25519
#     # sftp_known_hosts: ~/.ssh/known_hosts
#     # sftp_timeout: 30          # per-request timeout in seconds (5–300)
#     # access_token: VYKAR_ACCESS_TOKEN
#
#     min_pack_size: 33554432      # 32 MiB
#     max_pack_size: 536870912     # 512 MiB
#
#     retry:
#       max_retries: 8             # default is 5 (~1 min avg backoff); raise for very unreliable links
#       retry_delay_ms: 3000
#       retry_max_delay_ms: 120000
#
#     encryption:
#       passcommand: "pass show vykar-offsite"
#     compression:
#       algorithm: zstd
#       zstd_level: 6
#     retention:
#       keep_daily: 30
#
#     limits:
#       connections: 2
#       upload_mib_per_sec: 25
#
#     # Per-repo schedule: replaces the global `schedule:` block wholesale
#     # (fields you omit fall back to defaults, not to the global values).
#     # `enabled: true` is required whenever a cadence is set.
#     schedule:
#       enabled: true
#       every: "1h"
#       on_startup: false
#       jitter_seconds: 0
#
#     hooks:
#       before:
#         - "echo starting offsite backup"
#       finally:
#         - "echo finished offsite backup"

# Override hostname recorded in snapshots (default: short system hostname).
# Useful when gethostname() returns a network-dependent FQDN (macOS).
# hostname: MyMachine

# --- Global defaults and advanced options -----------------------------------

# Encryption defaults to mode: auto.
#
# encryption:
#   mode: auto                     # auto|aes256gcm|chacha20poly1305|none
#   # passphrase: "inline-secret"
#   # passcommand: "pass show vykar"
#   # Shell quoting is supported (executed via sh -c on Unix):
#   #   passcommand: "secret-tool lookup app vykar key '/path with spaces'"

# chunker:
#   min_size: 524288               # 512 KiB
#   avg_size: 2097152              # 2 MiB
#   max_size: 8388608              # 8 MiB

# Global source traversal defaults:
#
# exclude_patterns:
#   - "*.tmp"
#   - "*.cache"
#   - ".DS_Store"
#   - "node_modules"
# exclude_if_present:
#   - .nobackup
#   - CACHEDIR.TAG
# one_file_system: false
# git_ignore: false
# xattrs:
#   enabled: true

# Retention policy for `vykar prune` (rules are additive):
#
# retention:
#   keep_within: "2d"             # plain number means days
#   keep_last: 5
#   keep_hourly: 24
#   keep_daily: 7
#   keep_weekly: 4
#   keep_monthly: 6
#   keep_yearly: 2

# Scheduler settings (used by `vykar daemon` and vykar-gui).
# Any repository entry may override this block wholesale — see the per-repo
# `schedule:` example in the rich repository form above.
#
# schedule:
#   enabled: false
#   every: "24h"                  # fixed interval: m, h, d
#   cron: "0 3 * * *"            # OR 5-field cron (mutually exclusive with every)
#   on_startup: false
#   jitter_seconds: 0
#   passphrase_prompt_timeout_seconds: 300   # deprecated: accepted but ignored

# Optional resource limits for backup.
# Bandwidth values are MiB/s (0 = unlimited).
# threads=0 means auto mode: local repos use ceil(cores/2) clamped to [2, 4]; remote repos use min(cores, 12).
#
# limits:
#   connections: 2                 # Parallel backend ops (1-16)
#   threads: 0                     # Backup transform workers (0 = auto: local ceil(cores/2)∈[2,4], remote min(cores,12); 1 = sequential)
#   nice: 0                        # Unix niceness target (-20..19)
#   upload_mib_per_sec: 0          # Upload bandwidth cap
#   download_mib_per_sec: 0        # Download bandwidth cap

# Integrity check settings (used by bare `vykar`, `vykar daemon` and GUI backup runs).
# Standalone `vykar check` always runs 100% regardless of these settings.
#
# check:
#   max_percent: 0                 # % of packs/snapshots to verify per cycle (0-100, default: 0)
#                                  # 0 = skip partial checks; only full_every triggers checks
#   full_every: "60d"              # run full 100% check on this interval (default: unset = never)
#                                  # overrides max_percent to 100 when due

# See docs/src/configuration.md for full option reference.