inspector/INSTALL.md

Installing Inspector with Portainer

This guide uses only the Portainer web UI. You don't need SSH, a terminal, or a config file: Inspector creates its own settings on first start and everything else is done in its dashboard.

You need: a Docker host managed by Portainer (CE or BE, 2.x), and a few minutes. Gotify or Pushover are optional, for phone alerts.

---

1. Create the stack

1. In Portainer, open your environment (usually local) and click Stacks → + Add stack.

2. Name: inspector

3. Build method: Web editor. Paste the contents of compose.yml:

   services:
     inspector:
       image: gitea.euronvault.com/euronvault/inspector:${INSPECTOR_TAG:-latest}
       container_name: inspector
       restart: unless-stopped
       ports:
         - "${INSPECTOR_PORT:-8080}:8080"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - ${INSPECTOR_DATA:-/opt/inspector}/config:/app/config
         - ${INSPECTOR_DATA:-/opt/inspector}/logs:/app/logs
         - ${INSPECTOR_DATA:-/opt/inspector}/data:/app/data
       environment:
         - TZ=${TZ:-UTC}
         - INSPECTOR_PASSWORD=${INSPECTOR_PASSWORD:-}
         - PUID=${PUID:-1000}
         - PGID=${PGID:-1000}
   

2. Set the environment variables

Scroll down to Environment variables. Click Advanced mode and paste, then edit the values:

INSPECTOR_DATA=/mnt/user/appdata/inspector
INSPECTOR_PASSWORD=pick-a-password
TZ=America/Los_Angeles

Variable	What to put	Required
INSPECTOR_DATA	Folder on your server where Inspector keeps its settings, logs, and history. Unraid: /mnt/user/appdata/inspector. Other Linux: /opt/inspector. Created automatically.	Yes
INSPECTOR_PASSWORD	Password for the dashboard (username admin). Used only on first start; change it later in the dashboard. Leave it out and Inspector generates one and prints it in the container logs.	Recommended
TZ	Your timezone, so times on the dashboard are local.	Recommended
INSPECTOR_PORT	Port on your server for the dashboard. Change it if 8080 is taken.	No (default 8080)
INSPECTOR_TAG	Version to run, e.g. 0.8.0. See Updating.	No (default latest)
PUID / PGID	User and group that own Inspector's files. Unraid users often use 99 / 100 so the files match other appdata.	No (default 1000 / 1000)

3. Deploy and sign in

1. Click Deploy the stack.
2. Open http://<your-server-ip>:8080 (or the port you chose).
3. Sign in as admin with your INSPECTOR_PASSWORD.
   • No password set? Go to Containers → inspector → Logs in Portainer. Near the top is a box labeled Inspector dashboard login with the generated password.
4. Click Help in the dashboard header for the full how-to guide. The short version:
   • Settings → + Add container: add each container you want watched, using its exact name from Portainer, and click Recommended for restart rules.
   • Settings → Notifications: turn on Gotify and/or Pushover, click Send test, then Save.
   • Restart Inspector once after changing anything marked requires restart (Portainer → Containers → tick inspector → Restart).

That's it. Inspector picks up new containers on its next check (within a minute).

---

4. Updating

1. Stacks → inspector → Editor.
2. Click Update the stack and turn on Re-pull image and redeploy.
3. Confirm.

Your settings and history live in INSPECTOR_DATA, so updates never touch them.

Pinning a version. latest always gets the newest release. To stay on a specific version, set INSPECTOR_TAG (e.g. 0.8.0) in the stack's environment variables, then update the stack. Available versions are on the releases page and in the CHANGELOG.

Rolling back. Set INSPECTOR_TAG to the previous version and update the stack with Re-pull image and redeploy on.

5. Uninstalling

1. Stacks → inspector → Delete this stack.
2. Delete the INSPECTOR_DATA folder (on Unraid, through the appdata share) if you don't want to keep the settings and history.

Inspector never changes your other containers' files or settings. It only starts and restarts the ones you add to it.

---

Troubleshooting

What you see	What to do
Stack fails with pull access denied or not found	Check the image line is exactly gitea.euronvault.com/euronvault/inspector:... and that INSPECTOR_TAG (if set) is a real version.
Port already in use	Set INSPECTOR_PORT to a free port (e.g. 8095) and update the stack.
Logs say Permission denied on /var/run/docker.sock	Make sure the stack has no user: line, then update the stack. Inspector needs to start normally to set up socket access.
Red READ-ONLY badge at the bottom of Settings	The config folder mount ends in :ro or the folder isn't writable. Remove :ro and update the stack.
Can't sign in	Look for the generated password in the container logs. If you've lost it, open INSPECTOR_DATA/config/config.yml (e.g. via your Unraid share), set a new password: under dashboard:, and restart Inspector.
A container shows CONTAINER NOT FOUND	The name in Inspector doesn't match Docker. Copy the exact name from Portainer → Containers.

Security notes

• Inspector needs the Docker socket to restart containers. Anything with access to that socket effectively has full control of the host, so keep the dashboard on your home network (or behind a VPN / reverse proxy with auth) and use a real password.
• Inspector's process runs as an unprivileged user. It starts as root only long enough to detect the Docker socket's group and fix ownership of its own folders.

Moving from an older (0.7.x) setup

Older setups mounted a single file at /app/config.yml and set group_add / DOCKER_GID. That still works unchanged. To switch to the simpler layout: move your config.yml into <INSPECTOR_DATA>/config/, replace the stack with the compose above, and update the stack.