Merge pull request #17 from smashingtags/feature/cors

finally

Author: smashingtags

.env.example

@@ -7,4 +7,12 @@ AUTH_TOKEN=your-secure-token-here
 CORS_ORIGIN=https://your-domain.com
 
 # Docker Configuration
-DOCKER_SOCKET=/var/run/docker.sock
+# Path to Docker socket - usually /var/run/docker.sock on Linux systems
+DOCKER_SOCKET=/var/run/docker.sock
+
+# Docker group ID - MUST match your host system's docker group ID
+# Find your system's docker group ID with:
+#   Linux: getent group docker | cut -d: -f3
+#   Linux (alternative): cat /etc/group | grep docker
+# Common values: 999, 998, 994 (varies by system)
+DOCKER_GID=999

.env.production

@@ -3,7 +3,7 @@ NODE_ENV=production
 
 # Backend Configuration
 PORT=3001
-CORS_ORIGIN=http://localhost:8087
+CORS_ORIGIN=*
 
 # Docker Configuration
 DOCKER_SOCKET=/var/run/docker.sock

.kiro/specs/docker-socket-fix/design.md

@@ -0,0 +1,152 @@
+# Design Document
+
+## Overview
+
+The Docker socket permission error (EACCES) occurs because the homelabarr-backend container lacks proper permissions to access the Docker daemon socket at `/var/run/docker.sock`. The current implementation attempts to change socket permissions using `chmodSync()`, but this fails because the container runs as a non-root user (`node`) and cannot modify system-level socket permissions.
+
+The solution involves configuring proper Docker group membership and socket access through container orchestration rather than runtime permission changes.
+
+## Architecture
+
+The fix operates at multiple layers:
+
+1. **Container Build Layer** - Ensure proper user/group configuration in Dockerfile
+2. **Container Runtime Layer** - Configure group membership and socket mounting in docker-compose
+3. **Application Layer** - Implement robust error handling and retry logic
+4. **Monitoring Layer** - Add proper logging and health checks for Docker connectivity
+
+## Components and Interfaces
+
+### Docker Group Configuration
+- **Host Group Mapping**: Map the host's docker group ID to the container
+- **User Group Membership**: Add the container user to the docker group
+- **Socket Permissions**: Ensure socket is accessible to docker group members
+
+### Container Configuration
+- **Dockerfile Updates**: Configure proper group membership during build
+- **Docker Compose Updates**: Set correct group_add configuration
+- **Environment Variables**: Configure socket path and connection settings
+
+### Application Layer Improvements
+- **Connection Retry Logic**: Implement exponential backoff for failed connections
+- **Error Handling**: Graceful degradation when Docker is unavailable
+- **Health Monitoring**: Enhanced health checks for Docker connectivity
+
+### Security Considerations
+- **Least Privilege**: Grant minimal necessary permissions
+- **Group-based Access**: Use group membership instead of privileged mode
+- **Socket Protection**: Maintain socket security while enabling access
+
+## Data Models
+
+### Docker Connection Configuration
+```javascript
+interface DockerConfig {
+  socketPath: string;
+  timeout: number;
+  retryAttempts: number;
+  retryDelay: number;
+  healthCheckInterval: number;
+}
+```
+
+### Connection State Management
+```javascript
+interface DockerConnectionState {
+  isConnected: boolean;
+  lastError: Error | null;
+  lastSuccessfulConnection: Date | null;
+  retryCount: number;
+  nextRetryAt: Date | null;
+}
+```
+
+### Error Classification
+```javascript
+interface DockerError {
+  type: 'permission' | 'connection' | 'timeout' | 'unknown';
+  code: string;
+  message: string;
+  recoverable: boolean;
+  retryAfter?: number;
+}
+```
+
+## Error Handling
+
+### Permission Errors (EACCES)
+- **Root Cause**: Container user lacks docker group membership
+- **Detection**: Monitor for EACCES errors on socket connection
+- **Resolution**: Configure proper group membership in container
+- **Fallback**: Log error and continue with degraded functionality
+
+### Connection Failures
+- **Retry Strategy**: Exponential backoff with maximum retry limit
+- **Circuit Breaker**: Temporarily stop retrying after consecutive failures
+- **Recovery**: Automatic reconnection when Docker becomes available
+
+### Socket Unavailability
+- **Detection**: Monitor socket file existence and permissions
+- **Logging**: Detailed error messages for troubleshooting
+- **Graceful Degradation**: Continue serving non-Docker endpoints
+
+## Testing Strategy
+
+### Permission Testing
+- Verify container can access Docker socket after configuration changes
+- Test that docker group membership is properly configured
+- Validate socket permissions are correctly set
+
+### Connection Resilience Testing
+- Test behavior when Docker daemon is stopped/started
+- Verify retry logic works correctly with various failure scenarios
+- Test graceful degradation when Docker is unavailable
+
+### Security Testing
+- Ensure container doesn't run with unnecessary privileges
+- Verify socket access is limited to required operations
+- Test that security boundaries are maintained
+
+### Integration Testing
+- Test full container deployment with fixed configuration
+- Verify Docker operations work correctly after fix
+- Test health check endpoints report correct Docker status
+
+## Implementation Approach
+
+### Phase 1: Container Configuration Fix
+1. Update Dockerfile to properly configure docker group
+2. Modify docker-compose.yml to set correct group_add values
+3. Remove ineffective chmod attempts from application code
+
+### Phase 2: Application Layer Improvements
+1. Implement robust Docker connection management
+2. Add retry logic with exponential backoff
+3. Enhance error logging and monitoring
+
+### Phase 3: Health and Monitoring
+1. Improve health check to properly report Docker status
+2. Add connection state monitoring
+3. Implement graceful degradation for Docker unavailability
+
+### Phase 4: Security Hardening
+1. Verify minimal privilege configuration
+2. Add security validation for Docker operations
+3. Implement proper error boundaries
+
+## Security Considerations
+
+### Docker Socket Access
+- Use group-based permissions instead of privileged mode
+- Limit socket access to necessary operations only
+- Monitor and log all Docker API calls
+
+### Container Security
+- Run as non-root user with minimal required permissions
+- Use specific group membership rather than broad privileges
+- Implement proper input validation for Docker operations
+
+### Host System Protection
+- Ensure container cannot escape to host system
+- Limit Docker operations to safe, necessary functions
+- Implement proper audit logging for security monitoring

