An open source, self-hosted, real-time port monitoring and discovery tool.
chore: update readme
Mostafa-Wahied4e14f45c7ad8
diff --git a/.gitignore b/.gitignoreindex 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.ymlbackend/Dockerfile.devdiff --git a/README.md b/README.mdindex 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, accuraDeployment 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:latestcontainer_name: portrackerrestart: unless-stopped- network_mode: "host"+ pid: "host" # Required for comprehensive port detectionvolumes:# 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:**```shdocker 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+```+## ConfigurationConfigure `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.ymldeleted file mode 100644index 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.ymlindex 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:latestcontainer_name: portrackerrestart: 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:roports:- "${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 monitoringhealthcheck:test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4999/api/health"]interval: 30stimeout: 10sstart_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