chore: Update Docker configuration and documentation

### Summary of Changes
- Enhanced `docker-compose` files to include BuildKit compatibility settings for improved caching during builds.
- Updated service definitions to use pre-built images from the specified Docker registry, ensuring consistency across environments.
- Added Docker registry configuration to the `.env` example file for clarity on deployment settings.
- Revised the `README.md` to include instructions for using pre-built images and local development setups, along with Docker compatibility troubleshooting steps.
- Introduced health checks in the `Dockerfile` for the API Docs service to ensure container readiness.

### Expected Results
- Improved build performance and deployment clarity, facilitating easier setup for new developers and enhancing overall project maintainability.

.gitea/workflows/docker-build.yml

@@ -62,7 +62,7 @@ jobs:
         username: ${{ secrets.REGISTRY_USERNAME }}
         password: ${{ secrets.REGISTRY_PASSWORD }}
         
-    - name: Build and push API Gateway
+    - name: Build and push API Gateway (Legacy Builder)
       uses: docker/build-push-action@v5
       with:
         context: ./services/api-gateway
@@ -72,6 +72,10 @@ jobs:
         labels: ${{ needs.setup.outputs.labels }}
         cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/api-gateway:cache
         cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/api-gateway:cache,mode=max
+        # Use legacy builder for maximum compatibility
+        builder: default
+        build-args: |
+          BUILDKIT_INLINE_CACHE=0
 
   # Service Adapters build and push
   build-push-service-adapters:
@@ -92,7 +96,7 @@ jobs:
         username: ${{ secrets.REGISTRY_USERNAME }}
         password: ${{ secrets.REGISTRY_PASSWORD }}
         
-    - name: Build and push Service Adapters
+    - name: Build and push Service Adapters (Legacy Builder)
       uses: docker/build-push-action@v5
       with:
         context: ./services/service-adapters
@@ -102,6 +106,10 @@ jobs:
         labels: ${{ needs.setup.outputs.labels }}
         cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/service-adapters:cache
         cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/service-adapters:cache,mode=max
+        # Use legacy builder for maximum compatibility
+        builder: default
+        build-args: |
+          BUILDKIT_INLINE_CACHE=0
 
   # API Docs build and push
   build-push-api-docs:
@@ -122,7 +130,7 @@ jobs:
         username: ${{ secrets.REGISTRY_USERNAME }}
         password: ${{ secrets.REGISTRY_PASSWORD }}
         
-    - name: Build and push API Docs
+    - name: Build and push API Docs (Legacy Builder)
       uses: docker/build-push-action@v5
       with:
         context: ./services/api-docs
@@ -132,6 +140,10 @@ jobs:
         labels: ${{ needs.setup.outputs.labels }}
         cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/api-docs:cache
         cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/api-docs:cache,mode=max
+        # Use legacy builder for maximum compatibility
+        builder: default
+        build-args: |
+          BUILDKIT_INLINE_CACHE=0
 
   # Frontend build and push
   build-push-frontend:
@@ -152,7 +164,7 @@ jobs:
         username: ${{ secrets.REGISTRY_USERNAME }}
         password: ${{ secrets.REGISTRY_PASSWORD }}
         
-    - name: Build and push Frontend
+    - name: Build and push Frontend (Legacy Builder)
       uses: docker/build-push-action@v5
       with:
         context: ./frontend
@@ -162,3 +174,61 @@ jobs:
         labels: ${{ needs.setup.outputs.labels }}
         cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/frontend:cache
         cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.REPO_OWNER }}/frontend:cache,mode=max
