importarr/README.md

# 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

```sh
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:

```sh
docker build -t importarr:local .
```

### systemd / pip install

```sh
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:

```sh
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

```sh
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.

```sh
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:

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