dockpeek/dockpeekPublic

NotificationsYou must be signed in to change notification settings
Fork73
Star1.7k

Easily access your Docker container web interfaces and keep them up to date — across all your hosts.

License

MIT license

1.7k stars 73 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 447 Commits
.github		.github
deploy		deploy
dockpeek		dockpeek
screenshots		screenshots
.dockerignore		.dockerignore
.gitignore		.gitignore
BUILDING.md		BUILDING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
config.py		config.py
docker-compose-multi-sockets.yml		docker-compose-multi-sockets.yml
docker-compose-socket.yml		docker-compose-socket.yml
docker-compose-swarm-socket.yml		docker-compose-swarm-socket.yml
docker-compose.yml		docker-compose.yml
gunicorn.conf.py		gunicorn.conf.py
package-lock.json		package-lock.json
package.json		package.json
requirements.txt		requirements.txt
run.py		run.py
tailwind.config.js		tailwind.config.js

Repository files navigation

Dockpeek

Quick Access & Easy Updates for Your Docker Containers

Dockpeek is a lightweight, self-hosted Docker dashboard for quick access to your containers. Open web interfaces, view logs, monitor ports, and update images — all from one clean, intuitive interface. It automatically detects Traefik labels and works out of the box with zero configuration.

✨ Key Features

One-click web access — Instantly open your containers’ dashboards and web apps
Automatic port mapping — Detect and display all published ports
Live container logs — Stream logs in real time
Traefik integration — Automatically extract service URLs from labels
Multi-host management — Control multiple Docker daemons from one interface
Image update checks — Detect and upgrade outdated containers

🏷️Labels Support

Add labels to your containers to tag them, customize their appearance, or control how dockpeek interacts with them.

dockpeek.https — Force HTTPS protocol for specific ports
dockpeek.link — Turn container names into clickable links
dockpeek.ports — Add custom ports to display alongside detected ones
dockpeek.port-range-grouping — Controlport range grouping (true/false)
dockpeek.tags — Organize and categorize containers with custom tags

Container logs view

Checking for updates

Updates available

Light mode

🔧 Installation

Basic Setup (Recommended)

The easiest way to get started with dockpeek:

services:dockpeek:image:dockpeek/dockpeek:latestcontainer_name:dockpeekenvironment:      -SECRET_KEY=your_secure_secret_key# Required: Set a secure secret key      -USERNAME=admin# username      -PASSWORD=admin# password# Server name for UI (optional, auto-detected from Docker API if not set)#  - DOCKER_HOST_NAME=ports:      -"3420:8000"volumes:      -/var/run/docker.sock:/var/run/docker.sockrestart:unless-stopped

Tip

You can add labels to your other containers to tag them or control how dockpeek interacts with them.

Learn more aboutavailable dockpeek labels.

Option 2: Socket Proxy

For enhanced security, use a socket proxy to limit Docker API access:

services:dockpeek:image:dockpeek/dockpeek:latestcontainer_name:dockpeekenvironment:      -SECRET_KEY=your_secure_secret_key      -USERNAME=admin      -PASSWORD=admin      -DOCKER_HOST=tcp://socket-proxy:2375# Connect via socket proxyports:      -"3420:8000"depends_on:      -socket-proxyrestart:unless-stoppedsocket-proxy:# alternative: tecnativa/docker-socket-proxyimage:lscr.io/linuxserver/socket-proxy:latestcontainer_name:dockpeek-socket-proxyenvironment:      -CONTAINERS=1      -IMAGES=1      -PING=1      -VERSION=1      -INFO=1      -POST=1# Required for container updates      -ALLOW_START=1      -ALLOW_STOP=1      -ALLOW_RESTARTS=1      -NETWORKS=1volumes:      -/var/run/docker.sock:/var/run/docker.sockread_only:truetmpfs:      -/runrestart:unless-stopped

🌐 Multi-Host Setup

Manage multiple Docker hosts from a single dashboard:

services:dockpeek:image:dockpeek/dockpeek:latestcontainer_name:dockpeekrestart:unless-stoppedports:      -"3420:8000"environment:      -SECRET_KEY=your_secure_secret_key      -USERNAME=admin      -PASSWORD=admin# --- Docker Host 1 (Local) ---      -DOCKER_HOST_1_URL=unix:///var/run/docker.sock# Local Docker socket# DOCKER_HOST_1_NAME= is Optional: Auto-detected from Docker API if not set# DOCKER_HOST_1_PUBLIC_HOSTNAME= is optional; uses host IP by default# --- Docker Host 2 (Remote Server) ---      -DOCKER_HOST_2_URL=tcp://192.168.1.100:2375# Remote socket proxy      -DOCKER_HOST_2_NAME=Production Server# Optional: Auto-detected from Docker API if not set      -DOCKER_HOST_2_PUBLIC_HOSTNAME=server.local# Optional: Custom hostname for links# --- Docker Host 3 (Tailscale) ---      -DOCKER_HOST_3_URL=tcp://100.64.1.5:2375# Tailscale IP      -DOCKER_HOST_3_NAME=Remote VPS# Optional: Auto-detected from Docker API if not set      -DOCKER_HOST_3_PUBLIC_HOSTNAME=vps.tailnet.ts.net# Optional: Tailscale FQDN# --- Continue pattern for additional hosts (4, 5, etc.) ---volumes:# Required only if you are connecting to a local socket      -/var/run/docker.sock:/var/run/docker.sock:ro

