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`](./compose.yml):

   ```yaml
   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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), 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](#4-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`) |
| `PORTAINER_API_TOKEN` | A Portainer access token. Only needed if you use **Portainer stack redeploy** for VPN-routed apps; see the in-app guide (Help → Portainer). | No |

## 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](https://gitea.euronvault.com/euronvault/inspector/releases)
and in the [CHANGELOG](./CHANGELOG.md).

**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.