+        # Use legacy builder for maximum compatibility
+        builder: default
+        build-args: |
+          BUILDKIT_INLINE_CACHE=0
+
+  # Compatibility test job
+  test-compatibility:
+    runs-on: self-hosted
+    needs: [build-push-api-gateway, build-push-service-adapters, build-push-api-docs, build-push-frontend]
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      
+    - name: Test API Docs compatibility
+      run: |
+        echo "Testing API Docs image compatibility..."
+        
+        # Pull the latest image
+        docker pull ${{ env.REGISTRY }}/admin/api-docs:${{ needs.setup.outputs.version }}
+        
+        # Test running the container
+        docker run --rm -d --name test-api-docs \
+          -p 8083:8083 \
+          ${{ env.REGISTRY }}/admin/api-docs:${{ needs.setup.outputs.version }}
+        
+        # Wait for container to start
+        sleep 10
+        
+        # Check if container is running
+        if docker ps | grep -q test-api-docs; then
+          echo "✓ API Docs container started successfully"
+        else
+          echo "✗ API Docs container failed to start"
+          docker logs test-api-docs
+          exit 1
+        fi
+        
+        # Clean up
+        docker stop test-api-docs || true
+        
+    - name: Test docker-compose compatibility
+      run: |
+        echo "Testing docker-compose configuration..."
+        
+        # Validate docker-compose.yml
+        docker-compose config > /dev/null
+        if [ $? -eq 0 ]; then
+          echo "✓ docker-compose.yml is valid"
+        else
+          echo "✗ docker-compose.yml has syntax errors"
+          exit 1
+        fi
+        
+    - name: Compatibility test completed
+      run: |
+        echo "✓ All compatibility tests passed"
+        echo "Images are ready for deployment with maximum Docker version compatibility"

README.md

@@ -34,6 +34,7 @@ A unified dashboard and integration hub for your homelab services. LabFusion pro
 
 - Docker and Docker Compose
 - Git
+- Access to container registry (optional, for pre-built images)
 
 ### Installation
 
@@ -48,9 +49,14 @@ cd labfusion
 cp env.example .env
 ```
 
-3. Edit `.env` file with your service URLs and tokens:
+3. Edit `.env` file with your configuration:
 ```bash
-# Update these with your actual service URLs and tokens
+# Docker Registry Configuration (for pre-built images)
+DOCKER_REGISTRY=gittea.kammenstraatha.duckdns.org/admin
+DOCKER_USERNAME=admin
+IMAGE_TAG=main
+
+# Service Integration URLs (update with your actual service URLs and tokens)
 HOME_ASSISTANT_URL=http://homeassistant.local:8123
 HOME_ASSISTANT_TOKEN=your-ha-token-here
 FRIGATE_URL=http://frigate.local:5000
@@ -61,9 +67,27 @@ IMMICH_API_KEY=your-immich-api-key-here
 
 4. Start the services:
 ```bash
+# Using pre-built images from registry (recommended)
 docker-compose up -d
+
+# Or for development with local builds
+docker-compose -f docker-compose.dev.yml up -d
 ```
 
+**Docker Compatibility Issues?** If you encounter BuildKit cache errors (common with Docker 27.x), run our compatibility fix:
+
+**Windows:**
+```powershell
+.\scripts\fix-docker-compatibility.ps1
+```
+
+**Linux/macOS:**
+```bash
+./scripts/fix-docker-compatibility.sh
+```
+
+See [Docker Compatibility Guide](docs/DOCKER_COMPATIBILITY.md) for detailed troubleshooting.
+
 5. Access the application:
 - Frontend: http://localhost:3000
 - API Gateway: http://localhost:8080
@@ -155,6 +179,29 @@ npm start
 - **API Gateway**: http://localhost:8080/swagger-ui.html
 - **Service Adapters**: http://localhost:8000/docs
 
+## Docker Deployment
+
+LabFusion supports both pre-built images from container registries and local builds:
+
+### Pre-built Images (Recommended)
+```bash
+# Configure registry settings in .env
+DOCKER_REGISTRY=gittea.kammenstraatha.duckdns.org/admin
+DOCKER_USERNAME=admin
+IMAGE_TAG=main
+
+# Deploy with pre-built images
+docker-compose up -d
+```
+
+### Local Development
+```bash
+# Build and run locally
+docker-compose -f docker-compose.dev.yml up -d
+```
+
+For detailed deployment instructions, see [Docker Deployment Guide](docs/DOCKER_DEPLOYMENT.md).
+
 ## Roadmap
 
 - [x] Basic project structure and Docker setup

docker-compose.dev.yml

@@ -1,5 +1,9 @@
 version: '3.8'
 
