Port monitoring and service discovery on a host machine can be surprisingly tedious, especially when juggling multiple containers and network services. Portracker addresses this by automating port discovery and monitoring, packaging it in a lightweight, self-hosted tool that integrates tightly with Docker and TrueNAS environments.
what portracker does and how it works
Portracker is a JavaScript-based port monitoring and discovery application designed for self-hosted setups. It automatically scans the host system to detect running services and their exposed ports, removing the need for manual tracking or external tools.
The core architecture centers around an embedded SQLite database, which means no additional database dependencies or external services are required. This simplifies deployment and reduces operational overhead.
Portracker’s stack is Docker-first, with official Docker images and orchestration examples provided. It integrates deeply with Docker through a socket proxy pattern, allowing it to query container information securely and efficiently.
Additionally, it supports TrueNAS-specific collectors to enrich metadata about running services on TrueNAS systems, which is a niche but valuable feature for users in those environments.
A standout feature is the peer-to-peer federation support, enabling multiple Portracker instances across servers to share data and create unified dashboards. The UI is designed with usability in mind, offering light and dark modes and multiple layout views.
why portracker’s docker socket proxy pattern and architecture matter
Portracker’s approach to Docker integration is worth understanding for anyone working with containerized monitoring tools. Instead of granting the application full access to the Docker socket (which is a common but risky pattern), it uses a Docker socket proxy.
This proxy runs as a separate container, exposing a read-only HTTP API that limits Docker API calls to safe operations like querying containers, images, networks, and info. This is a clear security improvement, reducing the attack surface while maintaining necessary functionality.
Under the hood, the Docker socket proxy container mounts the host’s Docker socket as read-only and filters requests via environment variables specifying allowed API scopes. Portracker then connects to this proxy over TCP, avoiding direct socket access.
This pattern is a practical tradeoff between convenience and security. Many tools simply bind-mount the Docker socket with full privileges, which can lead to privilege escalation risks. Portracker’s design shows how to implement least-privilege access effectively.
The codebase reflects these concerns: the Docker Compose setup includes explicit capabilities (SYS_PTRACE, SYS_ADMIN) and security options (apparmor:unconfined) to enable necessary operations, but the socket proxy shields Docker from write operations.
Beyond Docker, Portracker’s embedded SQLite database keeps its footprint small and deployment straightforward—no external DB server or complex configuration needed. This choice favors simplicity and ease of maintenance over scaling to massive environments.
The peer-to-peer federation feature is another nice touch, enabling multi-host monitoring without a central server. This could be useful in homelab setups or small clusters.
quick start with docker and authentication
Portracker provides a clear Docker Compose example for secure deployment with the Docker socket proxy and optional authentication added in v1.2.0.
Using Docker Compose:
services:
docker-proxy:
image: tecnativa/docker-socket-proxy:latest
container_name: portracker-docker-proxy
restart: unless-stopped
environment:
- CONTAINERS=1
- IMAGES=1
- INFO=1
- NETWORKS=1
- POST=0
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
ports:
- "2375:2375"
portracker:
image: mostafawahied/portracker:latest
container_name: portracker
restart: unless-stopped
pid: "host"
cap_add:
- SYS_PTRACE
- SYS_ADMIN
security_opt:
- apparmor:unconfined
volumes:
- ./portracker-data:/data
ports:
- "4999:4999"
environment:
- DOCKER_HOST=tcp://docker-proxy:2375
depends_on:
- docker-proxy
Using Docker Run:
# Start the Docker proxy
docker run -d \
--name portracker-docker-proxy \
--restart unless-stopped \
-p 2375:2375 \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-e CONTAINERS=1 \
-e IMAGES=1 \
-e INFO=1 \
-e NETWORKS=1 \
-e POST=0 \
tecnativa/docker-socket-proxy:latest
Authentication can be enabled to secure dashboard access:
services:
portracker:
image: mostafawahied/portracker:latest
environment:
- ENABLE_AUTH=true
- SESSION_SECRET=your-random-secret-here-change-this
This setup requires a first-time admin account creation via a setup wizard, adding a layer of security for multi-user environments.
verdict: who should consider portracker
Portracker fills a niche for self-hosted port discovery and monitoring, especially in environments where Docker containers and TrueNAS systems are prevalent. Its lightweight design, embedded SQLite backend, and Docker socket proxy security pattern make it a practical choice for small to medium setups.
It’s not designed for massive scale or complex enterprise monitoring but shines in homelabs, small clusters, or teams wanting full control over their port monitoring without external dependencies.
The security-conscious Docker proxy approach is a valuable reference for anyone building Docker-integrated tools, showing a clear path to reducing privileges while maintaining functionality.
If you need a simple, easy-to-deploy port monitor with multi-server federation and some niche TrueNAS support, Portracker is worth a look. The code is clean, the architecture is straightforward, and the UX is polished enough for daily use.
Limitations include the reliance on Docker and TrueNAS specific collectors, so bare-metal or other container runtimes may require additional work. Also, the embedded SQLite backend may not scale well beyond modest setups.
Overall, Portracker is a solid toolbox addition for infrastructure monitoring enthusiasts who value security and simplicity.
→ GitHub Repo: mostafa-wahied/portracker ⭐ 2,104 · JavaScript