Stop Guessing Your Ports: Portracker Exposes Every Service Instantly

When was the last time you deployed a service only to watch it crash and burn because port 3000 was already taken? If you're like most developers and DevOps^{↗ Bright Coding Blog} engineers, you've got a spreadsheet somewhere—maybe three—that's supposed to track which ports run on which servers. It's outdated, it's wrong, and it's costing you time you don't have.

Here's the brutal truth: manual port tracking is a ticking time bomb. Every undocumented service, every "temporary" container running on port 8080, every VM that someone spun up and forgot to log—it's all shadow IT waiting to sabotage your next deployment. The worst part? You only discover the conflict when something breaks at 2 AM.

What if you could see every running service across your entire infrastructure in real-time? Not a static report from yesterday. Not a scan you have to remember to run. A living, breathing dashboard that updates automatically as services start and stop. That's exactly what portracker delivers—and it's why developers are quietly replacing their port spreadsheets with this open-source powerhouse.

What Is Portracker?

Portracker is an open-source, self-hosted, real-time port monitoring and discovery tool created by Mostafa Wahied. Built for developers who are tired of flying blind, it automatically scans host systems to discover running services and their ports, then presents everything in a clean, modern web dashboard.

Unlike enterprise network monitoring solutions that require weeks of configuration and a certification to operate, portracker is radically simple. It runs as a single process with an embedded SQLite database—no PostgreSQL^{↗ Bright Coding Blog} cluster, no Redis instance, no external dependencies to babysit. You deploy it, and it starts working immediately.

The tool has gained serious traction in the self-hosting and homelab communities because it solves a genuinely painful problem with minimal friction. It doesn't try to be everything to everyone. It does one thing exceptionally well: giving you complete visibility into what services are running where, on which ports, right now.

What makes portracker particularly compelling is its platform-aware intelligence. It doesn't just list open ports like a generic netstat wrapper. It understands Docker^{↗ Bright Coding Blog} containers, distinguishes internal container ports from published host ports, and even integrates with TrueNAS for enhanced system discovery. This contextual awareness transforms raw port data into actionable infrastructure intelligence.

Key Features That Set Portracker Apart

Let's dissect what makes portracker more than just another port scanner:

Automatic Port Discovery with Zero Configuration

Portracker's core engine continuously scans the host system to identify running services and their associated ports. No manual data entry. No CSV imports. No agent installation on every box. It reads process information directly from the system, giving you accurate, up-to-the-second visibility.

Platform-Specific Collectors for Deep Context

Generic tools give you numbers. Portracker gives you meaning. Its specialized collectors for Docker and TrueNAS gather rich contextual information:

Docker integration reveals container names, images, and the critical distinction between internal container ports and published host ports
TrueNAS API integration surfaces VMs, LXC containers, native apps, and enhanced system metadata like OS version and uptime

Peer-to-Peer Multi-Server Monitoring

Here's where portracker gets seriously powerful. You can add other portracker instances as peers and view all your servers, containers, and VMs from a single unified dashboard. Homelab with ten machines? No problem. Managing production and staging environments? One glance tells you the full story.

Hierarchical Infrastructure Grouping

Organization matters at scale. Portracker supports parent-child server relationships, perfect for nesting a VM's portracker instance under its physical host. This mirrors how your infrastructure actually works, not how some vendor thinks it should be categorized.

Lightweight, Self-Contained Architecture

The entire application runs as a single process with an embedded SQLite database. No external database dependencies. This isn't just convenient—it's a security and operational win. Fewer moving parts means fewer failure modes and a dramatically smaller attack surface.

Modern, Responsive Web Interface

The dashboard features light/dark modes, live filtering, and multiple data layout views (list, grid, table). It works beautifully on your laptop during incident response and on your phone when you're checking the homelab from bed.

Real-World Use Cases Where Portracker Shines

1. The Homelab Operator's Command Center

You've got Proxmox running VMs, TrueNAS handling storage, Docker hosting a dozen services, and maybe a Raspberry Pi or three. You can't remember what's on port 8123—is that Home Assistant or your experimental Node-RED flow? Portracker becomes your single source of truth, auto-discovering everything and showing you service names, not just port numbers.