Tip

Dockpeek does not need to be installed on remote devices.Each remote host only needs the Docker API exposed over TCP (e.g. via a Docker Socket Proxy).

⚙️ Configuration

Required Environment Variables

Variable	Description
`SECRET_KEY`	Required. Essential for application functionality and session security
`USERNAME`	Required. Username for dashboard login
`PASSWORD`	Required. Password for dashboard login

Optional Configuration

Variable	Default	Description
`PORT`	`8000`	Port on which the application listens
`DISABLE_AUTH`	`false`	Set to`true` to disable authentication
`DOCKER_HOST`	Local socket	Primary Docker connection URL
`DOCKER_HOST_NAME`	Auto-detected	Display name for the primary server (auto-detected from Docker API if not set)
`DOCKER_HOST_PUBLIC_HOSTNAME`	Auto-detected	Optional hostname or IP for generating clickable links
`DOCKER_CONNECTION_TIMEOUT`	`2`	Connection timeout in seconds (eg.`0.5`,`5`) for Docker host discovery
`UPDATE_FLOATING_TAGS`	`disabled`	Update check mode:`latest`,`major` (e.g.,`8.3.3` →`8`), or`minor` (e.g.,`8.3.3` →`8.3`) (default: exact tags)
`TRUST_PROXY_HEADERS`	`false`	Set to`true` to enable proxy header support (X-Forwarded-*)
`TRUSTED_PROXY_COUNT`	`1`	Number of trusted proxies when`TRUST_PROXY_HEADERS=true`
`TRAEFIK_LABELS`	`true`	Set to`false` to hide Traefik column
`TAGS`	`true`	Set to`false` to hide tags column
`PORT_RANGE_GROUPING`	`true`	Set to`false` to disable port range grouping globally
`PORT_RANGE_THRESHOLD`	`5`	Minimum number of consecutive ports to group as a range (seePort Range Grouping)
`CUSTOM_REGISTRY_TEMPLATES`	`{}`	URL templates for custom/private registries using`{0}`,`{1}`,`{2}` placeholders (seeCustom Registry Templates)

Multi-Host Variables

For additional Docker hosts, use the patternDOCKER_HOST_N_*:

Variable	Description
`DOCKER_HOST_N_URL`	Docker API URL (e.g.,`tcp://host:2375`)
`DOCKER_HOST_N_NAME`	Display name in the dashboard (auto-detected from Docker API if not set)
`DOCKER_HOST_N_PUBLIC_HOSTNAME`	Optional public hostname for links

Important

Important Configuration Requirements:

SECRET_KEY must always be set - dockpeek will not function without it
USERNAME andPASSWORD are required unlessDISABLE_AUTH=true
Multi-host variables require matchingN identifiers (URL, name, hostname)

Custom Registry Templates

Dockpeek supports custom URL templates for private or self-hosted Docker registries like Gitea, Harbor, or GitLab. This makes registry icons clickable and links directly to your registry's web interface.

Configuration:

environment:  -|    CUSTOM_REGISTRY_TEMPLATES={      "git.example.com": {"urlTemplate": "https://git.example.com/{1}/-/packages/container/{2}"},      "harbor.company.com": {"urlTemplate": "https://harbor.company.com/harbor/projects/{1}/repositories/{2}"}    }

How it works:

The placeholders{0},{1},{2}, etc. are replaced with parts of your image name:

For an image likegit.example.com/myuser/myapp:latest:

{0} =git.example.com (registry host)
{1} =myuser (first path component)
{2} =myapp (second path component)
{3},{4}, etc. for deeper paths if needed

Port Range Grouping

Dockpeek automatically groups consecutive ports into ranges for cleaner display. For example, ports 601, 602, 603, 604, 605, 606 will be displayed as a single range "601-606" instead of individual port badges.

Per-Container Configuration:

labels:  -"dockpeek.port-range-grouping=false"# Disable for this container  -"dockpeek.port-range-grouping=true"# Enable for this container (overrides global)

🏷️ Container Labels

Customize how containers appear and behave in dockpeek:

services:webapp:image:nginx:latestports:      -"3001:80"labels:      -"dockpeek.ports=8080,9090"# Show additional ports      -"dockpeek.https=3001,8080"# Force HTTPS for these ports      -"dockpeek.link=https://myapp.local"# Make container name clickable      -"dockpeek.tags=frontend,production"# Add organization tags

Available Labels

Label	Purpose	Example
`dockpeek.ports`	Show additional ports	`dockpeek.ports=8080,9090`
`dockpeek.https`	Force HTTPS for ports	`dockpeek.https=9002,3000`
`dockpeek.link`	Custom container link	`dockpeek.link=https://app.com`
`dockpeek.port-range-grouping`	Control port range grouping	`dockpeek.port-range-grouping=false`
`dockpeek.tags`	tags	`dockpeek.tags=web,prod`

