Seerr

Seerr is the canonical replacement for both Overseerr and Jellyseerr in QuickBox Pro. Running qb update overseerr -u username or qb update jellyseerr -u username automatically migrates to Seerr. New installations should use qb install seerr -u username directly.

Seerr is a multi-user installable application — each user on the server can have their own Seerr instance with its own port, data directory, and optional subdomain. Whether a given non-admin user is permitted to install Seerr is controlled by their assigned user group. Your server administrator decides which user groups are allowed to install Seerr; administrators can install Seerr for any user regardless of group. If a user attempts to install Seerr and their group does not include it, the install will be blocked with a “package not allowed for user’s group” message.

Administrators can install Seerr for any user at any time. Non-admin users can install Seerr themselves only if their assigned user group includes Seerr in its allowed software list. If you are a regular user and the install command returns “package not allowed for user’s group”, ask your server administrator to add Seerr to your group’s software permissions. Installs triggered from the v4 dashboard’s Package Management page enforce the same group-based access rules.

Running qb update jellyseerr -u username or qb update overseerr -u username automatically triggers migration to Seerr. No manual intervention is needed.

Seerr is automatically integrated into your QuickBox dashboard. Find it in the Service Control panel with port and status information. Click the LAUNCH icon to open the web interface.

Find Seerr in the v4 dashboard under Package Management and in the Service Control tile on your app landing page. The tile shows your assigned port and a direct LAUNCH link. You can also read your assigned port from the software_port column of the user_software table or directly from /opt/username/Seerr/env.conf (which stores the internal Node.js port — add or subtract 10000 to map between internal and public).

Every Seerr update needs to know which public port your instance already owns so nginx, the database row, and the running service stay consistent. The updater resolves that port from multiple sources in priority order and refuses to proceed if none of them yield a valid value:

1. /opt/username/Seerr/env.conf — the PORT= value written by the last successful install or update. This is the most authoritative source because it is exactly what the running seerr@username service binds to.
2. QuickBox database (user_software.software_port for this user) — used when env.conf is missing or unreadable.
3. /etc/nginx/apps-http/username.seerr.conf — the public port parsed from the listen directive. Fallback of last resort.

Each candidate is validated as a positive integer before it is accepted. If all three sources are missing, empty, or invalid, the update aborts cleanly — no files are rewritten, no services are restarted, and the install lock is released so you can retry after investigating. This guarantees qb update seerr will never silently re-assign your port or corrupt your deployment if the state on disk is partially damaged.

Symptom: qb install seerr -u username or qb update seerr -u username aborts with Timed out waiting for /opt/username/Seerr/config/settings.json after 60s. The install lock is released automatically — no database rows are written and nginx is left untouched.

What this means: Right after building the app, the installer starts seerr@username and waits up to 60 seconds for Seerr’s first launch to generate /opt/username/Seerr/config/settings.json. If the Node.js process crashes before that file is written (missing dependency, corrupted build, bad prior state in the config directory, or insufficient memory/disk to complete the first boot), the wait trips and the install aborts.

Checks (run in this order):

1. Service state — look at why the first-boot attempt died:

   systemctl status seerr@username
   journalctl -u seerr@username -n 100 --no-pager

   Common signals: MODULE_NOT_FOUND, Cannot find module, EACCES, ENOSPC (disk full), or a Node-level stack trace.

2. Installer log — the build step pipes its output here:

   tail -n 200 /opt/quickbox/logs/seerr.log

   Look at the final lines before the timeout. A failed pnpm install or pnpm build (network flake, locked pnpm cache, out-of-memory kill) will show up here and explains why the service could not start cleanly.

3. Config directory — confirm the first-boot attempt did not leave a partial file behind:

   ls -la /opt/username/Seerr/config/

   A zero-byte settings.json, a leftover settings.json.tmp, or a pre-existing settings.json owned by root is the bad-state signal. The installer’s jq step writes settings.json.tmp then renames it over settings.json, so a stranded .tmp means the rename never happened.

4. Node runtime — the installer pins Node 22.11.0 inside a per-user venv. Confirm that venv exists:

   /opt/username/lib/nodejs/Seerr/.venv/bin/node --version

   should print v22.11.0. If the venv path is missing, the dependency step failed earlier and the service could never start.