2. Preventing Production Deployment Failures

Your CI/CD pipeline deploys a new microservice. It specifies port 8080. But that staging server already has Prometheus node-exporter on 8080 from three months ago that nobody documented. Portracker catches this before your deployment fails, because you've got real-time visibility into actual port usage, not theoretical documentation.

3. Container Environment Auditing

Docker's port mapping system is powerful but opaque. Internal port 80 becomes host port 32874 through ephemeral assignment, or maybe someone hardcoded -p 80:80 and now you've got a conflict. Portracker's internal vs. published port detection makes these mappings instantly visible, preventing the "works on my machine" surprises.

4. Multi-Site Infrastructure Consolidation

Running servers across cloud providers, colocation facilities, and your basement? Add a portracker instance to each, peer them together, and see your entire global infrastructure from one dashboard. The hierarchical grouping even lets you organize by site, by environment, or by organizational ownership.

5. TrueNAS Ecosystem Visibility

TrueNAS Scale's app ecosystem and virtualization capabilities are powerful but can become opaque. With API key integration, portracker reveals not just what's running in Docker, but native TrueNAS apps, VMs, and LXC containers—complete with system context that helps you understand resource relationships.

Step-by-Step Installation & Setup Guide

Portracker is designed for Docker-first deployment. Here's how to get running in under five minutes.

Prerequisites

Docker Engine 20.10+ or Docker Desktop
Docker Compose v2+ (recommended)
Linux, macOS, or Windows with WSL2

Quick Start with Docker Compose

Create a docker-compose.yml file with the following configuration:

services:
  portracker:
    image: mostafawahied/portracker:latest
    container_name: portracker
    restart: unless-stopped
    pid: "host"  # Required for port detection — allows reading host process namespace
    # Required permissions for system ports service namespace access
    cap_add:
      - SYS_PTRACE     # Linux hosts: read other PIDs' /proc entries for service identification
      - SYS_ADMIN      # Docker Desktop: allow namespace access for host ports (required for MacOS)
    security_opt:
      - apparmor:unconfined # Required for system ports — removes AppArmor restrictions
    volumes:
      # Required for data persistence across container restarts
      - ./portracker-data:/data
      # Required for discovering services running in Docker
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "4999:4999"
    # environment:
      # Optional: For enhanced TrueNAS features
      # - TRUENAS_API_KEY=your-api-key-here

Deploy with:

docker-compose up -d

Access your dashboard at http://localhost:4999.

Docker Run (Alternative)

For single-command deployment:

docker run -d \
  --name portracker \
  --restart unless-stopped \
  --pid host \
  --cap-add SYS_PTRACE \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  -p 4999:4999 \
  -v ./portracker-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  mostafawahied/portracker:latest

Enhanced Security: Docker Proxy Deployment

Direct Docker socket access is convenient but carries security implications. For production or security-conscious environments, use a read-only proxy:

services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy:latest
    container_name: portracker-docker-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1    # Allow reading container information
      - IMAGES=1        # Allow reading image information
      - INFO=1          # Allow reading Docker system info
      - NETWORKS=1      # Allow reading network configuration
      - POST=0          # CRITICAL: Disable all write operations (read-only)
    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  # Route through proxy instead of direct socket
    depends_on:
      - docker-proxy

This architecture eliminates direct socket exposure while preserving full discovery capabilities. The proxy restricts Docker API access to read-only operations, significantly reducing potential attack vectors.

Real Code Examples from the Repository

Let's examine practical implementations drawn directly from portracker's documentation.

Example 1: Production-Ready Compose with Authentication

Security shouldn't be an afterthought. Here's how to enable authentication for dashboard access:

services:
  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
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "4999:4999"
    environment:
      # Enable authentication — dashboard requires login
      - ENABLE_AUTH=true
      # Prevents session invalidation on container restart
      # Generate with: openssl rand -base64 32
      - SESSION_SECRET=your-random-secret-here-change-this

