128 lines
7.0 KiB
Markdown
128 lines
7.0 KiB
Markdown
# 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 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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```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`.
|
|
|
|
## 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
|
|
```
|