An open source, self-hosted, real-time port monitoring and discovery tool.
fix: improve TrueNAS timeout handling (#70)
Mostafa Wahied1de310f442dc
diff --git a/.env.example b/.env.examplenew file mode 100644index 0000000..f6b2666--- /dev/null+++ b/.env.example@@ -0,0 +1,123 @@+# ===================================+# CORE CONFIGURATION+# ===================================++# Server port+PORT=4999++# Enable debug logging for troubleshooting+DEBUG=false++# ===================================+# DOCKER CONFIGURATION+# ===================================++# Docker host connection (use with docker-proxy for security)+# DOCKER_HOST=tcp://docker-proxy:2375++# Docker socket path (default: /var/run/docker.sock)+# DOCKER_SOCK=/var/run/docker.sock++# Docker TLS verification (1=enabled, 0=disabled)+# DOCKER_TLS_VERIFY=0++# Docker certificate path for TLS+# DOCKER_CERT_PATH=/path/to/certs++# Docker API cache timeouts (milliseconds)+DOCKER_CACHE_CONTAINERS_TTL_MS=4000+DOCKER_CACHE_INSPECT_TTL_MS=5000+DOCKER_CACHE_STATS_TTL_MS=1500+DOCKER_CACHE_PORTS_TTL_MS=4000++# ===================================+# TRUENAS INTEGRATION+# ===================================++# TrueNAS API key for enhanced features (VMs, containers, system info)+# Get this from TrueNAS UI: System Settings > API Keys+# TRUENAS_API_KEY=++# TrueNAS WebSocket base URL (auto-detected if not set)+# Examples: ws://192.168.1.100:80, wss://truenas.local:443+# TRUENAS_WS_BASE=++# Overall timeout for enhanced features collection (milliseconds)+# Increase if you see timeout errors (systems with many apps/VMs may need 120000-180000)+TRUENAS_TIMEOUT_MS=90000++# Individual API call timeouts (advanced tuning)+# Only adjust these if specific API calls timeout (check logs for which call failed)+# - system.info: Basic system information (rarely slow)+TRUENAS_SYSTEM_INFO_TIMEOUT_MS=30000+# - app.query: TrueNAS apps (slow with 20+ apps, increase to 45000-60000)+TRUENAS_APP_QUERY_TIMEOUT_MS=20000+# - vm.query: Virtual machines (increase if you have many VMs)+TRUENAS_VM_QUERY_TIMEOUT_MS=15000+# - virt.instance.query: LXC containers (increase if you have many containers)+TRUENAS_CONTAINER_QUERY_TIMEOUT_MS=15000++# WebSocket request timeout (should be >= longest individual timeout)+# Increase if individual timeouts are increased+TRUENAS_WS_REQUEST_TIMEOUT_MS=40000++# ===================================+# AUTHENTICATION+# ===================================++# Enable authentication to protect dashboard access+ENABLE_AUTH=false++# Session secret for secure cookie signing+# Generate a strong random string for production+# If not set, a random secret is generated (sessions won't persist across restarts)+# SESSION_SECRET=++# Enable recovery mode for password reset+# A time-limited recovery code will appear in logs (valid 15 minutes)+RECOVERY_MODE=false++# ===================================+# CACHING & PERFORMANCE+# ===================================++# Disable all caching (not recommended for production)+DISABLE_CACHE=false++# Generic collector cache timeout+COLLECTOR_CACHE_TTL_MS=30000++# System collector cache timeouts+SYSTEM_CACHE_SYSTEMINFO_TTL_MS=15000+SYSTEM_CACHE_PORTS_TTL_MS=5000++# Endpoint-level cache timeout for ports+ENDPOINT_CACHE_PORTS_TTL_MS=3000++# Port cache timeout+PORT_CACHE_TTL_MS=5000++# Cache debug logging (for development)+CACHE_DEBUG=false+CACHE_DEBUG_VERBOSE=false++# ===================================+# PORT SCANNING & DETECTION+# ===================================++# Include UDP ports in system scans (may increase noise)+INCLUDE_UDP=false++# Host /proc filesystem path (for containerized deployments)+# HOST_PROC=/host/proc++# ===================================+# PORT GENERATION+# ===================================++# Random port generator range+GENERATE_PORT_MIN=30000+GENERATE_PORT_MAX=60999++# Bind host for port availability testing+GENERATE_PORT_BIND_HOST=0.0.0.0diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bff8b06..7562594 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,12 @@All notable changes to portracker will be documented in this file.+## [1.2.2] - 2025-12-12++### Performance & Reliability++- **TrueNAS Integration**: Improved timeout handling with parallel API calls, granular per-call timeouts, and connection reuse for reliable VM and container collection+## [1.2.1] - 2025-11-21### Performance & Reliabilitydiff --git a/README.md b/README.mdindex c13e3c0..dea6110 100644--- a/README.md+++ b/README.md@@ -33,7 +33,7 @@ By auto-discovering services on your systems, portracker provides a live, accura- **Enhanced TrueNAS Discovery**: Providing an optional TrueNAS API key allows `portracker` to discover running VMs\* and gather enhanced system information like the OS version and uptime.- **Modern & Responsive UI**: A clean dashboard with light/dark modes, live filtering, and multiple data layout views (list, grid, table).-<sub>\*_Note: VMs discovered on TrueNAS with the optional API key are shown in read-only mode. To enable full monitoring, deploy a Portracker instance on each VM and add it as a separate server._</sub>+<sub>\*_Note: VMs discovered on TrueNAS with the optional API key are shown in read-only mode. To enable full monitoring, deploy a portracker instance on each VM and add it as a separate server._</sub>## Deployment@@ -94,7 +94,7 @@ docker run -d \### 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.+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:**@@ -151,7 +151,7 @@ docker run -d \-e POST=0 \tecnativa/docker-socket-proxy:latest-# Start Portracker+# Start portrackerdocker run -d \--name portracker \--restart unless-stopped \@@ -175,7 +175,7 @@ Configure `portracker` using environment variables.| `DATABASE_PATH`\* | Path inside the container to the SQLite database file. | `/data/portracker.db` || `TRUENAS_API_KEY` | Optional API key for enhanced TrueNAS data collection. | ` ` || `ENABLE_AUTH` | Set to `true` to enable authentication (v1.2.0+). | `false` |-| `SESSION_SECRET` | Secret key for session encryption (recommended when auth enabled). | _random_ |+| `SESSION_SECRET` | Only needed with auth enabled. Prevents logout on container restart. | _random_ || `CACHE_TIMEOUT_MS` | Duration in milliseconds to cache scan results. | `60000` || `DISABLE_CACHE` | Set to `true` to disable all caching. | `false` || `INCLUDE_UDP` | Set to `true` to include UDP ports in scans. | `false` |@@ -183,14 +183,50 @@ Configure `portracker` using environment variables.<sub>\*_Required_</sub>+For a complete list of all environment variables with detailed explanations, see [`.env.example`](.env.example).++### TrueNAS Integration++<details>+<summary><strong>Click to expand TrueNAS setup guide</strong></summary>++#### Getting Your TrueNAS API Key++1. Log into your TrueNAS web interface+2. Go to **System Settings → API Keys**+3. Click **Add** to create a new API key+4. Give it a descriptive name (e.g., "portracker")+5. Copy the generated key+6. Add it to portracker:+ - **TrueNAS Apps**: Edit your portracker app → Add Environment Variable: `TRUENAS_API_KEY=your-api-key-here`+ - **Docker Compose**: Add to environment section:+ ```yaml+ environment:+ - TRUENAS_API_KEY=your-api-key-here+ ```++#### What You'll See++With the API key configured, portracker will display:+- ✅ TrueNAS native apps (from Apps catalog)+- ✅ Virtual machines (VMs)+- ✅ LXC containers+- ✅ Enhanced system information (OS version, uptime, etc.)++Without the API key, you'll only see Docker containers and system ports.++For timeout configuration options, see [`.env.example`](.env.example).++</details>+### Authentication Setup (v1.2.0+)-Portracker includes optional authentication to secure dashboard access:+portracker includes optional authentication to secure dashboard access:1. **Enable Authentication**: Set `ENABLE_AUTH=true` in your environment variables2. **First-Time Setup**: On first access, you'll see a setup wizard to create the admin account3. **Login**: Use your admin credentials to access the dashboard-4. **Production Recommendation**: Set a custom `SESSION_SECRET` for secure session management+4. **Stay Logged In** (optional): Set `SESSION_SECRET` to avoid being logged out on container restart**Example with Authentication:**diff --git a/backend/collectors/truenas_collector.js b/backend/collectors/truenas_collector.jsindex 94d6664..068b764 100644--- a/backend/collectors/truenas_collector.js+++ b/backend/collectors/truenas_collector.js@@ -33,7 +33,10 @@ class TrueNASCollector extends BaseCollector {this.platform = "truenas";this.platformName = "TrueNAS";this.name = "TrueNAS Collector";- this.client = new TrueNASClient({ debug: this.debug });+ this.client = null;+ this._clientInitPromise = null;+ this._collectionInProgress = false;+ this._pendingCollectionPromise = null;this.procParser = new ProcParser();this.dockerApi = new DockerAPIClient();this._initializeDocker();@@ -92,6 +95,33 @@ class TrueNASCollector extends BaseCollector {}}+ async _ensureTrueNASClient() {+ if (this.client && this.client.connected) {+ return this.client;+ }++ if (this._clientInitPromise) {+ return this._clientInitPromise;+ }++ this._clientInitPromise = (async () => {+ try {+ this.client = new TrueNASClient({ debug: this.debug });+ await this.client.connect();+ this.log('TrueNAS client connected and ready');+ return this.client;+ } catch (err) {+ this.logWarn('TrueNAS client initialization failed:', err.message);+ this.client = null;+ throw err;+ } finally {+ this._clientInitPromise = null;+ }+ })();++ return this._clientInitPromise;+ }+/*** Cleanup method to properly close connections* Should be called when the collector is no longer needed@@ -899,6 +929,24 @@ class TrueNASCollector extends BaseCollector {* @returns {Promise<Object>} Collection results*/async collect() {+ if (this._collectionInProgress) {+ this.log('Collection already in progress, returning pending promise');+ return this._pendingCollectionPromise;+ }++ this._collectionInProgress = true;+ this._pendingCollectionPromise = this._performCollection();++ try {+ const results = await this._pendingCollectionPromise;+ return results;+ } finally {+ this._collectionInProgress = false;+ this._pendingCollectionPromise = null;+ }+ }++ async _performCollection() {const perf = new PerformanceTracker();perf.start("total-collection");@@ -1206,15 +1254,18 @@ class TrueNASCollector extends BaseCollector {const apiKey = process.env.TRUENAS_API_KEY;if (apiKey) {this.logInfo("API key detected - collecting enhanced TrueNAS features");+ this.logInfo("First collection may take longer as middleware initializes connections...");- const enhancedFeaturesTimeout = parseInt(process.env.TRUENAS_TIMEOUT_MS || '45000', 10);+ const enhancedFeaturesTimeout = parseInt(process.env.TRUENAS_TIMEOUT_MS || '90000', 10);this.log(`Using enhanced features timeout: ${enhancedFeaturesTimeout/1000}s`);- const timeoutPromise = new Promise((_, reject) =>- setTimeout(() => reject(new Error(`TrueNAS enhanced features timeout after ${enhancedFeaturesTimeout/1000} seconds - your TrueNAS middleware may be slow or unresponsive`)), enhancedFeaturesTimeout)- );-try {+ await this._ensureTrueNASClient();++ const timeoutPromise = new Promise((_, reject) =>+ setTimeout(() => reject(new Error(`TrueNAS enhanced features timeout after ${enhancedFeaturesTimeout/1000} seconds - your TrueNAS middleware may be slow or unresponsive`)), enhancedFeaturesTimeout)+ );+const enhancedData = await Promise.race([this._collectEnhancedFeatures(),timeoutPromise@@ -1305,15 +1356,29 @@ class TrueNASCollector extends BaseCollector {this.logInfo("Continuing with Docker and system port data only");if (err.message.includes('timeout')) {- this.logInfo("💡 Troubleshooting tips:");+ this.logInfo("TrueNAS middleware timeout - your system may be slow or under load");+ this.logInfo("Troubleshooting steps:");this.logInfo(" 1. Check TrueNAS system resources: CPU, RAM, disk I/O");this.logInfo(" 2. Restart TrueNAS middleware: systemctl restart middlewared");- this.logInfo(" 3. Increase timeout: set TRUENAS_TIMEOUT_MS=60000 (60 seconds)");- this.logInfo(" 4. Check middleware logs: journalctl -u middlewared -n 100");+ this.logInfo(" 3. Increase overall timeout: TRUENAS_TIMEOUT_MS=120000 (2 minutes)");+ this.logInfo(" 4. Or adjust specific API timeouts:");+ this.logInfo(" - TRUENAS_SYSTEM_INFO_TIMEOUT_MS=60000 (system info)");+ this.logInfo(" - TRUENAS_APP_QUERY_TIMEOUT_MS=45000 (apps - slow with many apps)");+ this.logInfo(" - TRUENAS_VM_QUERY_TIMEOUT_MS=30000 (VMs)");+ this.logInfo(" - TRUENAS_CONTAINER_QUERY_TIMEOUT_MS=30000 (containers)");+ this.logInfo(" 5. Check middleware logs: journalctl -u middlewared -n 100");+ this.logInfo(" 6. See troubleshooting guide: https://github.com/mostafa-wahied/portracker#truenas-troubleshooting");+ }++ if (this.client) {+ try {+ this.client.close();+ this.client = null;+ } catch (closeErr) {+ this.logWarn("Error closing TrueNAS client after failure:", closeErr.message);+ }}}- /* Note: WebSocket connection is kept alive for reuse in subsequent scans- * The connection has a keep-alive ping mechanism and will be closed when collector is destroyed */} else {this.logInfo("No TRUENAS_API_KEY provided - enhanced features disabled"@@ -1808,74 +1873,96 @@ class TrueNASCollector extends BaseCollector {apps: [],vms: [],containers: [],- partialFailure: false,+ failures: [],};- this.logInfo("Attempting enhanced TrueNAS API calls...");+ this.logInfo("Attempting enhanced TrueNAS API calls in parallel...");- try {- const startTime = Date.now();- const systemInfo = await this.client.call("system.info");- results.systemInfo = systemInfo;- const duration = Date.now() - startTime;- this.log(`Enhanced system info retrieved in ${duration}ms`);- if (duration > 5000) {- this.logWarn(`system.info took ${(duration/1000).toFixed(1)}s - middleware may be slow`);- }- } catch (err) {- this.logWarn(- "Enhanced system info API call failed (continuing with basic info):",- err.message.substring(0, 100)- );- results.partialFailure = true;- }+ const systemInfoTimeout = parseInt(process.env.TRUENAS_SYSTEM_INFO_TIMEOUT_MS || '30000', 10);+ const appQueryTimeout = parseInt(process.env.TRUENAS_APP_QUERY_TIMEOUT_MS || '20000', 10);+ const vmQueryTimeout = parseInt(process.env.TRUENAS_VM_QUERY_TIMEOUT_MS || '15000', 10);+ const containerQueryTimeout = parseInt(process.env.TRUENAS_CONTAINER_QUERY_TIMEOUT_MS || '15000', 10);- try {+ const apiCalls = [+ {+ name: 'system.info',+ timeout: systemInfoTimeout,+ call: () => this.client.call("system.info"),+ resultKey: 'systemInfo',+ },+ {+ name: 'app.query',+ timeout: appQueryTimeout,+ call: () => this.client.call("app.query"),+ resultKey: 'apps',+ },+ {+ name: 'vm.query',+ timeout: vmQueryTimeout,+ call: () => this.client.call("vm.query"),+ resultKey: 'vms',+ },+ {+ name: 'virt.instance.query',+ timeout: containerQueryTimeout,+ call: () => this.client.call("virt.instance.query"),+ resultKey: 'containers',+ },+ ];++ const apiPromises = apiCalls.map(async (apiCall) => {const startTime = Date.now();- this.log("Querying TrueNAS apps (this may take a while on systems with many apps)...");- const apps = await this.client.call("app.query");- results.apps = apps || [];- const duration = Date.now() - startTime;- this.log(`TrueNAS apps query completed in ${duration}ms (${(apps || []).length} apps found)`);- if (duration > 10000) {- this.logWarn(`app.query took ${(duration/1000).toFixed(1)}s - consider reducing number of TrueNAS apps for better performance`);+ try {+ const timeoutPromise = new Promise((_, reject) =>+ setTimeout(() => reject(new Error(`${apiCall.name} timeout after ${apiCall.timeout/1000}s`)), apiCall.timeout)+ );++ const data = await Promise.race([apiCall.call(), timeoutPromise]);+ const duration = Date.now() - startTime;++ this.log(`${apiCall.name} completed in ${duration}ms`);++ if (duration > apiCall.timeout * 0.7) {+ this.logWarn(`${apiCall.name} took ${(duration/1000).toFixed(1)}s (70% of ${apiCall.timeout/1000}s timeout - consider increasing if this becomes frequent)`);+ }++ return { success: true, name: apiCall.name, data, resultKey: apiCall.resultKey, duration };+ } catch (err) {+ const duration = Date.now() - startTime;+ this.logWarn(`${apiCall.name} failed after ${(duration/1000).toFixed(1)}s:`, err.message.substring(0, 100));+ return { success: false, name: apiCall.name, error: err.message, resultKey: apiCall.resultKey, duration };}- } catch (err) {- this.logWarn(- "TrueNAS apps API query failed (VMs will still be collected):",- err.message.substring(0, 100)- );- results.partialFailure = true;- }-- try {- const startTime = Date.now();- const vms = await this.client.call("vm.query");- results.vms = vms || [];- const duration = Date.now() - startTime;- this.log(`VM query completed in ${duration}ms (${(vms || []).length} VMs found)`);- } catch (err) {- this.logWarn("VM API query failed (continuing with other data):", err.message.substring(0, 100));- results.partialFailure = true;- }+ });- try {- const startTime = Date.now();- const containers = await this.client.call("virt.instance.query");- results.containers = containers || [];- const duration = Date.now() - startTime;- this.log(`LXC container query completed in ${duration}ms (${(containers || []).length} containers found)`);- } catch (err) {- this.logWarn("LXC Container API query failed (continuing with other data):", err.message.substring(0, 100));- results.partialFailure = true;- }+ const apiResults = await Promise.allSettled(apiPromises);++ apiResults.forEach((promiseResult) => {+ if (promiseResult.status === 'fulfilled') {+ const result = promiseResult.value;+ if (result.success) {+ if (result.resultKey === 'systemInfo') {+ results.systemInfo = result.data;+ } else {+ results[result.resultKey] = result.data || [];+ }+ } else {+ results.failures.push(result.name);+ }+ } else {+ this.logWarn('Unexpected API call rejection:', promiseResult.reason);+ }+ });const totalCollected = (results.apps?.length || 0) + (results.vms?.length || 0) + (results.containers?.length || 0);- if (results.partialFailure) {- this.logWarn(`Partial enhanced features collection: ${totalCollected} items collected (some API calls failed)`);+ const successCount = apiCalls.length - results.failures.length;++ if (results.failures.length === 0) {+ this.logInfo(`Enhanced features collected successfully: ${results.apps?.length || 0} apps, ${results.vms?.length || 0} VMs, ${results.containers?.length || 0} containers (${successCount}/${apiCalls.length} API calls)`);+ } else if (results.failures.length === apiCalls.length) {+ this.logWarn(`Enhanced features collection failed: all ${apiCalls.length} API calls failed (${results.failures.join(', ')})`);} else {- this.log(`Enhanced features collection successful: ${totalCollected} items collected`);+ this.logWarn(`Partial enhanced features collection: ${results.apps?.length || 0} apps, ${results.vms?.length || 0} VMs, ${results.containers?.length || 0} containers from ${successCount}/${apiCalls.length} API calls (failed: ${results.failures.join(', ')})`);}return results;diff --git a/backend/lib/logger.js b/backend/lib/logger.jsindex b2c5b92..673b49b 100644--- a/backend/lib/logger.js+++ b/backend/lib/logger.js@@ -1,5 +1,5 @@/**- * Centralized logging system for Portracker+ * Centralized logging system for portracker* Provides consistent logging across all components*/diff --git a/backend/lib/tn-ws.js b/backend/lib/tn-ws.jsindex ebad654..4166390 100644--- a/backend/lib/tn-ws.js+++ b/backend/lib/tn-ws.js@@ -326,10 +326,11 @@ async function connectWs(options = {}) {ws.on("message", messageHandler);ws.send(payload);+ const requestTimeout = parseInt(process.env.TRUENAS_WS_REQUEST_TIMEOUT_MS || '40000', 10);const requestTimeoutId = setTimeout(() => {ws.removeListener("message", messageHandler);- reject(new Error(`Request timeout for method ${method}`));- }, 30000);+ reject(new Error(`Request timeout for method ${method} after ${requestTimeout/1000}s`));+ }, requestTimeout);};if (diff --git a/backend/middleware/auth.js b/backend/middleware/auth.jsindex ec3fb14..303034c 100644--- a/backend/middleware/auth.js+++ b/backend/middleware/auth.js@@ -1,7 +1,7 @@/*** Authentication Middleware*- * Provides session management and authentication checking for Portracker.+ * Provides session management and authentication checking for portracker.* Authentication can be enabled/disabled via ENABLE_AUTH environment variable.*/diff --git a/docker-compose.yml b/docker-compose.ymlindex 0078610..db4bbcd 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -5,7 +5,7 @@ services:restart: unless-stopped# Required for comprehensive system port detection- # This allows Portracker to see all host processes for accurate port mapping+ # This allows portracker to see all host processes for accurate port mappingpid: "host"# Capabilities & security (universal, required)@@ -38,7 +38,7 @@ services:# CORE CONFIGURATION (Required)# - DATABASE_PATH=/data/portracker.db# - PORT=4999- # Tell Portracker where to find the host /proc (matches the volume above)+ # Tell portracker where to find the host /proc (matches the volume above)# - HOST_PROC=/host/proc# DOCKER CONFIGURATION@@ -86,14 +86,14 @@ services:# 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+ # 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+ # # Only allow read operations portracker needs# - CONTAINERS=1# - IMAGES=1# - INFO=1diff --git a/frontend/src/components/ui/WhatsNewModal.jsx b/frontend/src/components/ui/WhatsNewModal.jsxindex 8cb2df2..4d0b513 100644--- a/frontend/src/components/ui/WhatsNewModal.jsx+++ b/frontend/src/components/ui/WhatsNewModal.jsx@@ -261,7 +261,7 @@ export function WhatsNewModal({ isOpen, onClose, onDismiss, version, changes, gr</div><div><DialogTitle className="text-xl font-bold text-slate-900 dark:text-slate-100">- What's New in Portracker {version}+ What's New in portracker {version}</DialogTitle><DialogDescription className="text-slate-600 dark:text-slate-400 mt-1">Discover the latest features and improvementsdiff --git a/frontend/src/lib/logger.js b/frontend/src/lib/logger.jsindex e04134a..f6d57d6 100644--- a/frontend/src/lib/logger.js+++ b/frontend/src/lib/logger.js@@ -1,5 +1,5 @@/**- * Frontend Logger System for Portracker+ * Frontend Logger System for portracker* Provides centralized logging with component identification and timestamp formatting* Consistent with backend logging patterns*/diff --git a/package.json b/package.jsonindex 345edd8..bbb1d86 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "portracker",- "version": "1.2.1",+ "version": "1.2.2","description": "A multi-platform port-tracking dashboard","main": "backend/index.js","scripts": {