yams/docs/admin/configuration.md

Configuration

Concise guidance for configuring YAMS in production. This document focuses on filesystem layout, runtime execution, environment isolation, and operational hygiene. Keep configurations minimal, explicit, and reproducible.

1. Filesystem and data directory

YAMS persists content, indexes, and metadata in a data directory. Use a dedicated volume with strict permissions.

Recommended locations:

• Linux: /var/lib/yams
• macOS (standalone): /usr/local/var/yams or /opt/yams/data
• Containers: bind mount a host path into /var/lib/yams

Permissions:

• Create a dedicated system user/group (e.g., yams).
• Chown the data directory to yams:yams and set 0750.
• Avoid running as root.

Example (Linux):

sudo useradd --system --home /var/lib/yams --shell /usr/sbin/nologin yams || true
sudo mkdir -p /var/lib/yams
sudo chown -R yams:yams /var/lib/yams
sudo chmod 0750 /var/lib/yams

2. Runtime patterns

YAMS is commonly invoked as a CLI in batch or automation contexts. If you deploy a long-running API component in your environment, use a supervisor (systemd or a process manager) and apply the same isolation and logging practices.

2.1 Batch/automation (cron/systemd timer)

• Encapsulate commands in a script (with set -eu -o pipefail).
• Export environment in the script or use an EnvironmentFile.
• Log stdout/stderr for auditing.

Example wrapper:

#!/usr/bin/env bash
set -euo pipefail
export PATH="/usr/local/bin:$PATH"
export YAMS_STORAGE="/var/lib/yams"
# Example job: ingest a directory
yams add /srv/docs --recursive --include="*.md" --tags "docs,import"

2.2 Systemd service (long-running component)

If your deployment includes a long-running YAMS-based service (e.g., API layer):

[Unit]
Description=YAMS Service
After=network-online.target
Wants=network-online.target

[Service]
User=yams
Group=yams
Environment="YAMS_STORAGE=/var/lib/yams"
# EnvironmentFile=-/etc/yams/yams.env       # optional env file
WorkingDirectory=/var/lib/yams
ExecStart=/usr/local/bin/yams serve
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
ProtectSystem=full
ProtectHome=true
PrivateTmp=true
LimitNOFILE=16384

[Install]
WantedBy=multi-user.target

Notes:

• If your build does not expose a server entrypoint, prefer batch/cron usage.
• Adjust LimitNOFILE based on workload (see Performance Tuning).

3. Containers

Use a bind mount for durability and run as a non-root UID/GID.

mkdir -p $HOME/yams-data
docker run --rm -it \
  -u 10001:10001 \
  -v $HOME/yams-data:/var/lib/yams \
  ghcr.io/trvon/yams:latest yams init --non-interactive

Operational run:

docker run --rm -it \
  -u 10001:10001 \
  -v $HOME/yams-data:/var/lib/yams \
  ghcr.io/trvon/yams:latest yams add /data --recursive --include="*.md"

Resource controls:

• CPU/memory limits per container (e.g., --cpus, --memory).
• Mount read-only code/config; write-only data directories.

4. Environment and parameters

Discover supported flags and environment variables with:

yams --help

Guidelines:

• Prefer explicit CLI flags in automation for clarity.
• Use environment variables for secrets and deployment-specific paths.
• Keep site-specific values in an EnvironmentFile (systemd) or a .env (container orchestrators).

Common categories to review in your version:

• Data directory/path
• Concurrency/threads
• Compression options (e.g., zstd, LZMA)
• Deduplication/segmentation settings
• Full-text and vector indexing behavior
• Logging verbosity and output destination
• API service bind address/port (if applicable)

Only configure options supported by your version; defaults are generally safe to start.

5. Logging

• Production: capture stdout/stderr via journald (systemd) or container logs.
• Set log verbosity via CLI flags or environment if supported by your version.
• Retain logs according to your compliance policy; rotate at the platform layer.

Minimal examples:

• systemd: journalctl -u yams.service
• Docker: docker logs

6. Security

• Run as a non-privileged user.
• Restrict filesystem permissions on the data directory (0750).
• Avoid embedding secrets in command lines (process listing); prefer environment or secret managers.
• If exposing a network endpoint (API), bind to a private interface or use a reverse proxy/WAF; enforce TLS termination and authentication upstream.

7. OS resource limits

Set sane defaults for file descriptors and process memory:

• NOFILE: ≥ 16384 (increase with concurrency and open-file patterns)
• Consider vm.swappiness and I/O scheduling based on workload
• Pin versions for reproducibility; avoid untested rolling updates

Example (systemd):

LimitNOFILE=16384

8. Backups and recovery

• Snapshot/copy the entire data directory at a consistent point.
• Quiesce writes when feasible (low-traffic windows or maintenance).
• Store backups off-site with retention and integrity checks.
• Periodically test restore procedures.

See: Operations → Backup

9. Upgrades

• Pin the container tag or package version; upgrade deliberately.
• Take a fresh backup before upgrades.
• Review release notes for any migrations or compatibility notes.
• Validate in staging with representative data and queries.

10. Observability

• Health checks: implement a periodic read/search probe and alert on failures.
• Metrics: wrap CLI/API calls with timing and exit code logging.
• Surface slow queries and error rates in your monitoring stack.

See: Operations → Monitoring

11. References

• Admin → Performance Tuning
• Admin → Vector Search Tuning
• Operations → Deployment
• Operations → Monitoring
• Operations → Backup