Initial productized Importarr service

2026-07-29 11:37:57 +02:00
commit 577ea97d46
25 changed files with 886 additions and 0 deletions
@@ -0,0 +1,80 @@
+# Importarr
+
+Importarr is an Arr-style service for importing manually categorized SABnzbd downloads after SAB reports final completion. It owns one SAB category, defaults to `manual`, and refuses to import transient Direct Unpack paths or jobs still in SAB queue/post-processing.
+
+## New-machine install
+
+Importarr is intended to feel like a small Arr service: deploy the container or systemd service, edit one env file, point SABnzbd category `manual` at the same completed-download path, then open the web UI.
+
+### Docker Compose, recommended
+
+```sh
+mkdir -p /opt/importarr/config
+cd /opt/importarr
+curl -fsSLO https://gitea.delphas.dk/daniels/importarr/raw/branch/main/deploy/docker-compose.example.yml
+curl -fsSLo importarr.env https://gitea.delphas.dk/daniels/importarr/raw/branch/main/deploy/importarr.env.example
+${EDITOR:-vi} importarr.env
+docker compose -f docker-compose.example.yml --env-file importarr.env up -d
+```
+
+Then open `http://host:8765/` or put it behind your reverse proxy. For a local build instead of a published image, run:
+
+```sh
+docker build -t importarr:local .
+```
+
+### systemd / pip install
+
+```sh
+git clone https://gitea.delphas.dk/daniels/importarr.git
+cd importarr
+sudo sh deploy/systemd-install.sh
+sudo install -o importarr -g importarr -d /var/lib/importarr
+sudo ${EDITOR:-vi} /etc/importarr/importarr.env
+sudo systemctl start importarr.service
+```
+
+The installer creates the `importarr` system user when needed.
+
+### Required setup
+
+1. In SABnzbd, create or confirm category `manual`.
+2. Set its completed folder to the same path mounted as `IMPORTARR_DOWNLOAD_ROOT`.
+3. Set `IMPORTARR_SAB_URL` and `IMPORTARR_SAB_API_KEY`.
+4. Mount/configure `IMPORTARR_MOVIES_ROOT` and `IMPORTARR_TV_ROOT` read/write.
+5. Set `IMPORTARR_AUTH_TOKEN` unless write endpoints are protected by a reverse proxy.
+6. Check `GET /health`, then inspect `/api/jobs` before running imports.
+
+## Safety model
+
+- SAB-managed imports must be in `IMPORTARR_SAB_CATEGORY` and present in SAB history as `Completed` with final `storage`.
+- Active queue/post-processing states such as `Queued`, `Repairing`, `Extracting`, and `Moving` are never ready.
+- `_UNPACK_`, `__UNPACK__`, `_FAILED_`, and `_ADMIN_` paths are skipped.
+- Manual batches are explicit one-time folders under `IMPORTARR_DOWNLOAD_ROOT`.
+
+## API
+
+- `GET /health`
+- `GET /api/status`
+- `GET /api/jobs`
+- `GET /api/history`
+- `GET /api/manual-batches`
+- `POST /api/manual-batches` with `{ "path": "relative/or/absolute/path" }`
+- `DELETE /api/manual-batches/{id}`
+- `POST /api/import/run-now`
+
+Set `IMPORTARR_AUTH_TOKEN` to require `Authorization: Bearer <token>` for write endpoints.
+
+## Development
+
+```sh
+python3.12 -m venv .venv
+. .venv/bin/activate
+pip install -e '.[test]'
+pytest
+uvicorn importarr.main:app --reload
+```
+
+## Migration notes for dgsserver1
+
+Export the existing script settings into `IMPORTARR_*` env vars, add historical folders as explicit manual batches, run a dry-run/inspection through `/api/jobs`, then switch the systemd service or Compose route after the ready set matches expectations.