5. Disk space and permissions — a full /opt partition or a wrong owner on /opt/username/Seerr will both surface as a service that exits before writing settings.json:

   df -h /opt
   ls -ld /opt/username/Seerr

   The install directory must be owned by username:username.

Resolution:

• If the journal shows a module/build error, do a full clean reinstall:

  qb remove seerr -u username
  qb install seerr -u username

  This tears down the systemd unit, nginx configs, Node/Python venvs, and the install directory, then rebuilds everything from scratch with a fresh Node venv and a clean settings.json.

• If the journal shows a disk, permission, or memory problem, fix the underlying cause first (free space, correct ownership, add swap for low-RAM servers), then reinstall as above.

• If the failure happened during a qb update (including the auto-migration that runs when you update overseerr or jellyseerr), your original Seerr / source-app data is still on disk. A plain reinstall is safe because the installer will rebuild the config directory; if you want to preserve your existing settings.json and db.sqlite3, copy them out of /opt/username/Seerr/config/ before the remove step and drop them back in after the reinstall completes.

• If every step above checks out clean and the install still trips the 60-second wait, collect systemctl status seerr@username, journalctl -u seerr@username -n 200 --no-pager, and the tail of /opt/quickbox/logs/seerr.log, and open a Discord support ticket  with those three pastes attached.

Checks:

1. Check status: systemctl status seerr@username
2. View logs: journalctl -u seerr@username -f
3. Verify Node.js venv: /opt/username/lib/nodejs/Seerr/.venv/bin/node --version (should show v22.11.0)
4. Check permissions: ls -la /opt/username/Seerr (should be owned by username:username)
5. Verify the assigned internal port is free: ss -tuln | grep "$(grep -oP 'PORT=\K\d+' /opt/username/Seerr/env.conf)" (only seerr@username should be bound there)

Resolution: If Node environment is missing or corrupted, reinstall with qb reinstall seerr -u username to rebuild the virtual environment.

Symptom: Accessing Seerr through the reverse proxy returns 404 Not Found.

Checks:

1. Verify the apps-http nginx config exists: ls -la /etc/nginx/apps-http/username.seerr.conf
2. Look up the user’s internal port: grep PORT /opt/username/Seerr/env.conf
3. Confirm the nginx config’s proxy_pass target matches that internal port
4. Test nginx config: sudo nginx -t
5. Check service status: systemctl status seerr@username (should be active)
6. Verify the Node.js process is listening on its internal port: ss -tuln | grep "$(grep -oP 'PORT=\K\d+' /opt/username/Seerr/env.conf)"

Resolution: Reload nginx with sudo systemctl reload nginx. If the internal or public port drifted (for example after a manual edit of env.conf), run qb reinstall seerr -u username to rebuild the nginx templates against the database-stored port. If a domain was installed, ensure /etc/nginx/sites-enabled/username.seerr.conf references the active certificate paths under /etc/nginx/ssl/domain.

Symptom: Seerr reports “Failed to connect to Radarr” or “Failed to connect to Sonarr”.

Checks:

1. Verify services are running:

   systemctl status sonarr@username
   systemctl status radarr@username

2. Test API connectivity:

   curl http://localhost:7878/api/v3/system/status?apikey=YOUR_RADARR_API_KEY
   curl http://localhost:8989/api/v3/system/status?apikey=YOUR_SONARR_API_KEY

3. Verify API keys match in Seerr settings
4. Check hostname configuration: use localhost (not 127.0.0.1 or server IP)

Resolution: Update Seerr connection settings with correct API keys and ensure “Default Server” is checked for your primary Sonarr/Radarr instance.

Symptom: User requests are approved but not appearing in Sonarr/Radarr.

Checks:

1. View Seerr logs: journalctl -u seerr@username -f | grep -i error
2. Verify “Default Server” is configured: Settings > Services > Radarr/Sonarr > Check ‘Default Server’
3. Ensure quality profiles exist and are selected
4. Verify root folders are configured and paths are valid

Resolution: Test manual request from Seerr UI and watch logs. Ensure quality profile and root folder are properly configured.

Symptom: Running qb update seerr -u username stops early with a message that the public port could not be resolved. The install lock is released automatically — you can retry once the underlying state is fixed.

