portracker

A self-hosted, real-time port monitoring and discovery tool.

By auto-discovering services on your systems, portracker provides a live, accurate map of your network. It helps eliminate manual tracking in spreadsheets and prevents deployment failures caused by port conflicts.

Key Features

• Automatic Port Discovery: Scans the host system to find and display running services and their ports automatically. No manual data entry is needed.
• Platform-Specific Collectors: Includes specialized collectors for Docker and TrueNAS to gather rich, contextual information from the host.
• Internal Port Detection: Distinguishes between internal container ports and published host ports, providing complete visibility into containerized services.
• Lightweight & Self-Contained: Runs as a single process with an embedded SQLite database. No external database dependencies like PostgreSQL or Redis are required.
• Peer-to-Peer Monitoring: Add other portracker instances as peers to view all your servers, containers, and VMs from a single dashboard.
• Hierarchical Grouping: Organize servers in a parent-child structure, perfect for nesting servers, e.g. a VM's portracker instance under its physical host.
• Enhanced TrueNAS Discovery: Providing an optional TrueNAS API key allows portracker to discover running VMs* and gather enhanced system information like the OS version and uptime.
• Modern & Responsive UI: A clean dashboard with light/dark modes, live filtering, and multiple data layout views (list, grid, table).

*Note: VMs discovered on TrueNAS with the optional API key are shown in read-only mode. To enable full monitoring, deploy a portracker instance on each VM and add it as a separate server.

Deployment

Deployment is designed to be simple using Docker.

Quick Get Started

Using Docker Compose:

Create a docker-compose.yml file:

…

Then, run the application:

docker-compose up -d

Using Docker Run:

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 with Docker Proxy

For enhanced security, you can run portracker without direct access to the Docker socket by using a proxy. This restricts the Docker API permissions to read-only operations.

Using Docker Compose:

…

Using Docker Run:

…

Configuration

Configure portracker using environment variables.

*Required

For a complete list of all environment variables with detailed explanations, see .env.example.

TrueNAS Integration

Getting Your TrueNAS API Key

1. Log into your TrueNAS web interface
2. Go to System Settings → API Keys
3. Click Add to create a new API key
4. Give it a descriptive name (e.g., "portracker")
5. Copy the generated key
6. Add it to portracker:
   • TrueNAS Apps: Edit your portracker app → Add Environment Variable: TRUENAS_API_KEY=your-api-key-here
   • Docker Compose: Add to environment section:
     yaml复制

     environment:
       - TRUENAS_API_KEY=your-api-key-here

What You'll See

With the API key configured, portracker will display:

• ✅ TrueNAS native apps (from Apps catalog)
• ✅ Virtual machines (VMs)
• ✅ LXC containers
• ✅ Enhanced system information (OS version, uptime, etc.)

Without the API key, you'll only see Docker containers and system ports.

For timeout configuration options, see .env.example.

Authentication Setup (v1.2.0+)

portracker includes optional authentication to secure dashboard access:

1. Enable Authentication: Set ENABLE_AUTH=true in your environment variables
2. First-Time Setup: On first access, you'll see a setup wizard to create the admin account
3. Login: Use your admin credentials to access the dashboard
4. Stay Logged In (optional): Set SESSION_SECRET to avoid being logged out on container restart

Example with Authentication:

services:
  portracker:
    image: mostafawahied/portracker:latest
    environment:
      - ENABLE_AUTH=true
      - SESSION_SECRET=your-random-secret-here-change-this

Important Notes:

• Authentication is disabled by default for backward compatibility
• With authentication disabled, anyone who can reach Portracker has administrator-level UI and API control; keep it on a trusted network or protect it with an authenticated reverse proxy
• When enabled, dashboard, settings, and integration endpoints require a signed-in session
• Peer data endpoints accept API key authentication for instance-to-instance communication
• API key authentication for peer-to-peer communication is available in v1.3.0
• Reverse proxies should preserve the public Host header; otherwise set CORS_ORIGIN to the exact public origin, including https://

Autoxpose Integration (v1.3.0+)

If you run autoxpose to manage your public-facing services, portracker can display which ports are publicly exposed alongside their internal addresses.

Setup:

1. Open Settings (gear icon in header)
2. Expand the autoxpose section
3. Enter your autoxpose URL (e.g., http://autoxpose:3000)
4. Click Connect

After upgrading to v1.3.11, reconnect an existing autoxpose integration once while signed in. Private LAN and container-DNS addresses remain supported. Loopback, link-local, reserved, credential-bearing, query-bearing, and redirecting destinations are rejected; use the autoxpose service name or LAN address instead of localhost.

What You'll See:

Once connected, exposed services show a public URL chip or globe badge next to the port:

• URL Mode: Full clickable chip showing photos.example.com
• Badge Mode: Compact globe icon with tooltip

Display Options:

• Display Mode: Toggle between URL chip or compact badge
• URL Style: Show subdomain only (compact) or full hostname

SSL Status Indicators:

Technical Stack

• Backend: Node.js, Express, WebSocket, better-sqlite3
• Frontend: React, Vite, Tailwind CSS, Shadcn UI
• Containerization: Docker

Roadmap

Future development is focused on improving the application based on community feedback. Key areas include:

• Adding user authentication ✅ Added in v1.2.0 (optional authentication with setup wizard)
• Adding API key authentication for peer-to-peer communication ✅ Added in v1.3.0
• autoxpose integration for public URL visibility ✅ Added in v1.3.0
• Expanding the library of platform-specific collectors for other host systems
• Addressing bugs and incorporating requested changes from the community

Star History

Contributing

Contributions are welcome! Please feel free to open an issue to report a bug or suggest a feature, or submit a pull request with your improvements.

License

This project is licensed under the MIT License - see the LICENSE