+# Global BuildKit compatibility settings
+x-buildkit-args: &buildkit-args
+  BUILDKIT_INLINE_CACHE: 1
+
 services:
   # Database
   postgres:
@@ -30,6 +34,7 @@ services:
     build:
       context: ./services/api-gateway
       dockerfile: Dockerfile.dev
+      args: *buildkit-args
     ports:
       - "8080:8080"
     environment:
@@ -53,6 +58,7 @@ services:
     build:
       context: ./services/service-adapters
       dockerfile: Dockerfile.dev
+      args: *buildkit-args
     ports:
       - "8000:8000"
     environment:
@@ -72,6 +78,7 @@ services:
     build:
       context: ./frontend
       dockerfile: Dockerfile.dev
+      args: *buildkit-args
     ports:
       - "3000:3000"
     environment:
@@ -90,6 +97,7 @@ services:
     build:
       context: ./services/api-docs
       dockerfile: Dockerfile.dev
+      args: *buildkit-args
     ports:
       - "8083:8083"
     environment:

docker-compose.yml

@@ -3,7 +3,7 @@ version: '3.8'
 services:
   # Database
   postgres:
-    image: postgres:latest
+    image: postgres:14
     environment:
       POSTGRES_DB: labfusion
       POSTGRES_USER: labfusion
@@ -27,9 +27,7 @@ services:
 
   # Java Spring Boot API Gateway
   api-gateway:
-    build:
-      context: ./services/api-gateway
-      dockerfile: Dockerfile
+    image: gittea.kammenstraatha.duckdns.org/admin/api-gateway:main
     ports:
       - "8080:8080"
     environment:
@@ -38,6 +36,7 @@ services:
       - SPRING_DATASOURCE_PASSWORD=labfusion_password
       - REDIS_HOST=redis
       - REDIS_PORT=6379
+      - SPRING_PROFILES_ACTIVE=prod
     depends_on:
       - postgres
       - redis
@@ -46,9 +45,7 @@ services:
 
   # Python FastAPI Service Adapters
   service-adapters:
-    build:
-      context: ./services/service-adapters
-      dockerfile: Dockerfile
+    image: gittea.kammenstraatha.duckdns.org/admin/service-adapters:main
     ports:
       - "8000:8000"
     environment:
@@ -63,9 +60,7 @@ services:
 
   # React Frontend
   frontend:
-    build:
-      context: ./frontend
-      dockerfile: Dockerfile
+    image: gittea.kammenstraatha.duckdns.org/admin/frontend:main
     ports:
       - "3000:3000"
     environment:
@@ -78,9 +73,7 @@ services:
 
   # API Documentation Service
   api-docs:
-    build:
-      context: ./services/api-docs
-      dockerfile: Dockerfile
+    image: gittea.kammenstraatha.duckdns.org/admin/api-docs:cache
     ports:
       - "8083:8083"
     environment:
@@ -97,6 +90,7 @@ services:
 volumes:
   postgres_data:
   redis_data:
+  maven_cache:
 
 networks:
   labfusion-network:

docs/GITEA_DEPLOYMENT.md

