Portracker on Linux

🎯 What Portracker Does

Portracker is an open‑source pePortracker continuously scans the host system and identifies:

• Running services
• Open ports
• Container‑exposed and internal ports
• Service metadata (names, labels, mounts, env vars)

It eliminates the need for spreadsheets or manual port tracking and helps prevent deployment failures caused by port conflicts.

⚡ Key Features

• Automatic Port Discovery: Finds running services and their ports without manual input
• Remote Agent Support: Install the agent on additional systems and monitor them all from the server
• Real‑time Updates: The UI reflects changes instantly as services start or stop
• Complete Port Visibility: Shows all ports, including internal container ports, not just published ones
• Service Renaming: Assign custom names to discovered services directly from the UI
• Batch Actions: Hide, rename, or annotate multiple services or ports at once
• Container Details Drawer: View real‑time stats, labels, mounts, and environment variables for any container

🚀 Docker Installation Steps

1. Update your system
   sudo apt update && sudo apt upgrade -y
2. Install Docker
   

   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh

3. Install Docker Compose
   sudo apt install docker-compose-plugin
4. Add your user to the Docker group
   sudo usermod -aG docker $USER
5. Enable Docker at boot
   sudo systemctl enable docker
6. Reboot
   sudo reboot
7. Test Docker
   docker run hello-world

📁 Setup Portracker

mkdir ~/docker
mkdir ~/docker/portracker

🧾 Docker Compose File

On the server, in ~/docker/portracker create docker-compose.yml

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:
      - DATABASE_PATH=/data/portracker.db
      - PORT=4999
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4999/api/health"]
      interval: 30s
      timeout: 10s
      start_period: 30s
      retries: 3

On each agent system, use this compse file:

services:
  portracker:
    image: mostafawahied/portracker:latest
    container_name: portracker_agent
    restart: unless-stopped
    
    # Required to see processes on the host machine
    pid: "host"

    # Privileges needed for port detection
    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:
      - DATABASE_PATH=/data/portracker.db
      - PORT=4999
      # Optional: Give this agent a nickname so it looks good in the peer list
      # - NODE_NAME=Remote-Node-02
    
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4999/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

▶️ Start Portracker

On the server and each agent, from within ~/docker/portracker run:

📜 View Logs

On the server, run:

On each agent run:

🌐 Access Web Interface

Open your browser and go to "http://<YOUR_SERVER_IP_ADDRESS>:4999

You should see your server. Click on Add Server in the lower left hand corner. The Add New Server screen will open. Give it a name, type in the AGENT_IP_ADDRESS:4999 and click on Add Server. Repeat for each agent.

You will see the main server and each agent down the left hand side. Click on the one you want to use and its data will show up.

The most useful feature is Generate Port. This will give you a free port to use.