diff --git a/docs/install/choosemethod.md b/docs/install/choosemethod.md index 8aba882..3737633 100644 --- a/docs/install/choosemethod.md +++ b/docs/install/choosemethod.md @@ -4,6 +4,9 @@ title: Choose Install Method description: Choose an Unpackerr install method. --- +Coming from 0.16 or earlier? Read [Upgrading to v1](/docs/install/upgrading) before you +pull a new image or package. + We recommend installing Unpackerr the same way you installed your Starr or download apps. If your existing infrastructure exists in Docker, then Unpackerr should probably live in Docker too. diff --git a/docs/install/compose.md b/docs/install/compose.md index d2f64ee..8f86ed8 100644 --- a/docs/install/compose.md +++ b/docs/install/compose.md @@ -54,6 +54,21 @@ And if you're trying to watch a folder, add this `environment:` variable with _y - UN_FOLDER_0_PATH=/downloads/autoxtract ``` +On Docker, filesystem events are often missing. Add a poll interval on that +same key if nothing shows in the queue: + +```yaml + - UN_FOLDER_0_INTERVAL=1s +``` + +Incomplete downloads can wait on a suffix instead of polling: + +```yaml + - UN_FOLDER_0_WAIT_EXTENSION_0=.part +``` + +See [Folder Watcher](docker#folder-watcher). + ## Data Mount diff --git a/docs/install/configuration.md b/docs/install/configuration.md index c68d509..617ff40 100644 --- a/docs/install/configuration.md +++ b/docs/install/configuration.md @@ -14,52 +14,65 @@ Expand the blue sections to see excerpts from the [example docker-compose.yml](https://github.com/Unpackerr/unpackerr/blob/main/examples/docker-compose.yml) and [example config](https://github.com/Unpackerr/unpackerr/blob/main/examples/unpackerr.conf.example) files. +## Web UI + +:::danger[Web UI] + +- Added in v1.0.0 (September 2026). + +Most users should use the Web UI to configure Unpackerr. +While you can use this page for reference, you should avoid editing the config file. + +- See [Web UI page](web-ui). + +::: + +Unpackerr has a built in Web UI where you can configure all the settings using a validated form. +The Web UI also makes it easy to see what Unpackerr is doing live and to view the extraction history. +This page exists from a time when configuration required editing a file. Now it's for power users. + +**Use the web interface. Don't edit the config file.** + ## Config - Setting a log file is strongly recommended. This makes it much easier to troubleshoot problems. - To use a config file in Docker, mount `/config` to the container and Unpackerr will write a config file. - Update the new file at `/config/unpackerr.conf` and restart the container. -- When using a config file you must uncomment at minimum the `[[header]]` - ex. `[[radarr]]`, `url` and `api_key`. +- When using a config file you must uncomment at minimum the `[header.key]` + ex. `[radarr.radarr]`, `url` and `api_key`. - Uncomment means remove the hash `#` at the beginning of the line. - The config file format is [TOML](https://toml.io). - Indentation is not important like YAML files, but it's used for ease of readability. - You may use `"` or `'` or `'''` or `"""` to wrap strings. Recommend `'` for paths. -### Generator - -[Notifiarr](https://notifiarr.com) hosts a configuration file maker. -Simply fill in a web form, and click a button to get a working config file. - -- **Access the generator here: https://notifiarr.com/unpackerr** - ### Two+ Instances -When adding a second (or third+) instance to the __config file__, you just -add another `[[header]]` ex. `[[sonarr]]` and the -`url`/`api_key`/etc under it. When adding a second instance to the __environment -variables__, you must increment the `0` to a `1`. And to a `2` if you have 3 -instances. There is no limit to the number of supported instances. This notation -works for all Starr apps, folders, command hooks, and webhooks. +When adding a second (or third+) instance to the __config file__, use another +named table ex. `[sonarr.0]`, `[sonarr.uhd]` and the +`url`/`api_key`/etc under it. Environment variables use that same key: +`UN_SONARR_0_URL` or `UN_SONARR_uhd_URL`. Array rows from older configs load as +keys `0`, `1`, …. There is no limit to the number of supported instances. This +notation works for all Starr apps, folders, command hooks, and webhooks.
Config examples with multiple instances. - Config File example with two Radarrs and two Folders. -```yaml -[[radarr]] +```toml +[radarr.0] url = "http://radarr" api_key = "32characters" -[[radarr]] +[radarr.uhd] + name = "4K" url = "http://radarr4k" api_key = "32morecharacters" -[[folder]] +[folder.0] path = "/data/downloads/software/" -[[folder]] +[folder.games] path = "/data/downloads/games/" ``` @@ -68,16 +81,60 @@ works for all Starr apps, folders, command hooks, and webhooks. ```shell UN_RADARR_0_URL=http://radarr UN_RADARR_0_API_KEY=32characters -UN_RADARR_1_URL=http://radarr4k -UN_RADARR_1_API_KEY=32morecharacters +UN_RADARR_uhd_URL=http://radarr4k +UN_RADARR_uhd_API_KEY=32morecharacters UN_FOLDER_0_PATH=/data/downloads/software/ -UN_FOLDER_1_PATH=/data/downloads/games/ +UN_FOLDER_games_PATH=/data/downloads/games/ ```
-Anything that [has a header](https://github.com/Unpackerr/unpackerr/blob/main/examples/unpackerr.conf.example#L99) -with double brackets `[[..]]` can be repeated as many times as you'd like. +Anything that has a header like `[sonarr.0]` or `[folder.software]` can be repeated with a unique key. + +### Whisparr + +- Changed in v1.0.0 (September 2026). + +Whisparr uses the Radarr API. Configure it as `[radarr.whisparr]` (env `UN_RADARR_whisparr_*`). +Set `name = "Whisparr"` if logs and hooks should keep that label. + +### Named instances + +- Added in v1.0.0 (September 2026). + +Starr apps, folders, webhooks, and command hooks are identified by a short key, not by list position. +In the config file use `[sonarr.uhd]`, `[folder.software]`, `[webhook.discord]`; in env use `UN_SONARR_uhd_URL`, +`UN_FOLDER_software_PATH`, `UN_WEBHOOK_discord_URL`. The optional `name` on Starr and hooks is only a label +(`name = "Starrs & Stripes"`). Existing `[[sonarr]]` / `[[folder]]` / `[[webhook]]` tables still load as keys +`0`, `1`, …. Open that section in the web UI and click Save: Unpackerr rewrites the file to named tables automatically. + +### Watch folders + +- Changed in v1.0.0 (September 2026). + +Folder watch is not Starr. Each `[folder.]` is a path Unpackerr extracts +on its own. The generated tables below list every option. + +**Poll interval** is per folder (`interval`, env `UN_FOLDER__INTERVAL`). +Default `0s` uses filesystem events. Set `1s` (or similar) on Docker and CIFS +when new archives never show in the queue. Global `folders.interval` / +`UN_FOLDERS_INTERVAL` is gone; leftover `[folders] interval` is ignored. +Details: [Docker Folder Watcher](docker#folder-watcher). + +**After a restart**, recent folder history returns to the live queue the same +way Starr items do: EXTRACTED still waiting on `delete_after`, EXTRACTFAILED +retries, interrupted EXTRACTING, QUEUED, and WAITING after a retry. A path +you removed from config is not restored. Windows matches watch paths without +regard to drive-letter case. + +**Incomplete downloads:** `wait_extensions` keeps the item WAITING while a +matching file exists in that item's top folder (`.part`, `.crdownload`, …). +Nested paths are not scanned. The queue shows the blocking filename. +Recheck is every 5s and does not enable the poller. +Env: `UN_FOLDER__WAIT_EXTENSION_0=.part`. + +**Empty folders:** `skip_empty` (env `UN_FOLDER__SKIP_EMPTY`) drops +archive-free folders after `start_delay` with no history row and no webhook. {/* The Global content is generated from here: https://github.com/Unpackerr/unpackerr/tree/main/init/config */} @@ -97,8 +154,8 @@ by setting the value to `filepath:/path/to/file.txt`. In other words, if you wan your Radarr API key to be read from a separate file, instead of storing it directly in the config file or environment variables you can do this: -```json -[[radarr]] +```toml +[radarr.0] url = "https://some.url/radarr" api_key = "filepath:/etc/secrets/radarr.txt" ``` diff --git a/docs/install/docker.md b/docs/install/docker.md index de6ca76..7841da8 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -106,16 +106,28 @@ docker run -e PUID=1000 -e PGID=100 -d -v /mnt/data:/data -v /mnt/config:/config ## Folder Watcher -Watching folders in Docker will cause Unpackerr to constantly poll the -watched-folder for changes at a default rate of `1s` (1 second). +The Folder Watch feature uses `inotify` (a.k.a. `fsnotify`) to notice new +archives. Each watch path has its own `interval`. The default is `0s`, which +means filesystem events only — Unpackerr does **not** poll. -The Folder Watch feature uses `inotify` (a.k.a. `fsnotify`) to identify changes to the -watched folder. A folder-poller is automatically started when run in Docker because -`inotify` is unreliable. Disable the folder poller (and rely on `inotify` only) by -setting `folders.interval` (`UN_FOLDERS_INTERVAL`) to `1ms`. +Docker bind mounts and CIFS often drop or delay those events, so items never +appear in the queue. Turn polling on for that path: -If Unpackerr has trouble determining when downloads are finished, set -`start_delay` high enough to avoid beginning extracting files that are -still being transferred. +- Web UI: **Settings → Folders** → **Poll interval** (try `1s`). +- Config: `interval = "1s"` under `[folder.downloads]`. +- Env: `UN_FOLDER_downloads_INTERVAL=1s` (same key as the table). + +Leave `interval` at `0s` when native fsnotify works. Polling increases disk +reads. A folder with a poll interval uses the poller only; other folders keep +fsnotify. + +v0.x Docker installs auto-polled every 1s via global `folders.interval` +(`UN_FOLDERS_INTERVAL`). That setting is gone. An old `[folders] interval` +line in the file is ignored. + +If Unpackerr starts extracting files that are still downloading, raise +`start_delay`, or set `wait_extensions` (for example `.part`, `.crdownload`) +on that folder. Waiting items are rechecked every 5 seconds without turning +the poller on. See [Watch folders](configuration#watch-folders). **Alternatively, run Unpackerr as a native service instead of in Docker.** diff --git a/docs/install/unraid.md b/docs/install/unraid.md index 73eea4f..597622d 100644 --- a/docs/install/unraid.md +++ b/docs/install/unraid.md @@ -6,31 +6,32 @@ description: Install Unpackerr on your unRAID server! # unRAID Install -Unpackerr is available in the -[Community Applications](https://github.com/selfhosters/unRAID-CA-templates/blob/main/templates/unpackerr.xml) -on unRAID. Install it from the `Apps` page; see screenshot that follows. +Unpackerr is available in +[Community Applications](https://github.com/selfhosters/unRAID-CA-templates/blob/master/templates/unpackerr.xml) +on unRAID. Install it from the **Apps** page. -![Community Applications Unpackerr install](/img/screenshots/unraid/install1.png "install") +The golift template mounts **appdata** at `/config`, publishes port **5656** for +the web UI, and runs as `--user 99:100`. Configure Sonarr, Radarr, Lidarr, and +the rest in the browser after install. Do not put Starr URLs and API keys back +into environment variables unless you want those fields locked in the UI. -On the install screen, fill in the `URL` and `API_KEY` for one or more of the Starr apps. +Upgrading an existing 0.x container? See [Upgrading to v1](/docs/install/upgrading#unraid). -:::note[Multiple Instances] -If you have, for instance, two Radarrs, you can simply add two new variables: -`UN_RADARR_1_URL` and `UN_RADARR_1_API_KEY`. If you have 3, then increase -the `1` to a `2` and so on. This works for all Starr apps, folders, webhooks and command -hooks. There is no limit to how many you may configure. -::: +![Community Applications Unpackerr install](/img/screenshots/unraid/install1.png "install") -It's also recommended that you set a log file. -Put it in your downloads location; an example follows. +On the install screen, set **Downloads Location** so it matches your Starr apps +(next section). Leave **appdata** at `/mnt/user/appdata/unpackerr/` unless you +prefer another folder. Apply, then open the WebUI. -![Bind volume for Unpackerr log file](/img/screenshots/unraid/bindvolume.png "bind volume") +First login is user `admin`. The password is printed once in the container log +(`Generated temporary UI password`). Change it in Settings. :::tip[Download Location] -The most common misconfiguration on unRAID, by far, and it's not even a close second, is -having the correct path mounted for your download location. As you see in the screenshot above, -it's set to `host:/mnt/user/downloads` and `container:/downloads`. This is almost certainly -not what you want. **Do this:** +The most common misconfiguration on unRAID, by far, and it's not even a close +second, is having the correct path mounted for your download location. As you +see in the screenshot below, a host path of `/mnt/user/downloads` with a +container path of `/downloads` is almost certainly not what you want. +**Do this:** 1. Go into Unraid. 1. Click on Docker. @@ -43,31 +44,38 @@ not what you want. **Do this:** ![Starr app volume mounts](/img/screenshots/unraid/starrmounts.png "starr mounts") -If the highlighted portions above are not identical to the one below, then things are bound to work poorly. -In other words, if Unpackerr has `/downloads <-> /mnt/user/downloads` and Sonarr has -`/data <-> /mnt/user/downloads`, Unpackerr will not be able to find your files. In this hypothetical, you -must edit the Unpackerr `/downloads` mount, and change the _Container Path_ to `/data` so it matches Sonarr. +If the highlighted portions above are not identical to the one below, then +things are bound to work poorly. In other words, if Unpackerr has +`/downloads <-> /mnt/user/downloads` and Sonarr has +`/data <-> /mnt/user/downloads`, Unpackerr will not be able to find your files. +In this hypothetical, you must edit the Unpackerr `/downloads` mount, and +change the _Container Path_ to `/data` so it matches Sonarr. ![Unpackerr volume mount](/img/screenshots/unraid/unpackerrmount.png "unpackerr mount") ::: ## Permissions -Set the UID and GID by adding `--user uid:gid` to the `Extra Parameters` -section of the unraid template after enabling the `Advanced` view. -![Enable Docker advanced view](/img/screenshots/unraid/advancedview.png "advanced view") -You must make these match your Starr app so hard links work correctly. -**Other containers, use env variables such as `PUID` and `PGID`, but the -Go Lift unpackerr container does not use these.** -e.g. If Sonarr has `PUID` of `99` and `PGID` of `100`, then you must -add **`--user 99:100`** to `Extra Parameters` as shown below. +The template Extra Parameters already include `--user 99:100` (unRAID +`nobody:users`), which matches typical linuxserver Starr containers. Change it +if your Sonarr/Radarr uid:gid is different. **Other containers use `PUID` and +`PGID`; the golift image does not.** ![Unpackerr Extra Parameters UID and GID](/img/screenshots/unraid/extraparameters.png "extra parameters") +The appdata folder and the config file inside it must be writable by that +same user, or the UI cannot Save. If needed: + +```bash +chown -R 99:100 /mnt/user/appdata/unpackerr +``` + ## Video Guide This guide is provided by a community member, [@Celsian](https://www.youtube.com/@Celsian), -consider giving him a sub and a like. +consider giving him a sub and a like. It was recorded against the old env-var +template; ignore the Sonarr/Radarr variable fields and use the web UI instead. +The download-path matching still applies.