portracker Documentation

repository·main·Indexed 25 days ago

https://github.com/mostafa-wahied/portracker

A self-hosted, multi-platform port-tracking dashboard and discovery tool (v1.3.10) that automatically maps running services and ports on a host system. It features Docker and system collectors, TrueNAS integration for VM and LXC discovery, and autoxpose support for public URL visibility. The tool includes an API for port scanning, unused port generation, and management of service overrides, notes, and custom names.

Tokens: 10.9K
Snippets: 8
Records: 54
Agent score: 82%

What's inside portracker

Quick Start with portracker using Docker Compose

main

To deploy portracker quickly, create a docker-compose.yml file with the following configuration. Note that specific flags like pid: "host", cap_add, and security_opt are required for the application to detect system ports and access the host namespace.

Key requirements for successful deployment:

pid: "host": Required for port detection.
cap_add: SYS_PTRACE (for Linux hosts to read /proc entries) and SYS_ADMIN (required for Docker Desktop on MacOS).
security_opt: apparmor:unconfined is required for system ports.
volumes: Mount a local directory to /data for SQLite persistence and mount /var/run/docker.sock for Docker service discovery.

services:
  portracker:
    image: mostafawahied/portracker:latest
    container_name: portracker
    restart: unless-stopped
    pid: "host"  # Required for port detection
    # Required permissions for system ports service namespace access
    cap_add:
      - SYS_PTRACE     # Linux hosts: read other PIDs' /proc entries
      - SYS_ADMIN      # Docker Desktop: allow namespace access for host ports (required for MacOS)
    security_opt:
      - apparmor:unconfined # Required for system ports
    volumes:
      # Required for data persistence
      - ./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

Quick Start with portracker using Docker Run

main

You can run portracker as a standalone container using the following command. Ensure you include the necessary capabilities and volume mounts for port detection and data persistence.

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

Enable Authentication in portracker
main
Authentication (available since v1.2.0) secures your dashboard.
1. Set ENABLE_AUTH=true in your environment variables.
2. On your first visit, use the setup wizard to create an admin account.
3. To prevent being logged out when the container restarts, set a persistent SESSION_SECRET.
Note: Authentication is disabled by default. When enabled, the dashboard requires login, but API endpoints for peer-to-peer communication remain accessible.
```
services:
  portracker:
    image: mostafawahied/portracker:latest
    environment:
      - ENABLE_AUTH=true
      - SESSION_SECRET=your-random-secret-here-change-this
```
https://github.com/mostafa-wahied/portracker/blob/main/README.md
Integrate TrueNAS for enhanced discovery
main
By providing a TRUENAS_API_KEY, portracker can discover more than just Docker containers. It can identify TrueNAS native apps, Virtual Machines (VMs), and LXC containers, and gather enhanced system info like OS version and uptime.
Setup Steps:
1. In TrueNAS: System Settings → API Keys → Add.
2. Copy the generated key.
3. Add it to portracker via the TRUENAS_API_KEY environment variable.
Note: VMs discovered via the TrueNAS API are shown in read-only mode. For full monitoring of a VM, you must deploy a separate portracker instance on that VM and add it as a peer.
https://github.com/mostafa-wahied/portracker/blob/main/README.md

Secure portracker with a Docker Socket Proxy

main

To avoid giving portracker direct access to the Docker socket, use tecnativa/docker-socket-proxy. This restricts the Docker API to read-only operations. You must configure portracker to use the proxy via the DOCKER_HOST environment variable.

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

