Dockpeek: one-click access and image update checks for Docker container interfaces

Python and Flask run the backend despite JavaScript appearing as the primary language on GitHub

Dockpeek is a self-hosted dashboard for Docker environments. Its job is to replace the manual process of finding and opening container web interfaces: instead of remembering which port a container's admin panel lives on, you open the dashboard and click. Port mappings, live log streaming and image update checks all sit in the same browser view.

GitHub reports JavaScript as the primary language, but Python runs the application. requirements.txt lists Flask, Flask-Login, Flask-Cors, werkzeug, docker, packaging, gunicorn and gevent. Building from python:3.11-slim, the container runs via gunicorn with a configuration file at gunicorn.conf.py. JavaScript enters through the frontend build toolchain: package.json shows a single script that compiles Tailwind CSS from ./dockpeek/static/css/styles.css to ./dockpeek/static/css/tailwindcss.css using @tailwindcss/cli version 4.1.11. No Node.js runtime is in the application image; the Tailwind toolchain only produces the stylesheet.

That distinction matters when you want to understand the container's resource footprint or build from source. Python drives every feature the dashboard exposes. BUILDING.md is at the repository root for contributors, but no build steps are documented for a first-time setup.

SECRET_KEY, USERNAME and PASSWORD are required before the container starts listening on port 3420

Three environment variables are required: SECRET_KEY, USERNAME and PASSWORD. Inside the container the service listens on port 8000, and the compose file maps it to 3420 on the host.

services:
  dockpeek:
    image: dockpeek/dockpeek:latest
    container_name: dockpeek
    environment:
      - SECRET_KEY=your_secure_secret_key
      - USERNAME=admin
      - PASSWORD=admin
    ports:
      - "3420:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

After this compose file runs, the dashboard is available at the host's address on port 3420. Volume mounting the Docker socket gives Dockpeek its view of running containers, their ports, logs and image digests.

A discrepancy appears when comparing the README's basic setup with the docker-compose.yml file at the repository root. In the README's basic snippet, the socket appears without any flag, as above. docker-compose.yml adds :ro at the end of that same line: /var/run/docker.sock:/var/run/docker.sock:ro. Multi-host compose examples in the README also include :ro. A read-only socket mount prevents write operations to the Docker daemon from inside the container, which would affect features like triggering restarts or pulling updated images. Neither source explains the discrepancy, and neither is labeled as the authoritative configuration.

Authentication is a single USERNAME and PASSWORD pair, with no multi-user or role separation documented.

Traefik labels are read directly from existing container annotations without duplicating them for Dockpeek

Traefik integration is what the README calls zero configuration. When Traefik is running and its standard labels are already applied to your containers, Dockpeek reads those labels and extracts service URLs from them without any additional annotation. Containers already configured for Traefik need no Dockpeek-specific labels.

For containers not behind Traefik, automatic port mapping detects all published ports and builds links from them. Where the auto-detected scheme or URL is wrong, three labels allow per-container corrections. dockpeek.https forces HTTPS on specific ports, covering cases where a container runs TLS internally but publishes on a plain port number. dockpeek.link replaces the generated URL entirely, which handles endpoints at a path or subdomain that port detection cannot determine.

Where an endpoint is published by a mechanism that standard Docker port mapping does not capture, dockpeek.ports adds custom port entries alongside the ones Dockpeek detects.

Conflict resolution between Traefik labels and a dockpeek.link label is not documented. dockpeek.link is listed as a URL control label, but no documentation states whether it takes precedence over Traefik-derived URLs or whether both are shown.

A socket proxy restricts the Docker API calls Dockpeek can make, with ten explicit permission grants

Mounting the Docker socket directly gives Dockpeek full access to the Docker daemon API. For environments where that surface is too broad, a socket proxy option replaces the direct mount with a TCP connection that enforces per-permission grants.

The README shows lscr.io/linuxserver/socket-proxy:latest for this role, with tecnativa/docker-socket-proxy listed as an alternative. Ten permissions appear in the proxy's environment section: CONTAINERS=1, IMAGES=1, PING=1, VERSION=1, INFO=1, POST=1, ALLOW_START=1, ALLOW_STOP=1, ALLOW_RESTARTS=1 and NETWORKS=1.

socket-proxy:
  image: lscr.io/linuxserver/socket-proxy:latest
  container_name: dockpeek-socket-proxy
  environment:
    - CONTAINERS=1
    - IMAGES=1
    - PING=1
    - VERSION=1
    - INFO=1
    - POST=1
    - ALLOW_START=1
    - ALLOW_STOP=1
    - ALLOW_RESTARTS=1
    - NETWORKS=1
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  read_only: true
  tmpfs:
    - /run
  restart: unless-stopped

