From 7bb753e293c43b507829defb9e7c42d6f9d1f80d Mon Sep 17 00:00:00 2001 From: GSRN Date: Thu, 18 Sep 2025 00:28:21 +0200 Subject: [PATCH] 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 | 78 +++++++- README.md | 51 +++++- docker-compose.dev.yml | 8 + docker-compose.yml | 20 +- docs/GITEA_DEPLOYMENT.md | 172 ++++++++++++++++++ docs/structure.txt | 14 +- env.example | 5 + services/api-docs/Dockerfile | 21 ++- services/api-docs/Dockerfile.dev | 19 +- .../com/labfusion/config/OpenApiConfig.java | 1 - 10 files changed, 361 insertions(+), 28 deletions(-) create mode 100644 docs/GITEA_DEPLOYMENT.md diff --git a/.gitea/workflows/docker-build.yml b/.gitea/workflows/docker-build.yml index 1c7ed4e..49978c5 100644 --- a/.gitea/workflows/docker-build.yml +++ b/.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" diff --git a/README.md b/README.md index c242ac9..050c921 100644 --- a/README.md +++ b/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 diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index f932db8..2a79524 100644 --- a/docker-compose.dev.yml +++ b/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: diff --git a/docker-compose.yml b/docker-compose.yml index 524fc12..07602bc 100644 --- a/docker-compose.yml +++ b/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: diff --git a/docs/GITEA_DEPLOYMENT.md b/docs/GITEA_DEPLOYMENT.md new file mode 100644 index 0000000..65f08ed --- /dev/null +++ b/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 diff --git a/docs/structure.txt b/docs/structure.txt index 47e7b85..7310f12 100644 --- a/docs/structure.txt +++ b/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 \ No newline at end of file + ├── SONARQUBE_INTEGRATION.md # SonarQube integration documentation + ├── DOCKER_DEPLOYMENT.md # Docker deployment and registry guide + └── DOCKER_COMPATIBILITY.md # Docker version compatibility guide \ No newline at end of file diff --git a/env.example b/env.example index ea0fe23..06fa417 100644 --- a/env.example +++ b/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 diff --git a/services/api-docs/Dockerfile b/services/api-docs/Dockerfile index 681db6c..b94def0 100644 --- a/services/api-docs/Dockerfile +++ b/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"] diff --git a/services/api-docs/Dockerfile.dev b/services/api-docs/Dockerfile.dev index 9e1dcd2..349b543 100644 --- a/services/api-docs/Dockerfile.dev +++ b/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"] diff --git a/services/api-gateway/src/main/java/com/labfusion/config/OpenApiConfig.java b/services/api-gateway/src/main/java/com/labfusion/config/OpenApiConfig.java index 0b57e2d..dabdc74 100644 --- a/services/api-gateway/src/main/java/com/labfusion/config/OpenApiConfig.java +++ b/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;