@@ -0,0 +1,172 @@
+# LabFusion Gitea Registry Deployment
+
+This guide explains how to deploy LabFusion using images from your Gitea container registry.
+
+## Registry Information
+
+- **Registry URL**: `gittea.kammenstraatha.duckdns.org/admin`
+- **Username**: `admin`
+- **Image Tag**: `main`
+
+## Quick Start
+
+### 1. Authentication
+
+First, authenticate with your Gitea registry:
+
+```bash
+# Login to Gitea registry
+docker login gittea.kammenstraatha.duckdns.org/admin
+# Enter your Gitea username and password when prompted
+```
+
+### 2. Configuration
+
+The Docker Compose files are already configured to use your Gitea registry by default. No additional configuration is needed unless you want to override the defaults.
+
+**Default Configuration:**
+```bash
+DOCKER_REGISTRY=gittea.kammenstraatha.duckdns.org/admin
+DOCKER_USERNAME=admin
+IMAGE_TAG=main
+```
+
+### 3. Deploy
+
+```bash
+# Production deployment
+docker-compose up -d
+
+# Development deployment (with volume mounts)
+docker-compose -f docker-compose.dev.yml up -d
+```
+
+## Image URLs
+
+Your LabFusion images are available at:
+
+- **API Gateway**: `gittea.kammenstraatha.duckdns.org/admin/api-gateway:main`
+- **Service Adapters**: `gittea.kammenstraatha.duckdns.org/admin/service-adapters:main`
+- **Frontend**: `gittea.kammenstraatha.duckdns.org/admin/frontend:main`
+- **API Docs**: `gittea.kammenstraatha.duckdns.org/admin/api-docs:main`
+
+## Verification
+
+### Check if images are accessible:
+
+```bash
+# Test pulling each image
+docker pull gittea.kammenstraatha.duckdns.org/admin/api-gateway:main
+docker pull gittea.kammenstraatha.duckdns.org/admin/service-adapters:main
+docker pull gittea.kammenstraatha.duckdns.org/admin/frontend:main
+docker pull gittea.kammenstraatha.duckdns.org/admin/api-docs:main
+```
+
+### Check running services:
+
+```bash
+# View running containers
+docker-compose ps
+
+# Check logs
+docker-compose logs api-gateway
+docker-compose logs service-adapters
+docker-compose logs frontend
+docker-compose logs api-docs
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failed**:
+   ```bash
+   # Re-authenticate
+   docker logout gittea.kammenstraatha.duckdns.org/admin
+   docker login gittea.kammenstraatha.duckdns.org/admin
+   ```
+
+2. **Image Not Found**:
+   ```bash
+   # Check if images exist in registry
+   curl -u admin:password https://gittea.kammenstraatha.duckdns.org/admin/v2/_catalog
+   ```
+
+3. **Network Issues**:
+   ```bash
+   # Test connectivity
+   ping gittea.kammenstraatha.duckdns.org
+   curl -I https://gittea.kammenstraatha.duckdns.org/admin/v2/
+   ```
+
+4. **Permission Denied**:
+   - Verify you have access to the `admin` organization
+   - Check if the images are public or require authentication
+   - Ensure your Gitea account has the necessary permissions
+
+### Debug Commands
+
+```bash
+# Check Docker daemon logs
+docker system events
+
+# Inspect image details
+docker inspect gittea.kammenstraatha.duckdns.org/admin/api-gateway:main
+
+# Check registry connectivity
+docker pull gittea.kammenstraatha.duckdns.org/admin/api-gateway:main
+```
+
+## Environment Variables
+
+You can override the default registry settings by setting environment variables:
+
+```bash
+# Use different tag
+export IMAGE_TAG=v1.0.0
+docker-compose up -d
+
+# Use different registry (if you have multiple)
+export DOCKER_REGISTRY=your-other-registry.com
+export DOCKER_USERNAME=your-username
+docker-compose up -d
+```
+
+## CI/CD Integration
+
+If you're using Gitea Actions to build and push images, ensure your workflow pushes to the correct registry:
+
+```yaml
+# Example Gitea Actions workflow
+- name: Build and Push Images
+  run: |
+    # Build and tag images
+    docker build -t gittea.kammenstraatha.duckdns.org/admin/api-gateway:main ./services/api-gateway
+    docker build -t gittea.kammenstraatha.duckdns.org/admin/service-adapters:main ./services/service-adapters
+    docker build -t gittea.kammenstraatha.duckdns.org/admin/frontend:main ./frontend
+    docker build -t gittea.kammenstraatha.duckdns.org/admin/api-docs:main ./services/api-docs
+    
+    # Push to registry
+    docker push gittea.kammenstraatha.duckdns.org/admin/api-gateway:main
+    docker push gittea.kammenstraatha.duckdns.org/admin/service-adapters:main
+    docker push gittea.kammenstraatha.duckdns.org/admin/frontend:main
+    docker push gittea.kammenstraatha.duckdns.org/admin/api-docs:main
+```
+
+## Security Considerations
+
+- **Authentication**: Always authenticate before pulling images
+- **HTTPS**: Ensure your Gitea registry uses HTTPS
+- **Access Control**: Verify that only authorized users can access the images
+- **Image Scanning**: Regularly scan images for vulnerabilities
+- **Updates**: Keep images updated with security patches
+
+## Support
+
+If you encounter issues with the Gitea registry deployment:
+
+1. Check the troubleshooting section above
+2. Verify your Gitea registry configuration
+3. Check network connectivity to `gittea.kammenstraatha.duckdns.org`
+4. Ensure you have proper permissions in the `admin` organization
+5. Review Docker and Docker Compose logs for detailed error messages

docs/structure.txt

@@ -146,6 +146,16 @@ runners/
     ├── data_docker/           # Docker runner data directory
     └── data_security/         # Security runner data directory
 
+# Scripts
+scripts/
+├── check-registry.ps1        # Windows PowerShell registry check script
+├── check-registry.sh         # Linux/macOS registry check script
+├── docker-compatibility.ps1  # Windows PowerShell Docker compatibility fix
+├── docker-compatibility.sh   # Linux/macOS Docker compatibility fix
+├── fix-docker-compatibility.ps1 # Windows PowerShell quick fix script
+├── fix-docker-compatibility.sh  # Linux/macOS quick fix script
+└── test-docker-compatibility.ps1 # Windows PowerShell compatibility test
+
 └── docs/                      # Documentation
     ├── specs.md              # Project specifications
     ├── structure.txt         # Project structure
@@ -156,4 +166,6 @@ runners/
     ├── DOCKER_RATE_LIMIT_FIX.md # Docker Hub rate limit solutions
     ├── CI_CD.md              # CI/CD pipeline documentation
     ├── CACHE_TROUBLESHOOTING.md # Cache troubleshooting guide
-    └── SONARQUBE_INTEGRATION.md # SonarQube integration documentation
+    ├── SONARQUBE_INTEGRATION.md # SonarQube integration documentation
+    ├── DOCKER_DEPLOYMENT.md  # Docker deployment and registry guide
+    └── DOCKER_COMPATIBILITY.md # Docker version compatibility guide

env.example

@@ -1,3 +1,8 @@
+# Docker Registry Configuration
+DOCKER_REGISTRY=gittea.kammenstraatha.duckdns.org/admin
+DOCKER_USERNAME=admin
+IMAGE_TAG=main
+
 # Database Configuration
 POSTGRES_DB=labfusion
 POSTGRES_USER=labfusion

services/api-docs/Dockerfile

@@ -1,18 +1,31 @@
-FROM node:18-alpine
+FROM node:20-alpine
 
+# Set working directory
 WORKDIR /app
 
-# Copy package files
+# Copy package files first for better caching
 COPY package*.json ./
 
-# Install dependencies
-RUN npm install --only=production
+# Install dependencies with npm ci for production builds
+RUN npm ci --only=production && npm cache clean --force
 
 # Copy source code
 COPY . .
 
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nextjs -u 1001
+
+# Change ownership of the app directory
+RUN chown -R nextjs:nodejs /app
+USER nextjs
+
 # Expose port
 EXPOSE 8083
 
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:8083/health || exit 1
+
 # Start the application
 CMD ["npm", "start"]

services/api-docs/Dockerfile.dev

@@ -1,18 +1,31 @@
 FROM node:18-alpine
 
+# Set working directory
 WORKDIR /app
 
-# Copy package files
+# Copy package files first for better caching
 COPY package*.json ./
 
-# Install dependencies
-RUN npm install
+# Install dependencies with npm ci for production builds
+RUN npm ci --only=production && npm cache clean --force
 
 # Copy source code
 COPY . .
 
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nextjs -u 1001
+
+# Change ownership of the app directory
+RUN chown -R nextjs:nodejs /app
+USER nextjs
+
 # Expose port
 EXPOSE 8083
 
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:8083/health || exit 1
+
 # Start the application in development mode
 CMD ["npm", "run", "dev"]

services/api-gateway/src/main/java/com/labfusion/config/OpenApiConfig.java

@@ -2,7 +2,6 @@ package com.labfusion.config;
 
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Info;
-import io.swagger.v3.oas.models.info.Contact;
 import io.swagger.v3.oas.models.info.License;
 import io.swagger.v3.oas.models.servers.Server;
 import io.swagger.v3.oas.models.security.SecurityRequirement;