euronvault/inspector
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release v0.8.0 — Portainer-first install, in-app guide

Browse Source 
- Install from Portainer with no command line: paste the compose, set a
  folder and a password, deploy. Inspector creates its own config and
  detects Docker socket permissions by itself.
- Illustrated how-to guide inside the app (Help tab) and in the repo.
- Containers added in the UI are watched right away, no restart.
- maintenance_window switch on the container form.
- README with logo and screenshots; INSTALL rewritten for Portainer.
This commit is contained in:
Europium 63 committed 2026-10-27 15:45:33 -07:00
1 parent 4c05a4d565
commit c603e86e75
21 files changed
+789 -202
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

INSTALL.md
+115 -50
View File
@@ -1,70 +1,135 @@
# Install
# Installing Inspector with Portainer
Inspector watches Docker containers, restarts the ones you tell it to,
and notifies you via Gotify and/or Pushover. All configuration lives in
a single `config.yml` that you can edit by hand or from the built-in web
settings page.
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.
## Requirements
**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.
- Docker Engine 24+ and `docker compose` v2.
- A machine that can reach `/var/run/docker.sock` (any Docker host).
- Optional: a Gotify server and/or a Pushover account for notifications.
---
## Quickstart
## 1. Create the stack
```bash
# 1. Grab the compose file and example config
mkdir -p ~/docker/inspector && cd ~/docker/inspector
curl -L -o compose.yml https://gitea.euronvault.com/euronvault/inspector/raw/branch/main/compose.yml
curl -L -o config.yml https://gitea.euronvault.com/euronvault/inspector/raw/branch/main/config.example.yml
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):
# 2. Edit config.yml — at minimum, list the containers you want watched
# under the `containers:` key.
$EDITOR config.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}
```
# 3. Set your Docker group GID so the container can read the socket.
echo "DOCKER_GID=$(getent group docker | cut -d: -f3)" > .env
## 2. Set the environment variables
# 4. Pull and run
docker compose pull
docker compose up -d
docker compose logs -f inspector
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
```
If `dashboard.enabled: true` in your config, visit
`http://<host>:8080/` after startup to see the dashboard, and
`http://<host>:8080/settings` to edit the config from the browser.
| 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`) |
## Pinning a version
## 3. Deploy and sign in
Prefer an immutable tag over `latest` in production:
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).
```bash
# .env
INSPECTOR_TAG=0.7.0
```
That's it. Inspector picks up new containers on its next check (within a minute).
Images are published at `gitea.euronvault.com/euronvault/inspector`.
---
## Upgrading
## 4. Updating
```bash
docker compose pull
docker compose up -d
```
1. **Stacks → inspector → Editor**.
2. Click **Update the stack** and turn on **Re-pull image and redeploy**.
3. Confirm.
Your `config.yml` is persisted outside the container, so upgrades don't
touch it. The settings page keeps a `.bak` of the previous file next to
`config.yml` on every save (when the directory is bind-mounted; see the
README for the Docker caveat).
Your settings and history live in `INSPECTOR_DATA`, so updates never touch them.
## Uninstall
**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).
```bash
docker compose down
rm -rf logs data config.yml compose.yml .env
```
**Rolling back.** Set `INSPECTOR_TAG` to the previous version and update the
stack with **Re-pull image and redeploy** on.
Inspector doesn't store anything outside the directory it was started
from.
## 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.