What this means: The updater intentionally refuses to continue if it cannot recover a valid public port from any of its trusted sources. This is a safety guard that prevents a partially-corrupt deployment from being rewritten with an invalid port (for example, listen 0 ssl; in nginx or a 0 in the database). No files are touched when this guard fires.

Checks:

1. Check env.conf: cat /opt/username/Seerr/env.conf — expect a line like PORT=15055. If the file is missing, empty, or the value is 0, the first source has failed.
2. Check the database port: inspect user_software.software_port for this user in the QuickBox database. A value of 0, NULL, or a missing row means the second source has failed.
3. Check the nginx listener: grep -E '^\s*listen' /etc/nginx/apps-http/username.seerr.conf — expect a real port followed by ssl. A listen 0 ssl; line means the third fallback is also corrupt.
4. Look for a prior failed install/update that may have left partial state behind.

Resolution:

• If at least one source has a valid (non-zero) port, repair the others to match and retry qb update seerr -u username.
• If all three sources are corrupt, the safest path is to back up /opt/username/Seerr/config/ (your settings and database) and run qb reinstall seerr -u username. The reinstall will allocate a fresh port and rebuild nginx, systemd, and env.conf from a clean state while preserving your configuration directory. Open a Discord support ticket  if you would like a staff member to walk through recovery with you.

The update-wipe scenario below only affects servers running a QuickBox Pro CLI release older than 3.2.2.4178. If your server is on 3.2.2.4178 or newer, you do not need to worry about this failure mode — every qb install seerr and qb update seerr now runs the following safeguards automatically:

• Backup first: your current settings.json and db.sqlite3 are copied to ~/.QuickBox/software/seerr/backup/ before anything on the live install is touched.
• Build in staging: the new Seerr version is built in a separate staging directory. Your live install keeps running the whole time.
• Atomic swap: the live install is only replaced after the staging build finishes cleanly.
• Auto-rollback: if the service fails to start on the new version, the entire install is rolled back to the previous state. You never end up with a missing /opt/username/Seerr directory.

Check your CLI version with qb -v. If it is 3.2.2.4178 or higher, the recovery steps below are historical — keep reading only if you need to recover from a failure that happened on an earlier build.

Symptom: A failed qb update seerr -u username on a CLI build older than 3.2.2.4178 has left your install directory gone. Subsequent commands that try to enter /opt/username/Seerr fail with cd: /opt/username/Seerr: No such file or directory, and the Seerr URL returns 502 or connection refused. A fresh install attempt may also surface Timed out waiting for /opt/username/Seerr/config/settings.json after 60s if the rebuild can’t finish cleanly.

What this means: Older versions of the update path removed /opt/username/Seerr before cloning the new release. If the clone, build, or first-boot failed mid-flight, the directory was never restored. From QuickBox Pro 3.2.2.4178 onward, the update is fully transactional (see the green callout above), so new runs cannot reach this state — but installs that were already bitten on earlier builds need to be recovered from the QuickBox backup.

What is in /home/username/.QuickBox/software/seerr/backup/: QuickBox automatically writes settings.json and db.sqlite3 into this directory at specific moments. The directory lives in the user’s home — it is outside /opt/username/Seerr/ and is not touched by an update wipe — but what it contains depends on which of the following triggers ran most recently:

• After qb install seerr -u username — the copy is taken just after Seerr’s first boot writes a default settings.json. If you had not yet opened Seerr in your browser and completed first-time setup, this snapshot is a blank-default settings.json and an essentially empty db.sqlite3. It is a safety net, not your configured state.
• After qb reinstall seerr -u username — the copy captures the post-reinstall state, not your pre-reinstall state. Useful only if you took a manual backup before reinstalling.
• After qb update seerr -u username on CLI 3.2.2.4178 or newer — the copy is taken before the new version touches the live install, so it is a true pre-update snapshot of your running configuration and request database. This is the case that matters for recovery.

Fresh installs — the backup folder is not your data: if you hit this error on a brand-new install that never reached first-time setup, the backup/ folder contains default settings only. There is nothing meaningful to restore. Skip the restore steps below and run a clean install (qb install seerr -u username). For guaranteed point-in-time snapshots going forward, take a manual backup from the dashboard or CLI before major changes — see Take a manual backup below.