.kiro/specs/docker-socket-fix/requirements.md

@@ -0,0 +1,47 @@
+# Requirements Document
+
+## Introduction
+
+This feature addresses the Docker socket permission error (EACCES) that prevents the homelabarr-backend from accessing Docker containers. The application is running in a Docker container and needs to communicate with the Docker daemon on the host system to manage other containers, but lacks the necessary permissions to access /var/run/docker.sock.
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a homelabarr-backend service, I want to access the Docker socket, so that I can fetch and manage Docker containers without permission errors.
+
+#### Acceptance Criteria
+
+1. WHEN the backend attempts to connect to /var/run/docker.sock THEN the connection SHALL succeed without EACCES errors
+2. WHEN the Docker socket is mounted in the container THEN the backend process SHALL have read/write permissions
+3. WHEN fetching containers THEN the API calls SHALL complete successfully without permission denials
+
+### Requirement 2
+
+**User Story:** As a system administrator, I want secure Docker socket access, so that the container can manage Docker resources without compromising host security.
+
+#### Acceptance Criteria
+
+1. WHEN mounting the Docker socket THEN only necessary permissions SHALL be granted
+2. WHEN the container accesses Docker THEN it SHALL use the least privilege principle
+3. WHEN running in production THEN Docker socket access SHALL be properly secured
+
+### Requirement 3
+
+**User Story:** As a developer, I want consistent Docker socket access across environments, so that the application works reliably in development, testing, and production.
+
+#### Acceptance Criteria
+
+1. WHEN running via docker-compose THEN Docker socket access SHALL work consistently
+2. WHEN running on different host systems THEN the socket mounting SHALL adapt to the environment
+3. WHEN deploying to different platforms THEN Docker access SHALL remain functional
+
+### Requirement 4
+
+**User Story:** As a homelabarr user, I want the backend to gracefully handle Docker connection failures, so that the application remains stable even when Docker access is temporarily unavailable.
+
+#### Acceptance Criteria
+
+1. WHEN Docker socket access fails THEN the backend SHALL log appropriate error messages
+2. WHEN Docker is temporarily unavailable THEN the backend SHALL implement retry logic with exponential backoff
+3. WHEN Docker access is restored THEN the backend SHALL automatically reconnect without requiring restart

.kiro/specs/docker-socket-fix/tasks.md

