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 time zone**, e.g. `America/New_York` or `Europe/Berlin`. Without it Inspector uses UTC, so the maintenance window, alerts and dashboard times are off by your UTC offset. See [Why the time zone matters](#why-the-time-zone-matters). | **Yes** (default `UTC`) |
| `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 |

### Why the time zone matters

Inspector uses `TZ` for every time it shows or acts on. If it's wrong, things
still work, but at the wrong hour or with confusing times:

- **The maintenance window runs in this time zone.** A window of `02:00–05:00`
  with `TZ` left at UTC runs at 02:00 UTC, which is the middle of the evening in
  the Americas or mid-morning in Asia. Inspector would then restart containers
  during your nightly backups, and ignore real problems during the day.
- **Alerts** (Gotify / Pushover) show the time of the problem in this zone, with
  its abbreviation, e.g. `10-28 03:15 AM CET`.
- **The dashboard and Events page** show times in this zone, and the Events
  page's days run midnight to midnight in this zone.
- **Logs** are stamped in this zone.

**How to set it:** use your zone's name from the
[list of time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
("TZ identifier" column), e.g. `America/New_York`, `America/Chicago`,
`Europe/London`, `Europe/Berlin`, `Australia/Sydney`. Abbreviations like `EST` or
`CET` don't work. On Unraid, **Settings → Date and Time** shows the zone your
server uses.

**How to check it:** the bottom of every Settings page shows
`time zone: <name>`. If it says `UTC` and you're not on UTC, set `TZ` in the
stack and click **Update the stack**. If the name you set isn't recognized,
Inspector logs a warning and uses UTC.

## 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. |
| Times are a few hours off, or the maintenance window runs at the wrong time | `TZ` is missing or wrong. Check `time zone:` at the bottom of Settings, set `TZ` to your zone name (e.g. `Europe/London`), and update the stack. |
| 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.