What's happening here? The ENABLE_AUTH=true flag activates portracker's built-in authentication system. On first access, you'll encounter a setup wizard to create the admin account. The SESSION_SECRET is critical for production: without it, every container restart invalidates all sessions, forcing re-authentication. Generate a cryptographically secure secret and treat it like any other credential.

Example 2: TrueNAS Integration with Full Environment Configuration

Maximize portracker's capabilities on TrueNAS Scale:

services:
  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
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "4999:4999"
    environment:
      # TrueNAS API integration — unlocks VM, LXC, and native app discovery
      - TRUENAS_API_KEY=your-api-key-here
      # Customize web server port if 4999 conflicts
      - PORT=4999
      # Database location inside container
      - DATABASE_PATH=/data/portracker.db
      # Include UDP ports in scans (default is TCP-only)
      - INCLUDE_UDP=true
      # Cache scan results for 60 seconds to reduce system load
      - CACHE_TIMEOUT_MS=60000

The TrueNAS API key transforms portracker's output. Without it, you see Docker containers and basic system ports. With it, you gain visibility into TrueNAS's native app catalog, virtual machines, and LXC containers—plus enriched system metadata. The INCLUDE_UDP=true flag is essential for services like DNS (port 53), SNMP, and QUIC protocols that many modern applications use.

Example 3: Docker Proxy Security Architecture

For environments where security hardening is non-negotiable:

# Step 1: Start the read-only 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

# Step 2: Start portracker with proxy connectivity
docker run -d \
  --name portracker \
  --restart unless-stopped \
  --pid host \
  --cap-add SYS_PTRACE \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  -p 4999:4999 \
  -v ./portracker-data:/data \
  -e DOCKER_HOST=tcp://localhost:2375 \
  mostafawahied/portracker:latest

This two-container pattern implements defense in depth. The tecnativa/docker-socket-proxy container exposes a filtered, read-only subset of the Docker API. The POST=0 environment variable is the critical security control—it blocks all write operations, preventing container creation, modification, or deletion even if portracker were compromised. Portracker connects via TCP to this restricted endpoint, maintaining full discovery capabilities without direct socket access.

Example 4: Autoxpose Integration for Public Service Visibility

Portracker v1.3.0+ integrates with autoxpose to display public-facing URLs:

services:
  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:
      # Connect to autoxpose for public URL discovery
      - AUTOXPOSE_URL=http://autoxpose:3000

After configuration via the Settings UI, exposed services display public URL chips or globe badges with SSL status indicators. The visual hierarchy instantly communicates:

🔒 Green lock: SSL secured and properly configured
⚠️ Amber warning: SSL pending or certificate issues
❌ Red cross: SSL error or misconfiguration

This integration bridges the gap between internal infrastructure visibility and external service exposure, critical for understanding your complete attack surface.

Advanced Usage & Best Practices

Optimize Scan Performance

The default CACHE_TIMEOUT_MS=60000 balances freshness with system load. For highly dynamic environments with frequent container churn, reduce to 30000. For stable production systems, increase to 300000 to minimize scanning overhead.

Secure Your Peer Network

When linking multiple portracker instances, use API key authentication (v1.3.0+) for peer-to-peer communication. Never expose portracker dashboards to the public internet without authentication enabled—treat it as infrastructure metadata that deserves protection.

Backup Strategy

The SQLite database at ./portracker-data/portracker.db contains your configuration and peer relationships. Include this path in your backup strategy. For zero-downtime migrations, stop the container, copy the data directory, and start on the new host.

Resource Monitoring

Portracker itself is lightweight, but the SYS_PTRACE and SYS_ADMIN capabilities grant significant system access. Monitor container resource usage and audit logs for unexpected behavior. The Docker proxy deployment pattern reduces this exposure substantially.

Comparison with Alternatives