Verify your backup exists and contains real data before doing anything else:

ls -la /home/username/.QuickBox/software/seerr/backup/
stat -c '%s %y %n' /home/username/.QuickBox/software/seerr/backup/settings.json
stat -c '%s %y %n' /home/username/.QuickBox/software/seerr/backup/db.sqlite3

Expect to see settings.json and db.sqlite3 with a modification time and byte size that match a moment when your install was actually working. A db.sqlite3 that is only a few KB typically indicates first-boot defaults rather than real request history.

Recovery steps:

1. Rebuild the install directory from scratch:

   qb install seerr -u username

   This reclones seerr-team/seerr, rebuilds the Node.js venv, allocates a fresh port, writes a new env.conf, regenerates the nginx config, and starts the service with a clean first-boot settings.json. Wait for the installer to finish and confirm the service is up:

   systemctl status seerr@username

2. Stop the service so the restore is atomic:

   systemctl stop seerr@username

3. Restore settings.json and db.sqlite3 from the backup on top of the fresh install:

   cp -p /home/username/.QuickBox/software/seerr/backup/settings.json /opt/username/Seerr/config/settings.json
   cp -p /home/username/.QuickBox/software/seerr/backup/db.sqlite3 /opt/username/Seerr/config/db/db.sqlite3
   chown -R username:username /opt/username/Seerr/config/

4. Start the service and confirm it’s healthy:

   systemctl start seerr@username
   systemctl status seerr@username
   journalctl -u seerr@username -n 50 --no-pager

5. Open Seerr in your browser — your previous settings, media server connection, Sonarr/Radarr links, user list, and request history should all be present.

If you never took a manual backup and the automatic backup is only defaults, a clean reinstall is the only path forward. This is unavoidable on CLI releases older than 3.2.2.4178 because those builds never captured a pre-update snapshot of your configured state — the backup/ folder on those servers only holds what was copied at install or reinstall time, which for most users is a blank-default settings.json and an empty db.sqlite3. Concretely, if any of the following is true:

• The backup/ directory is empty or the .QuickBox directory was manually deleted.
• backup/settings.json exists but was written by a fresh qb install seerr before you configured Seerr (default settings only — not your data).
• backup/db.sqlite3 exists but is only a few kilobytes in size (empty database, not your request history).

Then your configuration and request database are unrecoverable from this folder. The only path forward is a clean install (qb install seerr -u username) followed by reconfiguring from scratch: reconnect your media server, re-add Sonarr and Radarr, re-invite your users, and rebuild request history as those users place new requests. Open a Discord support ticket  with the output of ls -la /home/username/.QuickBox/software/seerr/ attached if you want a staff member to confirm there is no alternate backup source before you rebuild.

To avoid this class of loss in the future, take a manual backup from App Management in the v4 dashboard, or run qb manage software -o backup -u username -s seerr, before any major change. See Take a manual backup below for the full flow. From CLI 3.2.2.4178 onward, updates also capture a pre-update snapshot automatically — but that does not replace a user-scheduled backup cadence.

If step 1 itself fails with the 60-second timeout: see Install hangs waiting for settings.json above to diagnose the first-boot failure, then return to step 2 once the service is running.

The automatic copy written to /home/username/.QuickBox/software/seerr/backup/ only runs at install, reinstall, and (on CLI 3.2.2.4178+) at the start of an update. If you want a snapshot of your Seerr configuration and request database on demand — before editing settings, before a reinstall, or just on a schedule — take a manual backup.

From the v4 dashboard: open App Management, expand the Seerr row, and use the Backups panel to create a configuration backup, nginx backup, or full backup. The same panel lets you restore from or delete any previous backup. See App Management for the full dashboard flow.

From the CLI: run qb manage software with the backup operation:

# Back up Seerr's configuration files (settings.json, db.sqlite3)
qb manage software -o backup -u username -s seerr
 
# Back up the entire application (install directory + config) as timestamped tarballs
qb manage software -o backup -o app -u username -s seerr

Both variants write to /home/username/.QuickBox/software/seerr/backup/ with a timestamped filename, so they do not overwrite the install/reinstall/update-triggered copy. Use qb manage software -o restore -u username -s seerr to restore the most recent configuration backup, or -o rollback -o app to restore a full-application backup.