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.

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

mkdir -p importarr/config
cd importarr
curl -fsSLO https://example.com/importarr/deploy/docker-compose.example.yml
curl -fsSLo importarr.env https://example.com/importarr/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:

docker build -t importarr:local .

systemd / pip install

git clone https://example.com/importarr.git
cd importarr
sudo sh deploy/systemd-install.sh
sudo ${EDITOR:-vi} /etc/importarr/importarr.env
sudo systemctl start importarr.service

The installer creates the importarr system user when needed, installs a virtualenv, and installs the package from the checked-out repository. Override install paths with IMPORTARR_* variables if the defaults do not fit your environment.

For a machine that should stay current with the repository, use the installed repo-upgrade helper:

sudo -n sh /opt/importarr/repo-upgrade.sh

The helper requires a clean Git checkout at /opt/importarr/repo (override with IMPORTARR_REPO_DIR only for a nonstandard installation). It fetches and checks out exactly origin/main, reinstalls the package, records commit provenance, and restarts importarr.service.

When bootstrapping an existing tagged-release installation, invoke the new helper directly from the checked-out repository once instead of invoking the old installed copy:

sudo -n sh /opt/importarr/repo/deploy/repo-upgrade.sh

That first run installs the repository-based helper at /opt/importarr/repo-upgrade.sh and removes the obsolete IMPORTARR_UPDATE_COMMAND entry from the existing env file. Subsequent deployments can use the installed helper normally.

Pushes to main run .gitea/workflows/deploy.yml. Python tests, frontend tests/build, and deploy-script syntax checks must pass before the deploy job can start. The workflow then connects only to the configured live SSH host, refuses a dirty checkout, updates /opt/importarr/repo to origin/main, and invokes that checkout's upgrade helper through passwordless sudo.

Configure repository Actions secrets IMPORTARR_DEPLOY_HOST, IMPORTARR_DEPLOY_PORT, IMPORTARR_DEPLOY_USER, IMPORTARR_DEPLOY_SSH_KEY (a dedicated private key accepted for the deployment account), and IMPORTARR_DEPLOY_KNOWN_HOSTS (a pinned known_hosts line for the live host). The deployment account must allow the workflow's fixed /bin/sh -c deployment command through sudo -n. The live checkout must be able to fetch origin/main; do not put a Git credential in the workflow. Protect main: require pull requests and the workflow test job, restrict direct pushes and force pushes, and limit workflow/secret administration to trusted maintainers. Gitea Actions executes repository code before deployment, so deployment secrets must not be exposed to pull-request workflows and untrusted contributors must not be permitted to push to main. These controls are repository-administration prerequisites; this workflow cannot enforce them itself.

The upgrade helper holds an exclusive lock across fetch, checkout, install, provenance update, and service restart, so concurrent deployments cannot overlap. The web UI Start, Stop, and Restart controls target manual-media-import.service by default; configure IMPORTARR_START_COMMAND, IMPORTARR_STOP_COMMAND, or IMPORTARR_RESTART_COMMAND when those defaults need a wrapper such as sudo.

Release-worthy changes should be committed and pushed to main; tags remain optional release metadata and are not the deployment trigger.

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_FILE or IMPORTARR_SAB_API_KEY.
4. Mount/configure IMPORTARR_MOVIES_ROOT and IMPORTARR_TV_ROOT read/write.
5. Set IMPORTARR_AUTH_TOKEN_FILE or IMPORTARR_AUTH_TOKEN for every non-loopback bind. Importarr fails closed on write/control endpoints when a non-loopback service has no token; tokenless local development remains available on 127.0.0.1, ::1, or localhost.
6. Check GET /health, then inspect /api/preview 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/preview
• GET /api/history
• GET /api/manual-batches
• POST /api/manual-batches with { "path": "relative/or/absolute/path" }
• DELETE /api/manual-batches/{id}
• POST /api/control/start
• POST /api/control/pause
• POST /api/control/stop
• POST /api/control/cancel-current
• POST /api/control/restart
• POST /api/queue-items/{id}/action with { "action": "retry|ignore|remove" }
• POST /api/import/run-now

Set IMPORTARR_AUTH_TOKEN_FILE or IMPORTARR_AUTH_TOKEN to require Authorization: Bearer <token> for write endpoints.

Development

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
npm --prefix frontend install
npm --prefix frontend run build
pytest
uvicorn importarr.main:app --reload

The web UI is a Vite React application styled with Tailwind CSS. Its local shadcn-style component primitives use Radix UI for dialogs and composition, and lucide-react for icons. Run npm --prefix frontend run dev for Vite's development server (it proxies API calls to port 8765), or build before running FastAPI so the production assets are written to importarr/static.

Operations

Importarr intentionally does not document private deployment topology, hostnames, reverse proxies, monitoring, backups, or operator workflows in this repository. Keep those details in your own ops runbooks.

For a systemd install, prefer a normal package install from the checked-out repo over an editable install so the service user does not need read access to your development checkout.

If the service fails, standard systemd diagnostics are usually enough:

sudo systemctl --no-pager --full status importarr.service
sudo journalctl -u importarr.service -n 120 --no-pager