|
| 1 | +# WUD (What's Up Docker?) |
| 2 | + |
| 3 | +WUD watches Docker containers, checks their image registries for newer versions, and displays available updates in a web dashboard. This template runs WUD 9.5.0 with persistent SQLite storage and a Docker socket proxy that permits monitoring requests and blocks Docker writes. Notifications are optional; automatic container updates are not configured. |
| 4 | + |
| 5 | +Official documentation: [Quick start](https://getwud.app/docs/quickstart/), [configuration](https://getwud.app/docs/configuration/), [Docker watcher](https://getwud.app/docs/configuration/watchers/), and [source code](https://github.com/getwud/wud). |
| 6 | + |
| 7 | +## Deploy in Dokploy |
| 8 | + |
| 9 | +1. Import the template. Dokploy generates `WUD_AUTH_ADMIN_PASSWORD`; the username defaults to `admin`. Keep the generated password private, or replace it with your own strong value. |
| 10 | +2. Enable **Isolated Deployment** for this Compose service before deploying. Dokploy should place WUD and its socket proxy on the stack's private network. Do not add a domain or publish a port for `wud-socket-proxy`. |
| 11 | +3. Set your domain to service `wud`, port `3000`, and enable HTTPS with HTTP redirection in Dokploy. Traefik terminates TLS; WUD uses HTTP inside the stack. |
| 12 | +4. Deploy and wait for both services to become healthy. Open the domain and sign in using the values from the Environment tab. |
| 13 | +5. Inspect the Containers page. The local watcher monitors running containers on the Docker host where this stack is deployed, excluding Dokploy infrastructure by default as described below. Registry checks run hourly, with up to 60 seconds of jitter. Use the UI's watch action when you need an immediate scan. |
| 14 | + |
| 15 | +No external database, registry account, notification service, or password-hashing command is required. Public registries work anonymously within their rate limits. Large hosts or frequent scans may need registry credentials. |
| 16 | + |
| 17 | +## Monitoring scope and Docker access |
| 18 | + |
| 19 | +### Dokploy infrastructure is ignored by default |
| 20 | + |
| 21 | +The template adds this editable filter to Dokploy's Environment tab: |
| 22 | + |
| 23 | +```dotenv |
| 24 | +WUD_WATCHER_DOCKER_LOCAL_EXCLUDE=^dokploy([._-]|$) |
| 25 | +``` |
| 26 | + |
| 27 | +It skips version tracking for containers named `dokploy` or beginning with `dokploy-`, `dokploy_`, or `dokploy.`. This covers standard Dokploy infrastructure names such as `dokploy-traefik`, `dokploy-postgres`, and `dokploy-redis`, including their usual Compose/Swarm suffixes. Dokploy upgrades remain managed through Dokploy. |
| 28 | + |
| 29 | +This is a **container-name** filter. Your application databases and other workloads with different names are still monitored; an application deliberately named with a matching `dokploy` prefix is also excluded. Customize the expression if your infrastructure uses different names. |
| 30 | + |
| 31 | +To track Dokploy infrastructure too, remove the entire `WUD_WATCHER_DOCKER_LOCAL_EXCLUDE` line from Dokploy's Environment tab, save, and redeploy. Do not leave an empty `WUD_WATCHER_DOCKER_LOCAL_EXCLUDE=` entry: WUD rejects empty filter values. Then select **Containers → Watch now** to run a fresh scan. To include just one excluded container, add `wud.watch: "true"` to that service's Docker labels and recreate it; this explicit label takes precedence over the exclusion filter. |
| 32 | + |
| 33 | +### Other monitoring controls |
| 34 | + |
| 35 | +`WUD_WATCHER_DOCKER_LOCAL_WATCHBYDEFAULT=true` discovers running containers that pass the filter. Set it to `false` for opt-in monitoring, then add `wud.watch: "true"` to each monitored service's Docker labels. A `wud.watch: "false"` label excludes a container. These labels belong on the services being monitored, not in WUD's Environment tab. |
| 36 | + |
| 37 | +Stopped containers are excluded by default. Set `WUD_WATCHER_DOCKER_LOCAL_WATCHALL=true` to include them. Optional include/exclude patterns, tag filters, digest tracking, and release links are covered in [environment.md](environment.md) and the [container label guide](https://getwud.app/docs/configuration/watchers/labels/). |
| 38 | + |
| 39 | +Only the proxy mounts `/var/run/docker.sock`. This system socket is the intentional host bind mount; it must already exist on a normal Linux Docker host. WUD connects to `wud-socket-proxy:2375`, with container/image reads and Docker events allowed. `POST=0` blocks write methods, including container start/stop, exec, image pulls, and deletion. A read-only socket mount alone would not block those Docker API operations. |
| 40 | + |
| 41 | +Container inspection can expose host workload metadata and environment values, so keep proxy access within the isolated stack. Do not expose port 2375 or broaden proxy permissions for normal monitoring. This template observes one Docker host; it does not automatically discover remote Dokploy servers or configure a Swarm/Kubernetes watcher. |
| 42 | + |
| 43 | +## Notifications and updates |
| 44 | + |
| 45 | +Add notification variables in Dokploy's Environment tab, then redeploy. WUD loads optional values from `.env`. For example, an optional Ntfy trigger needs: |
| 46 | + |
| 47 | +```dotenv |
| 48 | +WUD_TRIGGER_NTFY_ALERTS_URL=https://ntfy.sh |
| 49 | +WUD_TRIGGER_NTFY_ALERTS_TOPIC=your-private-topic |
| 50 | +``` |
| 51 | + |
| 52 | +Use your server's authentication settings where needed. See the official [trigger documentation](https://getwud.app/docs/configuration/triggers/) for supported providers and required credentials. No notification provider is required to install WUD. |
| 53 | + |
| 54 | +Watcher, registry, and trigger settings are configured through the environment; their configuration pages in WUD display the effective settings. User accounts, preferences, and API tokens can be managed in the app. |
| 55 | + |
| 56 | +The template does not configure Docker or Docker Compose update triggers. Keep changes to Dokploy-managed applications in Dokploy so its deployment configuration stays authoritative. Adding an updater would require a separate, deliberate change to the proxy permissions and deployment design. Triggers can run automatically when configured; do not add a Docker updater merely to test notifications. |
| 57 | + |
| 58 | +## Passwords, persistence, and backups |
| 59 | + |
| 60 | +WUD reapplies `WUD_AUTH_ADMIN_USER` and `WUD_AUTH_ADMIN_PASSWORD` on every startup, including an existing account. Rotate this administrator's password in Dokploy's Environment tab and redeploy. Changing only that account's password in WUD will be overwritten on the next restart. Additional users are stored in the database and can be managed in WUD. |
| 61 | + |
| 62 | +The `wud-data` volume stores `/store`, including `wud.sqlite`, its WAL files, users, token hashes, preferences, monitored containers, history, and snoozes. Keep one WUD instance per volume. Back up the complete volume while WUD is stopped, or use a SQLite-aware backup method. Copying only the live `wud.sqlite` file can miss recent writes in the WAL. Keep an off-server copy and protect it as sensitive data. |
| 63 | + |
| 64 | +The official image handles store creation and migrations. It runs as root; this template drops all Linux capabilities and prevents privilege escalation. Do not force a different UID without preparing and checking volume ownership. Back up before changing the pinned image version and review the [release notes](https://github.com/getwud/wud/releases). |
| 65 | + |
| 66 | +### HTTPS and health behavior in 9.5.0 |
| 67 | + |
| 68 | +Use HTTPS and HTTP redirection for regular access. WUD 9.5.0 sets an HttpOnly session cookie, but its upstream implementation does not add Secure or SameSite cookie attributes. This template does not modify the published application image. You may need to sign in again after a container recreation or upgrade because WUD derives its session secret from the version and network interface. |
| 69 | + |
| 70 | +GET `/health` is public HTTP liveness. It does not prove that Docker discovery or registry checks succeeded: also check the local watcher, discovered containers, and scan errors. The API and dashboard require authentication. |
| 71 | + |
| 72 | +See [environment.md](environment.md) for settings and [testing.md](testing.md) for verification steps. |
0 commit comments