@@ -0,0 +1,102 @@
+# Implementation Plan
+
+- [x] 1. Fix Docker group configuration in Dockerfile.backend
+
+
+
+
+
+  - Remove the hardcoded docker group creation and use dynamic group ID detection
+  - Update the group_add configuration to use the correct docker group ID
+  - Ensure the node user is properly added to the docker group
+  - _Requirements: 1.1, 1.2, 2.1_
+
+- [x] 2. Update docker-compose.yml for proper Docker socket access
+
+
+
+
+
+  - Fix the group_add configuration to use the correct docker group ID for the host system
+  - Verify the Docker socket volume mount is correctly configured
+  - Add environment variable for Docker socket path configuration
+  - _Requirements: 1.1, 1.2, 3.1_
+
+- [x] 3. Remove ineffective socket permission code from server/index.js
+
+
+
+
+
+  - Remove the chmodSync call that attempts to change socket permissions
+  - Remove the try-catch block around the chmod operation
+  - Clean up related console.warn messages about socket permissions
+  - _Requirements: 1.1, 2.1_
+
+- [x] 4. Implement robust Docker connection management in server/index.js
+
+
+
+
+
+  - Create a DockerConnectionManager class to handle connection state
+  - Implement retry logic with exponential backoff for failed connections
+  - Add connection health monitoring and automatic reconnection
+  - _Requirements: 4.1, 4.2, 4.3_
+
+- [x] 5. Add proper error handling for Docker connection failures
+
+
+
+
+
+  - Implement error classification to distinguish between different failure types
+  - Add graceful degradation when Docker is temporarily unavailable
+  - Create proper error responses for Docker-dependent endpoints
+  - _Requirements: 4.1, 4.2, 4.3_
+
+- [x] 6. Enhance health check endpoint for Docker connectivity status
+
+
+
+
+
+  - Update the /health endpoint to properly report Docker connection status
+  - Add detailed error information when Docker connection fails
+  - Implement connection retry status in health check response
+  - _Requirements: 4.1, 4.3_
+
+- [x] 7. Add comprehensive logging for Docker connection issues
+
+
+
+
+
+  - Implement structured logging for Docker connection attempts
+  - Add debug logging for connection state changes
+  - Create informative error messages for troubleshooting
+  - _Requirements: 4.1, 4.3_
+
+- [x] 8. Create Docker connection retry mechanism
+
+
+
+
+
+  - Implement exponential backoff algorithm for connection retries
+  - Add maximum retry limits to prevent infinite retry loops
+  - Create circuit breaker pattern for consecutive failures
+  - _Requirements: 4.2, 4.3_
+
+- [x] 9. Test and validate Docker socket access fix
+
+
+
+
+
+
+
+  - Create test script to verify Docker socket permissions
+  - Test container deployment with updated configuration
+  - Verify all Docker operations work correctly after fix
+  - _Requirements: 1.1, 1.2, 1.3, 3.1_

.kiro/specs/error-cleanup/tasks.md

@@ -1,30 +1,30 @@
 # Implementation Plan
 
-- [] 1. Install project dependencies and verify module resolution
+- [x] 1. Install project dependencies and verify module resolution
   - Run npm install to install all dependencies from package.json
   - Verify that node_modules directory is created with all required packages
   - Test that React and lucide-react modules can be imported without errors
   - _Requirements: 1.1, 1.2, 1.3_
 
-- [] 2. Fix TypeScript configuration for proper JSX support
+- [x] 2. Fix TypeScript configuration for proper JSX support
   - Update tsconfig.app.json to ensure proper JSX runtime configuration
   - Verify that JSX.IntrinsicElements interface is properly recognized
   - Test that React components compile without JSX-related errors
   - _Requirements: 2.1, 2.2, 2.3_
 
-- [] 3. Resolve implicit any type errors in event handlers
+- [x] 3. Resolve implicit any type errors in event handlers
   - Add explicit type annotations for event handler parameters in App.tsx
   - Fix setState callback parameter types to remove implicit any errors
   - Ensure all event handlers have proper TypeScript types
   - _Requirements: 3.1, 3.2, 3.3_
 
-- [] 4. Fix React component prop type issues
+- [x] 4. Fix React component prop type issues
   - Review and fix component prop interfaces to align with usage
   - Separate React key props from component prop interfaces
   - Ensure all component props are properly typed and validated
   - _Requirements: 4.1, 4.2, 4.3_
 
-- [] 5. Verify compilation and test application functionality
+- [x] 5. Verify compilation and test application functionality
   - Run TypeScript compilation to ensure no errors remain
   - Test that the development server starts successfully
   - Verify that all React components render without runtime errors

DEPLOYMENT.md

@@ -85,6 +85,16 @@ The application requires access to the Docker socket for container management. T
 - Authentication required for all container operations
 - Health checks for service monitoring
 
+**Docker Group Configuration:**
+The application uses the host's docker group for socket access. To find your docker group ID:
+```bash
+getent group docker | cut -d: -f3
+```
+Set this value in your `.env` file:
+```bash
+DOCKER_GID=999  # Replace with your actual docker group ID
+```
+
 #### Network Security
 - Frontend and backend communicate over internal Docker network
 - Only necessary ports are exposed