|
| 1 | +--- |
| 2 | +id: web-ui |
| 3 | +title: Web UI |
| 4 | +description: Use the built-in Unpackerr web UI, confirm it is running, and reset the password. |
| 5 | +--- |
| 6 | + |
| 7 | +Unpackerr v1 ships a browser UI on port **5656**. Use it to watch the extract |
| 8 | +queue, read history and logs, and configure Starr apps, folders, and hooks. The |
| 9 | +HTTP API is the same server. Coming from 0.16 or earlier? Read |
| 10 | +[Upgrading to v1](/docs/install/upgrading) first. |
| 11 | + |
| 12 | +Do not edit the config file unless you have a reason. Save in the UI writes |
| 13 | +the file for you. Environment variables still win: a field owned by `UN_*` is |
| 14 | +locked in the form until you remove that variable. |
| 15 | + |
| 16 | +## What you get |
| 17 | + |
| 18 | +- **Dashboard** — live extract queue (retry / forget) and Starr poll counts. |
| 19 | +- **History** — completed extracts, with delete and clear. |
| 20 | +- **Logs** — follow the app log in the browser (and download rotated files). |
| 21 | +- **Settings** — general, Starr, folders, webhooks, command hooks, web server. |
| 22 | + Each Starr or hook row has a Test button that probes without saving. |
| 23 | +- **System** — version, hostname, OS, and the folders Unpackerr is logging to. |
| 24 | +- **API docs** — OpenAPI for the same process (`/api/openapi.json`). |
| 25 | + |
| 26 | +Windows and macOS also get a tray / menu-bar **WebUI** link that opens the |
| 27 | +local URL, plus **Change Password** and **View logs**. |
| 28 | + |
| 29 | +Languages: English, Spanish, Greek, Dutch. |
| 30 | +[Need more? Ask](https://github.com/Unpackerr/unpackerr/issues/new). |
| 31 | + |
| 32 | +## Make sure it is running |
| 33 | + |
| 34 | +The HTTP server starts whenever `[webserver]` `listen_addr` is set. The default |
| 35 | +is `0.0.0.0:5656` (all interfaces). An empty string turns the server **off**. |
| 36 | + |
| 37 | +```toml |
| 38 | +[webserver] |
| 39 | + listen_addr = "0.0.0.0:5656" |
| 40 | +``` |
| 41 | + |
| 42 | +Env equivalent: `UN_WEBSERVER_LISTEN_ADDR=0.0.0.0:5656`. Docker and Compose |
| 43 | +must **publish** that port (`5656:5656`). unRAID templates add the port for |
| 44 | +you; see [unRAID](/docs/install/unraid). |
| 45 | + |
| 46 | +Then open `http://<host>:5656/` (or `http://127.0.0.1:5656/` on the same |
| 47 | +machine). Tray installs: click **WebUI**. |
| 48 | + |
| 49 | +:::tip[Firewall] |
| 50 | +`0.0.0.0:5656` is reachable on the LAN. If the page never loads, check the |
| 51 | +host firewall and that nothing else is bound to 5656. Binding |
| 52 | +`127.0.0.1:5656` is local-only on purpose. |
| 53 | +::: |
| 54 | + |
| 55 | +### What to look for in the log |
| 56 | + |
| 57 | +On a healthy start you want lines like these (wording is exact): |
| 58 | + |
| 59 | +```text |
| 60 | + => Starting webserver. Listen address: http://0.0.0.0:5656/ (0 upstreams) auth:password |
| 61 | +Generated temporary UI password for user admin: <password> |
| 62 | +Change it with --reset or the tray menu. It will not be shown again. |
| 63 | +``` |
| 64 | + |
| 65 | +The temporary password line appears only when `ui_password` is empty (first |
| 66 | +start, or an empty `filepath:` password file). It is printed **once**. Copy it |
| 67 | +before you rotate or truncate the log. |
| 68 | + |
| 69 | +A first start may also print `Generated an admin API key named "…"`. That key |
| 70 | +is for `/metrics` and scripts, not for the login form. |
| 71 | + |
| 72 | +If the server is off: |
| 73 | + |
| 74 | +```text |
| 75 | + => Webserver Disabled |
| 76 | +``` |
| 77 | + |
| 78 | +`listen_addr` is empty. Set it and restart. |
| 79 | + |
| 80 | +If the bind failed: |
| 81 | + |
| 82 | +```text |
| 83 | +Web Server Failed: listen tcp …: bind: address already in use |
| 84 | +``` |
| 85 | + |
| 86 | +Something else owns the port, or the process cannot bind it. |
| 87 | + |
| 88 | +`Could not persist config to …` means the file (or `/config` directory) is not |
| 89 | +writable. Saves from the UI will fail until you fix ownership. Linux, Docker, |
| 90 | +and unRAID chmod notes live on [Upgrading to v1](/docs/install/upgrading). |
| 91 | + |
| 92 | +### Where the log is |
| 93 | + |
| 94 | +- **Linux package:** `journalctl -u unpackerr -e` |
| 95 | +- **Docker / unRAID:** container log (`docker logs unpackerr`, or the unRAID |
| 96 | + log view) |
| 97 | +- **Windows / macOS tray:** **View logs** |
| 98 | +- **Config:** `log_file` (and `webserver.log_file` for HTTP access logs) |
| 99 | + |
| 100 | +Once you can log in, the UI **Logs** page tails the same files. System → Logs |
| 101 | +shows the parent folder(s) if you are hunting on disk. |
| 102 | + |
| 103 | +## First login |
| 104 | + |
| 105 | +User is **`admin`** unless you set a username in `ui_password` (`user:pass` or |
| 106 | +`filepath:` with `user:pass` in the file). Password is the generated value |
| 107 | +from the log, or whatever you put in `ui_password` / |
| 108 | +`UN_WEBSERVER_UI_PASSWORD`. |
| 109 | + |
| 110 | +Change it under **Settings → Web server** after you get in. Minimum length is |
| 111 | +8 characters. The plaintext never leaves the browser; the UI sends a hash. |
| 112 | + |
| 113 | +:::danger[Empty env password] |
| 114 | +Do not set `UN_WEBSERVER_UI_PASSWORD=` (empty). A present empty env value |
| 115 | +wipes a stored hash on the next start. Omit the variable entirely if the |
| 116 | +password lives in the config file. |
| 117 | +::: |
| 118 | + |
| 119 | +## Reset the password |
| 120 | + |
| 121 | +You still know it: **Settings → Web server**, or tray **Change Password**. |
| 122 | +Those apply live and rewrite the file. |
| 123 | + |
| 124 | +You forgot it: stop the process, run `unpackerr --reset`, start it again. `--reset` |
| 125 | +writes a new password into the config file, prints it, and **exits**. It does |
| 126 | +not keep running as the daemon. |
| 127 | + |
| 128 | +Linux package: |
| 129 | + |
| 130 | +```bash |
| 131 | +sudo systemctl stop unpackerr |
| 132 | +sudo -u unpackerr unpackerr --reset |
| 133 | +sudo systemctl start unpackerr |
| 134 | +``` |
| 135 | + |
| 136 | +Docker / Compose (same `/config` mount as the running container): |
| 137 | + |
| 138 | +```bash |
| 139 | +docker compose stop unpackerr |
| 140 | +docker compose run --rm unpackerr --reset |
| 141 | +docker compose up -d |
| 142 | +``` |
| 143 | + |
| 144 | +Or a one-shot with the golift image: |
| 145 | + |
| 146 | +```bash |
| 147 | +docker run --rm -v /mnt/user/appdata/unpackerr:/config golift/unpackerr --reset |
| 148 | +``` |
| 149 | + |
| 150 | +Then start the usual container. unRAID: use that `docker run` with your |
| 151 | +appdata path, or stop the container and run `--reset` from a console that has |
| 152 | +the same `/config` mount. |
| 153 | + |
| 154 | +`--reset` keeps the existing username when one is stored. The new password is |
| 155 | +on stdout: |
| 156 | + |
| 157 | +```text |
| 158 | +Reset UI password for user "admin" and wrote /config/unpackerr.conf |
| 159 | +New "admin" user password: <password> |
| 160 | +``` |
| 161 | + |
| 162 | +If `UN_WEBSERVER_UI_PASSWORD` is set, that env value overlays the file on the |
| 163 | +next start and `--reset` will not stick. Remove the variable, then reset. |
| 164 | + |
| 165 | +`filepath:/path/to/ui.pass` is allowed: live login reads the file, the config |
| 166 | +keeps the `filepath:` string. An empty file is rejected on Save (400). At |
| 167 | +startup an empty file still generates a temporary `admin` password so you are |
| 168 | +not locked out. |
| 169 | + |
| 170 | +## Settings that stay locked |
| 171 | + |
| 172 | +Grey fields come from the environment. Saving will not change the running |
| 173 | +value. Drop `UN_SONARR_*`, `UN_RADARR_*`, `UN_WEBSERVER_UI_PASSWORD`, and the |
| 174 | +rest after those settings live in the file. Test on a Starr or hook row is |
| 175 | +also blocked when the URL, API key, or command is env-owned. |
| 176 | + |
| 177 | +Starr API keys (and most other strings) accept `filepath:/path/to/secret`. |
| 178 | +Save and Test expand the file for the live client; the config keeps the |
| 179 | +prefix. See [Secrets and Passwords](/docs/install/configuration#secrets-and-passwords). |
| 180 | + |
| 181 | +## Restart required |
| 182 | + |
| 183 | +Most settings apply as soon as you Save. Changing `listen_addr`, TLS certs, |
| 184 | +`urlbase`, metrics, pprof, or the HTTP log file needs a process restart. The |
| 185 | +Save response sets `restartRequired`; restart the service or container when |
| 186 | +you are done editing. |
| 187 | + |
| 188 | +## Reverse proxy |
| 189 | + |
| 190 | +Put Unpackerr behind nginx, Caddy, or SWAG if you want TLS or a subfolder. |
| 191 | + |
| 192 | +- Set `urlbase` to the public path (`/` on a subdomain, `/unpackerr/` on a |
| 193 | + subfolder). |
| 194 | +- Add the proxy IP or Docker gateway to `webserver.upstreams` so |
| 195 | + `X-Forwarded-For` / `X-Forwarded-Proto` are trusted (secure cookies, logs, |
| 196 | + optional header auth). |
| 197 | +- Proxy **WebSocket** `GET /ws` (or `/unpackerr/ws`) with Upgrade headers. |
| 198 | + Queue, progress, history, and log follow use it. |
| 199 | + |
| 200 | +A copy-pasta nginx example is in the |
| 201 | +[repo](https://github.com/Unpackerr/unpackerr/blob/main/examples/nginx.conf.example). |
| 202 | + |
| 203 | +Header auth (`ui_password = "webauth:X-Webauth-User"`) and `noauth` only work |
| 204 | +from an address in `upstreams`, so you cannot lock yourself out from a |
| 205 | +non-proxy IP. |
| 206 | + |
| 207 | +## API keys and metrics |
| 208 | + |
| 209 | +Login uses the UI user. Prometheus and scripts use an API key |
| 210 | +(`X-Api-Key` or `Authorization: Bearer`). Create keys under **Settings → Web |
| 211 | +server**. Scrapes of `/metrics` need a key with `system:metrics:read`. |
| 212 | + |
| 213 | +Need a hand? [Go Lift Discord](https://golift.io/discord) or |
| 214 | +[GitHub issues](https://github.com/Unpackerr/unpackerr/issues/new). |
0 commit comments