add v1 advice

Author: davidnewhall

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.

docs/install/configuration.md

@@ -26,12 +26,15 @@ and [example config](https://github.com/Unpackerr/unpackerr/blob/main/examples/u
   - 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
+### Web UI
 
-[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.
+- Added in v1.0.0 (September 2026).
 
-- **Access the generator here: https://notifiarr.com/unpackerr**
+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.**
 
 ### Two+ Instances
 
@@ -82,11 +85,20 @@ like `[sonarr.0]` or `[folder.software]` can be repeated with a unique key.
 
 ### Whisparr
 
-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. Existing `[[whisparr]]` blocks still load as Radarr. Changed in v1.0.0 (September 2026).
+- 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
 
-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. Changed in v1.0.0 (September 2026).
+- 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.
 
 {/* The Global content is generated from here: https://github.com/Unpackerr/unpackerr/tree/main/init/config */}
 <Global />

docs/install/unraid.md

@@ -6,31 +6,39 @@ 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.
+
+:::note[Multiple instances]
+Add extra Starr apps, folders, and hooks in the web UI. Each row has a short
+key (for example `uhd`). You can still use env vars such as
+`UN_RADARR_uhd_URL` if you insist; see
+[configuration](/docs/install/configuration#two-instances).
+:::
 
 :::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 +51,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.
 
 <iframe height="500" width="100%" src="https://www.youtube.com/embed/FfJqgm69ydA"
 frameborder="0" allowfullscreen title="UnRAID Video Guide"

docs/install/upgrading.md

@@ -0,0 +1,182 @@
+---
+id: upgrading
+title: Upgrading to v1
+description: What changed in Unpackerr v1 and how to upgrade an existing install.
+---
+
+Unpackerr v1 (the next release after 0.16) adds a built-in web UI and an HTTP API.
+Starr apps, folders, and hooks can be edited in the browser. Environment variables
+still work, but values owned by env are locked in the UI, so most people should
+move those settings into the config file.
+
+If you are on 0.16.x or earlier today, read this page before you pull `latest`.
+
+## What changed
+
+- A web UI on port **5656** (queue, history, logs, settings, API docs).
+- The HTTP server starts whenever `listen_addr` is set. The default is
+  `0.0.0.0:5656`. Set `listen_addr = ""` to turn the server off.
+- First start with an empty `ui_password` prints a temporary `admin` password
+  in the log. Change it in the UI. It is not shown again. `unpackerr --reset`
+  writes a new one and exits.
+- Saving settings from the UI rewrites the config file. The process user must
+  be able to write that file.
+- Starr apps, folders, webhooks, and command hooks use named keys
+  (`[sonarr.uhd]`, env `UN_SONARR_uhd_URL`). Old `[[sonarr]]` / `[[folder]]`
+  tables still load as `0`, `1`, ….
+- **Whisparr** is no longer its own app. Treat it as Radarr. See
+  [Whisparr](#whisparr).
+- Prometheus scrapes at `/metrics` must send an API key with
+  `system:metrics:read` (`Authorization: Bearer` or `X-Api-Key`).
+- Docker: mount `/config` if you want the UI to persist settings. Unpackerr
+  writes `/config/unpackerr.conf` when that directory exists.
+
+The extractor, Starr polling, and folder watch behave as they did. This release
+is mostly about operating the app from a browser instead of a pile of `UN_*`
+variables.
+
+## Config file permissions
+
+The UI Save button rewrites the active config file. If that file (or its
+directory) is not writable, saves return an error and the change does not stick.
+
+### Linux packages
+
+The service user is `unpackerr`. Packages install `/etc/unpackerr/unpackerr.conf`
+mode `0644` and the post-install script chowns leftover `root:root` files.
+
+If you created or edited the file as root, or Save fails:
+
+```bash
+sudo chown unpackerr:unpackerr /etc/unpackerr /etc/unpackerr/unpackerr.conf
+sudo chmod 0755 /etc/unpackerr
+sudo chmod 0644 /etc/unpackerr/unpackerr.conf
+sudo systemctl restart unpackerr
+```
+
+If you overrode `User=` / `Group=` in a systemd drop-in, chown the file to
+**that** user instead.
+
+Logs: `journalctl -u unpackerr -e` (temporary UI password is in here on first
+start). Open `http://<host>:5656/`.
+
+### Docker and Compose
+
+Mount an appdata directory on `/config`, and run as the same uid:gid that owns
+that directory and your downloads.
+
+```yaml
+    ports:
+      - "5656:5656"
+    volumes:
+      - /mnt/appdata/unpackerr:/config
+      - /mnt/storage/downloads:/downloads
+    user: "99:100"
+```
+
+If `/config/unpackerr.conf` was created as root and you later set `user:`,
+chown the host folder:
+
+```bash
+sudo chown -R 99:100 /mnt/appdata/unpackerr
+```
+
+Use the uid:gid from `user:` (unRAID nobody is `99:100`). Hotio images use
+`PUID`/`PGID` instead of `user:`; chown to those ids.
+
+Drop `UN_SONARR_*`, `UN_RADARR_*`, and the other Starr/hook env vars after the
+settings live in the file. While they remain set, the UI shows those fields as
+coming from the environment and will not Save over them.
+
+### Windows and macOS
+
+Tray and menu-bar installs already write under your user
+(`~/.unpackerr` or the folder you chose). No extra chmod is usually needed.
+Open the UI on `http://127.0.0.1:5656/` after upgrade. The first password is in
+**Logs**.
+
+### Seedbox / no-root binary
+
+Keep the config next to the binary (`~/unpackerr/unpackerr.conf`) owned by
+your shell user (`chmod 0600` is fine). Listen on a port your account may bind;
+the default `0.0.0.0:5656` is fine on a seedbox if the provider allows it.
+
+## unRAID
+
+The [Community Applications](https://github.com/selfhosters/unRAID-CA-templates)
+template used to be env-var only: Sonarr/Radarr/Lidarr URLs, API keys, timers,
+and a log path, with no `/config` and no port. v1 wants an appdata folder, port
+**5656**, and almost none of those variables.
+
+:::tip[Easiest path]
+Remove the Unpackerr container (keep the downloads mount path in mind) and
+install it again from Apps. The updated template adds `/config`, publishes
+5656, and sets `--user 99:100`. Then configure Starr apps in the web UI.
+:::
+
+### Keep the existing container
+
+If you would rather edit the current docker:
+
+1. Enable **Advanced View**.
+1. Add a path: container `/config`, host `/mnt/user/appdata/unpackerr/`
+   (rw).
+1. Add a port: container `5656`, host `5656`.
+1. Copy any Starr URLs and API keys you still need (screenshot or notepad).
+   Removing the env vars before they exist in a config file **drops** those
+   apps until you add them in the UI.
+1. Remove the old variables: `UN_DEBUG`, `UN_LOG_FILE`,
+   `UN_SONARR_*`, `UN_RADARR_*`, `UN_LIDARR_*`, `UN_TIMEOUT`, `UN_PARALLEL`,
+   `UN_INTERVAL`, `UN_DELETE_DELAY`, `UN_START_DELAY`, `UN_RETRY_DELAY`, and
+   any extra `UN_*` you added. Leave the **Downloads Location** path mount.
+1. Extra Parameters should include `--user 99:100` (or the same uid:gid as
+   Sonarr/Radarr). The golift image does **not** use `PUID`/`PGID`.
+1. Apply. First start writes `/config/unpackerr.conf`. Open the WebUI, log in
+   as `admin` with the password from the container log, add your Starr apps,
+   Save.
+
+If Save fails, the appdata folder is probably still `root`. From a terminal:
+
+```bash
+chown -R 99:100 /mnt/user/appdata/unpackerr
+```
+
+Match `99:100` to Extra Parameters.
+
+The download mount must still be identical to Sonarr/Radarr/Lidarr. That has
+not changed; see [unRAID](/docs/install/unraid).
+
+## Whisparr
+
+Whisparr speaks the Radarr API. In v1 it is a Radarr instance.
+
+In the config file, rename the table and optionally keep the label:
+
+```toml
+# before
+[[whisparr]]
+  url = "http://whisparr:6969"
+  api_key = "32characters"
+
+# after
+[radarr.whisparr]
+  name = "Whisparr"
+  url = "http://whisparr:6969"
+  api_key = "32characters"
+```
+
+Environment variables: `UN_WHISPARR_*` becomes `UN_RADARR_whisparr_*`
+(for example `UN_RADARR_whisparr_URL`). Prefer putting this in the file and
+dropping the env vars.
+
+## After upgrade
+
+1. Confirm the UI loads and you can Save a harmless setting (or a Starr
+   instance).
+2. Watch one completed download extract the way it did on 0.16.
+3. If you scrape Prometheus, add an API key with `system:metrics:read`.
+4. Optional: open the Starr (or folder/hook) page and Save once so named
+   tables replace leftover `[[sonarr]]` arrays.
+
+Need a hand? [Go Lift Discord](https://golift.io/discord) or
+[GitHub issues](https://github.com/Unpackerr/unpackerr/issues/new).

docs/introduction.md

@@ -12,6 +12,7 @@ and extract items they download. It can do both, at the same time even.
 ## Features
 
 - Simple to use.
+- Built-in web UI (queue, history, logs, settings) on port 5656.
 - Rich logs.
 - Extracts entire folders.
 - Extracts your subs files too.
@@ -27,7 +28,8 @@ and extract items they download. It can do both, at the same time even.
 
 This application runs as a daemon on your download host. It checks for completed
 downloads and extracts them so Lidarr, Radarr, Readarr, and Sonarr may
-import them. There are a handful of options out there for extracting and deleting
+import them. v1 adds a web UI; existing `0.x` installs should read
+[Upgrading to v1](/docs/install/upgrading). There are a handful of options out there for extracting and deleting
 files after your client downloads them. I just didn't care for any of them, so I
 wrote my own. I wanted a small single-binary with reasonable logging that can extract
 downloaded archives and clean up the mess after they've been imported.

sidebars.js

@@ -2,6 +2,7 @@
 const sidebars = {
   someSidebar: [
     'introduction',
+    'install/upgrading',
     {
       Installation: [
         'install/choosemethod',