daniels/importarr
1
0
Fork 0
Code Issues 21 Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
main
importarr/README.md
T

7.5 KiB
Raw Permalink Blame History

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 refuses to run when the checkout has uncommitted changes, then performs git pull --ff-only, reinstalls the package from the repo, restarts importarr.service, and prints service status. Use it after changes have been committed and pushed to main.

Installed deployments can expose the same operation through the authenticated API. GET /api/control/update-check queries the latest release from IMPORTARR_UPDATE_RELEASE_URL (default: this repository's Gitea latest-release API) and compares it with the running IMPORTARR_VERSION. POST /api/control/update performs the same check and only runs the update command when a newer release tag exists. Configure IMPORTARR_UPDATE_COMMAND when the default sh deploy/repo-upgrade.sh is not correct for the service working directory. 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, tagged with SemVer (v0.1.1, v0.2.0, ...), pushed with tags, then installed from the tagged checkout or artifact.

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 unless write endpoints are protected by a reverse proxy.
  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
  • GET /api/control/update-check
  • POST /api/control/update
  • 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.

Persistent local review environment

The review Compose stack builds the current working tree, including uncommitted UI/API changes, and stays running for pre-commit or pre-push inspection. It is separate from production: the web port is bound to localhost by default, state and sample media live under the ignored .review-data/ directory, external Arr/SAB services are not required, and service-control/update commands are safe no-ops.

deploy/review/review.sh up       # build current files and start in background
deploy/review/review.sh update   # rebuild changed files and recreate as needed
deploy/review/review.sh status
deploy/review/review.sh logs     # follow logs; Ctrl-C leaves the stack running
deploy/review/review.sh stop     # stop containers, preserving them and data
deploy/review/review.sh down     # remove containers/network, preserving data
deploy/review/review.sh reset    # remove stack and all local review data

On first use the wrapper copies deploy/importarr.review.env.example to the ignored deploy/importarr.review.env. Adjust REVIEW_PORT there if port 18765 is occupied, then review http://127.0.0.1:18765/. For review from a trusted internal network, set REVIEW_BIND_ADDRESS to the host's LAN address and use that address in the URL. Do not use 0.0.0.0 or expose this review stack to an untrusted network; the safe default is 127.0.0.1. To exercise imports without real integrations, place disposable folders in .review-data/downloads/; movie and TV destinations are .review-data/movies/ and .review-data/tv/. Each checkout gets its own Compose project and image name, so worktrees do not replace each other's containers or images. Read-only and cleanup commands do not create the local env file when it is absent.

Agent workflow: run tests, run update, confirm status reports healthy, and leave the stack running for the reviewer. Reviewer workflow: inspect the UI and API, use logs when needed, and use down after review (or reset when the saved review state is no longer useful). Re-run update after every working-tree change that should be reviewed.

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
Reference in New Issue View Git Blame Copy Permalink