Skip to content

An open source, self-hosted, real-time port monitoring and discovery tool.

chore: update readme

Mostafa-Wahied4e14f45c7ad8
diff --git a/.gitignore b/.gitignore
index e17b36d..c3f5751 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,17 +57,13 @@ validate-*.sh
# Docker
.dockerignore
-
-# Development documentation and process files
-
-# Test results and API testing artifacts
-backend/api-tests/
-backend/api-docs/
-
-# GitHub instructions (development process)
-.github/instructions/
-backend/api-tests/truenas/test-results/
-
-
-docker-compose-personal.yml
+docker-compose-*.yml
+docker-compose.*.yml
+*docker-compose.dev.yml
+.docker-compose-*.yml
+docker-compose.override.yml
+docker-compose.local.yml
+docker-compose.personal.yml
+.github/instructions
+backend/docker-compose.dev.yml
backend/Dockerfile.dev
diff --git a/README.md b/README.md
index 4a55d36..a160f46 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,7 @@ By auto-discovering services on your systems, portracker provides a live, accura
- **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.
@@ -38,24 +39,26 @@ By auto-discovering services on your systems, portracker provides a live, accura
Deployment is designed to be simple using Docker.
-### Option 1: Docker Compose (Recommended)
+### Quick Get Started
+
+**Using Docker Compose:**
Create a `docker-compose.yml` file:
```yaml
-version: "3.8"
-
services:
portracker:
image: mostafawahied/portracker:latest
container_name: portracker
restart: unless-stopped
- network_mode: "host"
+ pid: "host" # Required for comprehensive port detection
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:
- DATABASE_PATH=/data/portracker.db
- PORT=4999
@@ -69,15 +72,14 @@ Then, run the application:
docker-compose up -d
```
-### Option 2: Docker Run
-
-For a single-line command deployment:
+**Using Docker Run:**
```sh
docker run -d \
--name portracker \
--restart unless-stopped \
- --network host \
+ --pid host \
+ -p 4999:4999 \
-v ./portracker-data:/data \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-e DATABASE_PATH=/data/portracker.db \
@@ -85,6 +87,75 @@ docker run -d \
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:**
+
+```yaml
+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"
+ volumes:
+ - ./portracker-data:/data
+ ports:
+ - "4999:4999"
+ environment:
+ - DATABASE_PATH=/data/portracker.db
+ - PORT=4999
+ - DOCKER_HOST=tcp://docker-proxy:2375
+ depends_on:
+ - docker-proxy
+```
+
+**Using Docker Run:**
+
+```sh
+# 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
+
+# Start Portracker
+docker run -d \
+ --name portracker \
+ --restart unless-stopped \
+ --pid host \
+ -p 4999:4999 \
+ -v ./portracker-data:/data \
+ -e DATABASE_PATH=/data/portracker.db \
+ -e PORT=4999 \
+ -e DOCKER_HOST=tcp://localhost:2375 \
+ mostafawahied/portracker:latest
+```
+
## Configuration
Configure `portracker` using environment variables.
@@ -111,6 +182,7 @@ Configure `portracker` using environment variables.
Future development is focused on improving the application based on community feedback. Key areas include:
+- Adding user authentication.
- Expanding the library of platform-specific collectors for other host systems.
- Addressing bugs and incorporating requested changes from the community.
diff --git a/backend/docker-compose.dev.yml b/backend/docker-compose.dev.yml
deleted file mode 100644
index 49c5096..0000000
--- a/backend/docker-compose.dev.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-services:
- backend:
- build:
- context: .
- dockerfile: Dockerfile.dev
- working_dir: /app
- volumes:
- # Mount your source code (read-write for live updates)
- # Exclude node_modules from this mount, as it's handled by the named volume
- - .:/app:rw
- # Use a named volume for node_modules to persist them and keep them isolated
- - backend_node_modules:/app/node_modules
- # Optional: if your local collector needs access to the host's Docker socket
- - /var/run/docker.sock:/var/run/docker.sock
- # The CMD in Dockerfile.dev will be used (npm run dev)
- # If you need to override, you can use 'command:' here
- ports:
- - "3000:3000" # Exposed on ALL host IPs
- environment:
- - NODE_ENV=development
- - DATABASE_PATH=/app/data/ports-tracker.db # Ensure this path is used by db.js
- - RUNNING_IN_DOCKER=true # Explicitly set here, will override Dockerfile ENV if different
- # For Linux hosts if host.docker.internal is not available by default:
- # extra_hosts:
- # - "host.docker.internal:host-gateway"
-
-# Define the named volume
-volumes:
- backend_node_modules:
- # Optional: if you want to persist database data separately
- # backend_data:
diff --git a/docker-compose.yml b/docker-compose.yml
index a279475..cdbbd3f 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,50 +1,108 @@
-version: '3.8'
-
services:
portracker:
- build: .
- image: portracker:latest
+ image: mostafawahied/portracker:latest
container_name: portracker
restart: unless-stopped
- # network_mode: "host"
- pid: "host" # Access host PID namespace
- cap_add:
- - SYS_PTRACE # For process inspection
- - SYS_ADMIN # For nsenter if needed
+ # Required for comprehensive system port detection
+ # This allows Portracker to see all host processes for accurate port mapping
+ pid: "host"
volumes:
- - /var/run/docker.sock:/var/run/docker.sock:ro
+ # Required: Data persistence for SQLite database
- ./portracker-data:/data
- - /proc:/host/proc:ro # Mount host /proc
- - /sys:/host/sys:ro # Mount host /sys filesystem (optional but helpful)
+
+ # Required: Docker socket access for container discovery
+ # Comment out if using docker-proxy setup below
+ - /var/run/docker.sock:/var/run/docker.sock:ro
+
+ # Advanced: Host filesystem access (usually not needed with pid: "host")
+ # Uncomment only if you experience issues with port detection
+ # - /proc:/host/proc:ro
+ # - /sys/fs/cgroup:/host/sys/fs/cgroup:ro
ports:
- "${HOST_PORT:-4999}:4999"
environment:
- # CORE CONFIGURATION
+ # CORE CONFIGURATION (Required)
- DATABASE_PATH=/data/portracker.db
- PORT=4999
- - NODE_ENV=production
- - DATA_DIR=/data
- - HOST_PROC=/host/proc # Tell the app where to find host /proc
+
+ # DOCKER CONFIGURATION
+ # Uncomment to use with docker-proxy for enhanced security
+ # - DOCKER_HOST=tcp://docker-proxy:2375
# TRUENAS INTEGRATION (Optional)
+ # Uncomment and set your API key for enhanced TrueNAS features:
+ # - VM discovery and monitoring
+ # - Enhanced system information
+ # - TrueNAS-specific optimizations
# - TRUENAS_API_KEY=your-api-key-here
- # PERFORMANCE SETTINGS
- - CACHE_TIMEOUT_MS=60000 # Cache duration (60 seconds)
- - DISABLE_CACHE=false # Set to 'true' to disable caching
- - INCLUDE_UDP=true # Set to 'true' to include UDP ports
+ # PERFORMANCE SETTINGS (Optional)
+ # Cache duration - increase for better performance, decrease for fresher data
+ - CACHE_TIMEOUT_MS=60000
+ # Disable caching entirely (not recommended for production)
+ # - DISABLE_CACHE=true
- # DEBUGGING
- - DEBUG=true # Set to 'true' for verbose logging
+ # ADVANCED PORT SCANNING (Optional)
+ # Include UDP ports in scans (may increase noise and impact performance)
+ # - INCLUDE_UDP=true
+ # DEVELOPMENT & DEBUGGING (Optional)
+ # Enable verbose logging for troubleshooting
+ # - DEBUG=true
+ # Optional: Health check for monitoring
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4999/api/health"]
interval: 30s
timeout: 10s
start_period: 30s
- retries: 3
\ No newline at end of file
+ retries: 3
+
+ # OPTIONAL: Enhanced Security with Docker Socket Proxy
+ # Uncomment the entire section below for additional Docker socket security
+ # This adds a proxy layer between Portracker and the Docker socket
+
+ # docker-proxy:
+ # image: tecnativa/docker-socket-proxy:latest
+ # container_name: portracker-docker-proxy
+ # restart: unless-stopped
+ # environment:
+ # # Only allow read operations Portracker needs
+ # - CONTAINERS=1
+ # - IMAGES=1
+ # - INFO=1
+ # - NETWORKS=1
+ # # Disable write operations for security
+ # - 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"
+
+ # When using docker-proxy:
+ # 1. Uncomment the entire docker-proxy service above
+ # 2. Comment out the /var/run/docker.sock volume mount in portracker service
+ # 3. Uncomment the DOCKER_HOST environment variable in portracker service
+ # 4. Add depends_on to portracker service:
+ # depends_on:
+ # - docker-proxy
+
+# Optional: Custom networks for isolation
+# networks:
+# portracker:
+# driver: bridge
+
+# Optional: Named volumes for better data management
+# volumes:
+# portracker-data:
+# driver: local
\ No newline at end of file