fix(satellite): resolve Docker volume permission issues preventing credential persistence

Fixes #547

Problem:
- Satellite container failed to persist credentials due to volume permission mismatch
- Docker created volumes with root:root ownership by default
- Satellite runs as deploystack user (uid=1001, gid=1001) and couldn't write
- Registration succeeded but credentials not saved (silent failure)
- Container entered restart loop on subsequent starts

Solution:
1. Dockerfile: Create /app/persistent_data directory with correct ownership before USER switch
2. Backend Client: Add ensureDirectoryExists() method with fail-fast permission checks
3. Server: Call directory initialization during startup to catch permission issues early
4. Error Handling: Enhanced savePersistedData() with detailed permission error messages
5. Documentation: Updated docker run commands to include --user 1001:1001 flag

Impact:
- Fresh deployments now work automatically
- Existing broken volumes fail fast with clear error messages and fix commands
- Satellite credentials persist correctly across container restarts
- No more silent failures

Files Modified:
- services/satellite/Dockerfile
- services/satellite/src/services/backend-client.ts
- services/satellite/src/server.ts
- documentation/self-hosted/docker-compose.mdx
- documentation/self-hosted/quick-start.mdx

Author: Lasim

services/satellite/Dockerfile

@@ -17,6 +17,12 @@ RUN mkdir -p /opt/deploystack/mcp-cache && \
 
 WORKDIR /app
 
+# Create persistent_data directory with proper ownership
+# This prevents Docker volume permission issues when running as non-root user
+RUN mkdir -p /app/persistent_data && \
+    chown -R deploystack:deploystack /app/persistent_data && \
+    chmod 755 /app/persistent_data
+
 # Copy package files
 COPY services/satellite/package.json ./
 

services/satellite/src/server.ts

@@ -212,7 +212,19 @@ export async function createServer() {
   // Initialize Backend Client (needed by EventBus)
   const backendUrl = process.env.DEPLOYSTACK_BACKEND_URL || 'http://localhost:3000';
   const backendClient = new BackendClient(backendUrl, server.log);
-  
+
+  // Ensure persistent data directory exists before attempting any operations
+  try {
+    await backendClient.ensureDirectoryExists();
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    server.log.fatal({
+      operation: 'persistent_directory_initialization_failed',
+      error: errorMessage
+    }, 'Failed to initialize persistent storage directory - cannot continue');
+    process.exit(1);
+  }
+
   // Initialize MCP Activity Tracker for personal dashboard feature
   const activityTracker = new McpActivityTracker(server.log);
   server.decorate('activityTracker', activityTracker);

services/satellite/src/services/backend-client.ts

@@ -1,6 +1,6 @@
 import { FastifyBaseLogger } from 'fastify';
 import { platform, arch, totalmem } from 'os';
-import { readFile, writeFile, access } from 'fs/promises';
+import { readFile, writeFile, access, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { SatelliteEvent } from '../events/registry';
 import { getVersionString } from '../config/version';
@@ -105,6 +105,67 @@ export class BackendClient {
     };
   }
 
+  /**
+   * Ensure persistent data directory exists with proper permissions
+   * Called during server initialization before any file operations
+   */
+  public async ensureDirectoryExists(): Promise<void> {
+    try {
+      await access(this.persistentDataPath);
+      this.logger.debug({
+        operation: 'persistent_directory_exists',
+        path: this.persistentDataPath
+      }, 'Persistent data directory exists');
+    } catch (error) {
+      const accessError = error as NodeJS.ErrnoException;
+
+      if (accessError.code === 'ENOENT') {
+        // Directory doesn't exist, create it
+        this.logger.info({
+          operation: 'creating_persistent_directory',
+          path: this.persistentDataPath
+        }, 'Creating persistent data directory');
+
+        try {
+          await mkdir(this.persistentDataPath, { recursive: true, mode: 0o755 });
+
+          this.logger.info({
+            operation: 'persistent_directory_created',
+            path: this.persistentDataPath
+          }, '✅ Persistent data directory created successfully');
+
+        } catch (mkdirError) {
+          const mkdirErrno = mkdirError as NodeJS.ErrnoException;
+
+          if (mkdirErrno.code === 'EACCES' || mkdirErrno.code === 'EPERM') {
+            this.logger.fatal({
+              operation: 'persistent_directory_creation_failed',
+              path: this.persistentDataPath,
+              error: mkdirErrno.message,
+              errno: mkdirErrno.code,
+              fix: 'chown -R 1001:1001 /path/to/volume'
+            }, '❌ FATAL: Cannot create persistent data directory due to permission denied');
+
+            throw new Error(
+              `Permission denied creating ${this.persistentDataPath}. ` +
+              `Docker volume permission issue. Fix: chown -R 1001:1001 <volume-mountpoint>`
+            );
+          }
+          throw mkdirError;
+        }
+      } else {
+        // Other access errors (not ENOENT)
+        this.logger.error({
+          operation: 'persistent_directory_access_failed',
+          path: this.persistentDataPath,
+          error: accessError.message,
+          errno: accessError.code
+        }, 'Failed to access persistent data directory');
+        throw error;
+      }
+    }
+  }
+
   /**
    * Set API key for authenticated requests
    */
@@ -500,22 +561,48 @@ export class BackendClient {
    */
   async savePersistedData(data: PersistedSatelliteData): Promise<void> {
     try {
+      // Double-check directory exists (defensive programming)
+      await this.ensureDirectoryExists();
+
       const fileContent = JSON.stringify(data, null, 2);
       await writeFile(this.keyFilePath, fileContent, 'utf-8');
-      
+
       this.logger.info({
         operation: 'persistent_data_saved',
         file_path: this.keyFilePath,
         satellite_id: data.satellite_id,
         satellite_name: data.satellite_name
-      }, 'Satellite data saved to persistent storage');
-      
+      }, '✅ Satellite credentials saved to persistent storage');
+
     } catch (error) {
+      const errno = error as NodeJS.ErrnoException;
+
+      // Handle permission-specific errors with detailed guidance
+      if (errno.code === 'EACCES' || errno.code === 'EPERM') {
+        this.logger.fatal({
+          operation: 'persistent_data_save_permission_denied',
+          file_path: this.keyFilePath,
+          error: errno.message,
+          errno: errno.code,
+          help: 'Check Docker volume permissions. Expected uid=1001, gid=1001',
+          fix_command: 'docker run --rm -v deploystack_satellite_persistent:/data alpine chown -R 1001:1001 /data'
+        }, '❌ FATAL: Cannot save credentials due to permission denied. Satellite cannot persist registration.');
+
+        // This is CRITICAL - satellite will fail on restart without credentials
+        throw new Error(
+          `Permission denied writing ${this.keyFilePath}. ` +
+          `Docker volume permissions issue. Fix: chown -R 1001:1001 /path/to/volume`
+        );
+      }
+
+      // Generic error handling
       this.logger.error({
         operation: 'persistent_data_save_error',
         file_path: this.keyFilePath,
-        error: error instanceof Error ? error.message : 'Unknown error'
+        error: errno.message || 'Unknown error',
+        errno: errno.code
       }, 'Failed to save satellite data to persistent storage');
+
       throw error;
     }
   }