Feature/fix unknown system ports (#46)

* fix: fixed unknown system ports

* fix: fix inconsistent system ports indicator

* chore: update version to 1.1.0 and document backend changes in changelog

Author: mostafa-wahied

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to Portracker will be documented in this file.
 
+## [1.1.0] - 2025-08-23
+
+### Frontend & Backend
+- **System Port Name Fix**: Fixed the issue where system ports were incorrectly displayed as "unknown".
+- **Consistent Status Indicators**: Improved status indicators for system ports to ensure consistency.
+
 ## [1.0.8] - 2025-08-20
 
 ### Frontend

README.md

@@ -51,17 +51,21 @@ services:
     image: mostafawahied/portracker:latest
     container_name: portracker
     restart: unless-stopped
-    pid: "host"  # Required for comprehensive port detection
+    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:
-      - DATABASE_PATH=/data/portracker.db
-      - PORT=4999
+    # environment:
       # Optional: For enhanced TrueNAS features
       # - TRUENAS_API_KEY=your-api-key-here
 ```
@@ -79,11 +83,12 @@ 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 \
-  -e DATABASE_PATH=/data/portracker.db \
-  -e PORT=4999 \
   mostafawahied/portracker:latest
 ```
 
@@ -115,13 +120,16 @@ services:
     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:
-      - DATABASE_PATH=/data/portracker.db
-      - PORT=4999
       - DOCKER_HOST=tcp://docker-proxy:2375
     depends_on:
       - docker-proxy
@@ -148,10 +156,11 @@ 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 \
-  -e DATABASE_PATH=/data/portracker.db \
-  -e PORT=4999 \
   -e DOCKER_HOST=tcp://localhost:2375 \
   mostafawahied/portracker:latest
 ```
@@ -192,4 +201,4 @@ Contributions are welcome! Please feel free to open an issue to report a bug or
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](https://github.com/Mostafa-Wahied/portracker/blob/main/LICENSE)
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/Mostafa-Wahied/portracker/blob/main/LICENSE)

backend/collectors/docker_collector.js

@@ -605,6 +605,10 @@ class DockerCollector extends BaseCollector {
       return ports;
     } catch (nsenterErr) {
       this.logInfo(`nsenter method failed: ${nsenterErr.message}, trying alternative methods`);
+      const msg = String(nsenterErr?.message || '').toLowerCase();
+      if (msg.includes('permission denied') || msg.includes('operation not permitted') || msg.includes('exit code 1')) {
+        this.logWarn('Hint: nsenter requires cap_add: [SYS_ADMIN] to access the host network namespace on Docker Desktop (macOS/Windows).');
+      }
 
       try {
         const { stdout: netNsCheck } = await execAsync("readlink /proc/self/ns/net 2>/dev/null");

backend/collectors/truenas_collector.js

@@ -647,6 +647,10 @@ class TrueNASCollector extends BaseCollector {
       }
     } catch (nsenterErr) {
       this.logWarn(`nsenter method failed: ${nsenterErr.message}`);
+      const msg = String(nsenterErr?.message || '').toLowerCase();
+      if (msg.includes('permission denied') || msg.includes('operation not permitted') || msg.includes('exit code 1')) {
+        this.logWarn('Hint: nsenter requires cap_add: [SYS_ADMIN] to access the host network namespace on Docker Desktop (macOS/Windows).');
+      }
     }
 
     this.logError('All port collection methods failed');

backend/index.js

@@ -1965,7 +1965,7 @@ app.post("/api/notes/batch", (req, res) => {
 });
 
 app.get("/api/ping", async (req, res) => {
-  const { host_ip, host_port, target_server_url, owner, internal, container_id } = req.query;
+  const { host_ip, host_port, target_server_url, owner, internal, container_id, source } = req.query;
   const serverId = req.query.server_id;
   const currentDebug = req.query.debug === "true";
 
@@ -1997,6 +1997,7 @@ app.get("/api/ping", async (req, res) => {
         if (host_ip) params.set('host_ip', host_ip);
         if (host_port) params.set('host_port', host_port);
         if (owner) params.set('owner', owner);
+        if (source) params.set('source', source);
         if (currentDebug) params.set('debug', 'true');
         const url = `${base}/api/ping?${params.toString()}`;
         const resp = await fetch(url, { headers: { 'accept': 'application/json' } });
@@ -2054,14 +2055,14 @@ app.get("/api/ping", async (req, res) => {
     });
   }
 
-  if (serviceInfo.type === 'system') {
+  if (serviceInfo.type === 'system' || source === 'system') {
     return res.json({
       reachable: true,
       status: 'system',
       color: 'gray',
-      title: serviceInfo.description,
-      serviceType: serviceInfo.type,
-      serviceName: serviceInfo.name
+      title: source === 'system' ? 'System service' : serviceInfo.description,
+      serviceType: 'system',
+      serviceName: source === 'system' ? 'System Service' : serviceInfo.name
     });
   }