Integrate autoxpose for public URL visibility
main
If you use autoxpose, portracker can display which ports are publicly exposed alongside their internal addresses.
Setup:
1. Open Settings (gear icon) in the portracker dashboard.
2. Expand the autoxpose section.
3. Enter your autoxpose URL (e.g., http://autoxpose:3000) and click Connect.
Display Modes:
- URL Mode: Shows a clickable chip with the full URL (e.g., 🌐 photos.example.com 🔒).
- Badge Mode: Shows a compact globe icon with a tooltip.
SSL Status Indicators:
- 🔒 (Green): SSL secured
- ⚠️ (Amber): SSL pending
- ❌ (Red): SSL error
https://github.com/mostafa-wahied/portracker/blob/main/README.md
How service type detection works
main
PortTracker uses a multi-layered approach to identify what is running on a port:
1. Well-Known Ports: It checks against a hardcoded map of common services (e.g., 22 for SSH, 80 for HTTP, 3306 for MySQL).
2. Owner Metadata: If the port owner (e.g., a Docker container name) contains keywords like nginx, mysql, or sshd, it assigns a corresponding type (Web Server, Database, etc.).
3. Port Ranges: If no owner is found, it uses common port ranges (e.g., 80/443/8080 are 'Web Service', ports < 1024 are 'System Service').
4. Fallback: If no patterns match, it is labeled as a generic 'Service'.
https://github.com/mostafa-wahied/portracker/blob/main/backend/index.js

Deploy Portracker via Docker Compose

main

To run Portracker, use the following docker-compose.yml configuration. Note that specific host settings like pid: "host" and certain capabilities are required for the application to accurately map host processes and ports.

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"

Enhance Docker security with docker-socket-proxy
main
Instead of mounting /var/run/docker.sock directly into the Portracker container, you can use tecnativa/docker-socket-proxy to provide a read-only API layer. This is more secure as it limits the container's access to specific Docker operations.
Steps to implement:
1. Uncomment the docker-proxy service in your compose file.
2. Comment out the /var/run/docker.sock volume mount in the portracker service.
3. Uncomment the DOCKER_HOST environment variable in the portracker service and set it to tcp://docker-proxy:2375.
4. Add depends_on: [docker-proxy] to the portracker service.
```
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
    - BUILD=0
    - COMMIT=0
    - EXEC=0
    - SWARM=0
    - EVENTS=0
    - VOLUMES=0
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
  ports:
    - "2375:2375"
```
https://github.com/mostafa-wahied/portracker/blob/main/docker-compose.yml
Configure the Autoxpose client via environment variables
main
The AutoxposeClient can be configured using the following environment variables:
- AUTOXPOSE_URL: The base URL for the Autoxpose service.
- AUTOXPOSE_ENABLED: Set to 'true' to enable the client.
- AUTOXPOSE_CACHE_TTL_MS: The time-to-live for the internal cache in milliseconds (defaults to 30000).
- DEBUG: Set to 'true' to enable debug logging for the client.
https://github.com/mostafa-wahied/portracker/blob/main/backend/lib/autoxpose-client.js

Configure Port Generation via Environment Variables

main

You can control the behavior of the port suggestion engine using the following environment variables:

Variable	Default	Description
`GENERATE_PORT_MIN`	`30000`	Minimum port number for suggestions
`GENERATE_PORT_MAX`	`60999`	Maximum port number for suggestions
`GENERATE_PORT_BIND_HOST`	`0.0.0.0`	Host to use when testing port availability via TCP bind
`ENDPOINT_CACHE_PORTS_TTL_MS`	`3000`	TTL for the `/api/ports` endpoint cache in milliseconds

Configure Portracker environment variables

main

Portracker can be customized using several environment variables. These cover core database/port settings, authentication, performance, and integrations.

# CORE CONFIGURATION (Required)
DATABASE_PATH=/data/portracker.db
PORT=4999
HOST_PROC=/host/proc

# AUTHENTICATION (Optional)
ENABLE_AUTH=true
SESSION_SECRET=your-random-secret-here

# PERFORMANCE
CACHE_TIMEOUT_MS=60000
DISABLE_CACHE=true

# ADVANCED
INCLUDE_UDP=true
DEBUG=true

# INTEGRATIONS
TRUENAS_API_KEY=your-api-key-here
DOCKER_HOST=tcp://docker-proxy:2375
HOST_OVERRIDE=your-server-hostname