🐳 Docker Swarm Support

Dockpeek natively supports Docker Swarm, You can deploy dockpeek as a stack, with a single socket-proxy instance, and view/manage all Swarm services and tasks in the dashboard. This configuration is ideal for production clusters using Traefik as an ingress proxy.

Click to see Example stack file (docker-compose-swarm-socket.yml)

services:dockpeek:image:dockpeek/dockpeek:latestenvironment:      -SECRET_KEY=your_secure_secret_key      -USERNAME=admin      -PASSWORD=admin      -TRAEFIK_LABELS=true      -DOCKER_HOST=tcp://tasks.socket-proxy:2375# Connect to Swarm manager via socket-proxyports:      -"3420:8000"networks:      -traefik      -dockpeek-internaldeploy:replicas:1labels:        -"traefik.enable=true"        -"traefik.http.routers.dockpeek.rule=Host(`dockpeek.example.com`)"        -"traefik.http.routers.dockpeek.entrypoints=websecure"        -"traefik.http.routers.dockpeek.tls=true"        -"traefik.http.services.dockpeek.loadbalancer.server.port=8000"socket-proxy:image:lscr.io/linuxserver/socket-proxy:latestenvironment:      -CONTAINERS=1      -IMAGES=1      -PING=1      -VERSION=1      -INFO=1      -POST=1      -SERVICES=1# Enable Swarm services API      -TASKS=1# Enable Swarm tasks API      -NODES=1# Enable Swarm nodes APIvolumes:      -/var/run/docker.sock:/var/run/docker.sock:ro      -type:tmpfstarget:/runtmpfs:size:100000000networks:      -socket-proxydeploy:replicas:1placement:constraints:          -node.role == managernetworks:socket-proxy:traefik:external:true

How it works:

The dockpeek and socket-proxy services share a private network for secure API access.
The traefik network is external and should be pre-created by your Traefik deployment.
Traefik labels on dockpeek expose the dashboard securely at your chosen domain.
The DOCKER_HOST variable points to the socket-proxy service, which must run on a Swarm manager node.
Dockpeek will auto-detect Swarm mode and show all services/tasks in the dashboard, with all the usual features (port mapping, Traefik integration, update checks, etc.).

Deploy with:

docker stack deploy -c docker-compose-swarm-socket.yml dockpeek

FAQ

Answers to common questions:

Why do I see "Swarm mode" and no containers?

Dockpeek detected that Docker is running inSwarm mode, which changes how containers are managed (as "services" instead of standalone containers).
If you’renot intentionally using Docker Swarm, you can safely leave swarm mode with:
docker swarm leave --force
After running this command, refresh dockpeek — your regular containers should appear again.

How do I search for containers by port?

Use the format:port in the search box. For example, typing:8080 will show all containers exposing port 8080.

How do I search for available ports?

Use the:free search syntax to find the next available port:
:free — Returns the next free port after the lowest occupied port
:free 3420 — Returns the next free port starting from port 3420 or higher
The search works per server when a specific server is selected, or across all servers when "All" is selected.
Click the copy button next to the result to copy the port number to your clipboard.

When does dockpeek use HTTPS automatically?

Dockpeek automatically uses HTTPS for:
Container port443/tcp
Host ports ending with443 (e.g.,8443,9443)
Ports specified with thedockpeek.https label

How do I make container names clickable?

Use thedockpeek.link label:
labels:  -"dockpeek.link=https://myapp.example.com"
This is especially useful with reverse proxies to link directly to public addresses.

How can I add ports for containers without port mapping?

Some containers (like those using host networking or behind reverse proxies) don't expose ports through Docker's standard port mapping. Use thedockpeek.ports label:
labels:  -"dockpeek.ports=8096,8920"

How does port range grouping work?

Dockpeek automatically detects consecutive ports and groups them into ranges for cleaner display:
Input: 601, 602, 603, 604, 605, 606, 8080, 9000
Output: 601-606, 8080, 9000
Configure threshold:
environment:  -PORT_RANGE_THRESHOLD=3# Only group 3+ consecutive ports
Disable globally:
environment:  -PORT_RANGE_GROUPING=false
Disable per-container:
labels:  -"dockpeek.port-range-grouping=false"

How do I check updates for pinned versions like 8.2.2-alpine?

Use theUPDATE_FLOATING_TAGS environment variable:
Available modes:
latest - always checks thelatest tag
major - for8.2.2 checks8
minor - for8.2.2 checks8.2
disabled (default) - checks exact tag
environment:  -UPDATE_FLOATING_TAGS=major# Checks 8-alpine instead of exact 8.2.2-alpine

How do I enable X-Forwarded-* headers behind a proxy?

Enable proxy header support with these environment variables:
environment:  -TRUST_PROXY_HEADERS=true  -TRUSTED_PROXY_COUNT=1# Number of proxies between client and dockpeek
This allows dockpeek to correctly handle X-Forwarded-* headers (including X-Forwarded-Prefix for subpath deployments) from proxies.

How do I clear the search filter?