# Automation helpers

This directory includes repo-side helpers for homelab operational tasks.

## KitchenOwl recipe import helper

- `bin/kitchenowl_recipe_import.py` — Doris-managed KitchenOwl recipe importer
  - tries KitchenOwl's own scrape endpoint first
  - falls back to direct page fetch + schema.org `Recipe` JSON-LD parsing
  - normalizes ingredients/tags/timings into KitchenOwl's create-recipe payload
  - supports dry-run by default and live create with `--create`

See `docs/operations/KITCHENOWL_RECIPE_IMPORT.md` for setup and usage.

## Backup scripts

- `bin/pd_backup_postgres.sh` — creates gzipped `pg_dump` exports for the configured Postgres DB list (quote space-separated DB names in `.env`, e.g. `POSTGRES_DB_LIST="n8n paperless"`)
- `bin/pd_backup_sync_to_serenity.sh` — `rsync`s configured backup/config roots to Serenity
- `bin/run_pd_backups.sh` — wrapper that runs both steps in order

These scripts are staged repo-side only. They still need:

1. real values in `.env`
2. a writable dump destination on PD
3. SSH trust / key path for Serenity (`root@10.5.1.5` by default)
   - recommended known_hosts path on PD: `/home/truenas_admin/.ssh/known_hosts`
4. a real scheduler (cron/systemd timer/n8n) on the live host

## PD / TrueNAS deployment recommendation

Use a plain cron job on PD, not n8n and not a custom systemd timer.

Reasons:

- survives n8n outages
- keeps the backup runner close to the compose/data host
- avoids extra appliance fights on TrueNAS SCALE
- matches the existing shell-first operational style on PD

Preferred mode on PD: **root cron**.

Why: the dump path under `/mnt/tank/...` and Docker access are typically cleaner from root on TrueNAS than from a limited operator account.

TrueNAS-specific notes:

- scripts use `/usr/bin/bash` explicitly
- default Docker path is `/usr/bin/docker`
- if run as root, scripts call Docker directly
- if run as a non-root user, default behavior is `sudo -n /usr/bin/docker ...`
- keep all live paths under `/mnt/...`; never rely on rootfs write locations

## Example live flow

```bash
cd /mnt/docker-ssd/docker/compose/automation
cp .env.example .env
chmod 600 .env
mkdir -p /mnt/tank/docker/backups/db-dumps
bin/run_pd_backups.sh
```

## Recommended PD cron block

Install in **root's crontab on PD**:

```cron
# BEGIN PD BACKUPS
15 2 * * * cd /mnt/docker-ssd/docker/compose/automation && /usr/bin/bash bin/run_pd_backups.sh >> /mnt/tank/docker/backups/pd-backups.log 2>&1
# END PD BACKUPS
```

Recommended first-run checklist:

```bash
cd /mnt/docker-ssd/docker/compose/automation
cp .env.example .env   # if not already present
chmod 600 .env
mkdir -p /mnt/tank/docker/backups/db-dumps
/usr/bin/bash bin/run_pd_backups.sh
tail -100 /mnt/tank/docker/backups/pd-backups.log
```

## Safety notes

- DB dumps are the priority restore artifacts; do not rely only on raw volume copies.
- The sync script uses `rsync --delete` inside the destination backup root, so point it at a dedicated backup path.
- Keep `.env` and SSH material out of git.
- If cron runs under a non-root PD account, `sudo -n /usr/bin/docker` must work or the DB dump step will fail.