Dockpeek then connects via DOCKER_HOST=tcp://socket-proxy:2375. ALLOW_START, ALLOW_STOP, ALLOW_RESTARTS and POST are included to support the update and restart features. For setups that do not use those features, no documentation describes which specific grants to remove or what behavior changes when any individual one is absent.

Each additional Docker host gets a numbered group of three environment variables

Multi-host configuration is additive: each remote Docker host receives its own DOCKER_HOST_N_URL, DOCKER_HOST_N_NAME and DOCKER_HOST_N_PUBLIC_HOSTNAME variables. DOCKER_HOST_N_URL provides the socket address, unix:///var/run/docker.sock for a local socket or tcp:// followed by an IP and port for a remote one. DOCKER_HOST_N_NAME sets the label shown in the dashboard, and DOCKER_HOST_N_PUBLIC_HOSTNAME controls the hostname Dockpeek uses when building links to container interfaces on that host.

Both NAME and PUBLIC_HOSTNAME are optional. If NAME is omitted, Dockpeek attempts detection from the Docker API. If PUBLIC_HOSTNAME is absent, the host IP is used. Three hosts appear in the multi-host compose example: a local socket at unix:///var/run/docker.sock, a LAN machine at tcp://192.168.1.100:2375, and a Tailscale node at tcp://100.64.1.5:2375 with the Tailscale FQDN set as its PUBLIC_HOSTNAME.

Remote hosts need no Dockpeek installation. They only require the Docker API exposed over TCP, which in practice means running a socket proxy on each remote endpoint. Dockpeek need not be present on those machines.

No upper limit on the number of hosts is documented. A README comment reads "Continue pattern for additional hosts (4, 5, etc.)", indicating the series is open-ended beyond three, but no tested maximum appears in the repository.

Five container labels control tags, port display, link overrides and port-range grouping

Each individual container can carry up to five Dockpeek labels. dockpeek.tags accepts a string value that categorizes and filters containers in the dashboard view. dockpeek.ports adds custom port entries alongside the ones automatic detection finds, covering endpoints that standard Docker port mapping does not surface. dockpeek.port-range-grouping takes true or false and controls whether adjacent port numbers collapse into a single range display or appear individually.

For URL control, dockpeek.https forces HTTPS on specific ports, and dockpeek.link overrides the URL Dockpeek would otherwise generate. A container carrying no labels still appears in the dashboard; labels only change how it is presented or which URL opens on click.

No label controls visibility or access. There is no per-container mechanism to hide a container from the dashboard or restrict which authenticated user can reach it. Because authentication is a single USERNAME and PASSWORD pair, every logged-in user sees every container on every connected host.

Image update checking appears in screenshots with no prose description of what the update action does at the API level

Update checking is a headline feature: Dockpeek polls image registries to identify containers running outdated images and provides a dashboard mechanism to trigger upgrades. Screenshots in the README show both the checking state and the updates-available state. What the update action does at the Docker API level is absent from any prose section.

No description exists for whether the old image layer is retained after a pull, whether the container stops and gets recreated or is updated in place, or what happens if the new image fails its healthcheck. Dockpeek itself has a HEALTHCHECK in its Dockerfile that polls http://localhost:8000/health every 30 seconds, with a 15-second timeout, a 30-second start period and three retries. That covers Dockpeek's own process, not the containers it manages.

For a planned update to a production service, this gap matters. No rollback path is documented anywhere in the repository. The read-only socket mount used in docker-compose.yml and the write operations needed to pull images and recreate containers are in direct conflict, so confirming which socket configuration is actually in use is a prerequisite before triggering any update from the dashboard.

Editorial conclusion

Dockpeek suits a home lab or small self-hosted setup where the goal is one browser tab for container access and image updates across one or more hosts. Traefik label integration removes duplicated annotation for stacks already using that proxy. Two things to verify before deploying: the README and the docker-compose.yml disagree on whether the Docker socket should be mounted read-only (the compose file adds :ro, the README's basic snippet does not), and the update feature has no documented rollback path. If you plan to build from source, BUILDING.md is in the repository root, but the README gives no build steps.

Frequently asked questions

Official sources

1. dockpeek/dockpeek on GitHub
2. Issues
3. License: MIT
4. README
5. Releases