Feature	Portracker	Nmap/Zenmap	Portainer	Netdata	Custom Scripts
Auto-discovery	✅ Native	⚠️ Manual scans	✅ Containers only	❌ Manual config	❌ Build yourself
Real-time updates	✅ WebSocket live	❌ Point-in-time	✅ Live	✅ Live	❌ Cron-based
Multi-server view	✅ Peer-to-peer	❌ Per-host	❌ Per-instance	⚠️ Complex setup	❌ Custom build
Docker context	✅ Deep integration	❌ Port only	✅ Full management	⚠️ Basic	❌ Manual parsing
TrueNAS integration	✅ Native API	❌ No	❌ No	❌ No	❌ No
External dependencies	❌ None (SQLite)	❌ None	⚠️ Requires agent	⚠️ Requires config	Varies
Deployment complexity	🟢 Single container	🟢 Binary	🟡 Multi-service	🟡 Multi-service	🔴 Custom code

Portracker wins where simplicity meets intelligence. Nmap is powerful but manual. Portainer manages containers beautifully but doesn't show system ports or peer across instances. Netdata monitors everything but requires extensive configuration for port-specific visibility. Portracker occupies the sweet spot: purpose-built for port and service discovery with minimal operational overhead.

Frequently Asked Questions

Is portracker free to use?

Yes. Portracker is released under the MIT License. You can use, modify, and deploy it commercially without cost. The full license is available in the GitHub repository.

Does portracker work on ARM architectures like Raspberry Pi?

The official Docker images are built for AMD64. For ARM deployment (Raspberry Pi, Apple Silicon), you may need to build from source or use buildx for multi-architecture images. Check the repository for community contributions or build instructions.

Can I monitor ports on remote servers without installing portracker on each?

Partially. The peer-to-peer system requires a portracker instance on each monitored host. However, once peered, you view everything from one dashboard. For pure remote port scanning without agents, you'd need a different architecture—portracker prioritizes accuracy and context over agentless convenience.

How does portracker handle security with elevated capabilities?

The SYS_PTRACE and SYS_ADMIN capabilities are necessary for reading process and namespace information. Mitigate risk by: using the Docker proxy pattern, running on dedicated monitoring hosts, keeping images updated, and enabling authentication. The capabilities are container-scoped, not host-wide root access.

What's the difference between internal and published Docker ports?

Internal ports are what a container exposes to its internal network (defined by EXPOSE in Dockerfile). Published ports are explicitly mapped to the host (-p flag). Portracker shows both, preventing confusion when a container's internal port 80 is actually reachable on host port 32874 or explicitly mapped to 8080.

Can I export or alert on portracker data?

Currently, portracker focuses on dashboard visualization. For alerting, consider integrating with your existing monitoring stack or using the API endpoints for peer communication as a foundation for custom scripts. The roadmap includes expanding integration capabilities based on community feedback.

How do I update portracker without losing data?

Pull the latest image and recreate the container. Your data persists in the mounted ./portracker-data volume. Always backup before major version updates:

docker-compose pull
docker-compose up -d

Conclusion: Your Infrastructure Deserves Visibility

You can't protect what you can't see, and you can't optimize what you don't know exists. Portracker solves the fundamental visibility gap that plagues every growing infrastructure—whether that's a single Docker host or a distributed multi-server environment.

What makes this tool genuinely exciting isn't just what it does today, but what it represents: infrastructure tooling that respects your time and intelligence. No sales calls. No enterprise licensing maze. No 200-page configuration guide. Just a clean, capable tool that solves a real problem and gets out of your way.

The peer-to-peer architecture, platform-specific collectors, and thoughtful integrations like autoxpose show a product vision that understands modern infrastructure complexity. This isn't a toy project—it's production-ready software built by someone who felt the same pain you do.

Stop maintaining port spreadsheets. Stop guessing during deployments. Stop discovering conflicts at 2 AM.

Deploy portracker today. Your future self—the one who can see every service across every server in real-time—will thank you.

⭐ Star portracker on GitHub and join the growing community of developers who've replaced infrastructure blindness with complete visibility.

Ready to eliminate port chaos? Clone the repository, run the Docker Compose example, and have your dashboard live in under five minutes. The only thing you'll regret is not doing it sooner.