fix: load PaddleOCR model in background thread

The import and model loading can take minutes and was blocking
the startup event, causing health checks to timeout. Now loads
in a background thread — health endpoint returns 200 immediately
with status 'loading' until model is ready.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.coolify.example

@@ -0,0 +1,65 @@
+# =========================================================
+# BreakPilot Core — Coolify Environment Variables
+# =========================================================
+# Copy these into Coolify's environment variable UI
+# for the breakpilot-core Docker Compose resource.
+# =========================================================
+
+# --- External PostgreSQL (Coolify-managed) ---
+POSTGRES_HOST=<coolify-postgres-hostname>
+POSTGRES_PORT=5432
+POSTGRES_USER=breakpilot
+POSTGRES_PASSWORD=CHANGE_ME_STRONG_PASSWORD
+POSTGRES_DB=breakpilot_db
+
+# --- Security ---
+JWT_SECRET=CHANGE_ME_RANDOM_64_CHARS
+JWT_REFRESH_SECRET=CHANGE_ME_ANOTHER_RANDOM_64_CHARS
+INTERNAL_API_KEY=CHANGE_ME_INTERNAL_KEY
+
+# --- External S3 Storage ---
+S3_ENDPOINT=<s3-endpoint-host:port>
+S3_ACCESS_KEY=CHANGE_ME_S3_ACCESS_KEY
+S3_SECRET_KEY=CHANGE_ME_S3_SECRET_KEY
+S3_BUCKET=breakpilot-rag
+S3_SECURE=true
+
+# --- External Qdrant (Coolify-managed) ---
+QDRANT_URL=http://<coolify-qdrant-hostname>:6333
+QDRANT_API_KEY=
+
+# --- SMTP (Real mail server) ---
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USERNAME=noreply@breakpilot.ai
+SMTP_PASSWORD=CHANGE_ME_SMTP_PASSWORD
+SMTP_FROM_NAME=BreakPilot
+SMTP_FROM_ADDR=noreply@breakpilot.ai
+
+# --- Session ---
+SESSION_TTL_HOURS=24
+
+# --- Frontend URLs (build args) ---
+NEXT_PUBLIC_CORE_API_URL=https://api-core.breakpilot.ai
+FRONTEND_URL=https://www.breakpilot.ai
+
+# --- Stripe (Billing) ---
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+STRIPE_PUBLISHABLE_KEY=
+BILLING_SUCCESS_URL=https://www.breakpilot.ai/billing/success
+BILLING_CANCEL_URL=https://www.breakpilot.ai/billing/cancel
+TRIAL_PERIOD_DAYS=14
+
+# --- Embedding Service ---
+EMBEDDING_BACKEND=local
+LOCAL_EMBEDDING_MODEL=BAAI/bge-m3
+LOCAL_RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
+PDF_EXTRACTION_BACKEND=pymupdf
+OPENAI_API_KEY=
+COHERE_API_KEY=
+LOG_LEVEL=INFO
+
+# --- Ollama (optional, for RAG embeddings) ---
+OLLAMA_URL=
+OLLAMA_EMBED_MODEL=bge-m3

.gitea/workflows/deploy-coolify.yml

@@ -0,0 +1,27 @@
+name: Deploy to Coolify
+
+on:
+  push:
+    branches:
+      - coolify
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy via Coolify API
+        run: |
+          echo "Deploying breakpilot-core to Coolify..."
+          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+            -X POST \
+            -H "Authorization: Bearer ${{ secrets.COOLIFY_API_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d '{"uuid": "${{ secrets.COOLIFY_RESOURCE_UUID }}", "force_rebuild": true}' \
+            "${{ secrets.COOLIFY_BASE_URL }}/api/v1/deploy")
+
+          echo "HTTP Status: $HTTP_STATUS"
+          if [ "$HTTP_STATUS" -ne 200 ] && [ "$HTTP_STATUS" -ne 201 ]; then
+            echo "Deployment failed with status $HTTP_STATUS"
+            exit 1
+          fi
+          echo "Deployment triggered successfully!"

admin-core/Dockerfile

@@ -18,6 +18,9 @@ ARG NEXT_PUBLIC_API_URL
 # Set environment variables for build
 ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
 
+# Ensure public directory exists
+RUN mkdir -p public
+
 # Build the application
 RUN npm run build
 
@@ -30,8 +33,8 @@ WORKDIR /app
 ENV NODE_ENV=production
 
 # Create non-root user
-RUN addgroup --system --gid 1001 nodejs
-RUN adduser --system --uid 1001 nextjs
+RUN addgroup -S -g 1001 nodejs
+RUN adduser -S -u 1001 -G nodejs nextjs
 
 # Copy built assets
 COPY --from=builder /app/public ./public

backend-core/Dockerfile

@@ -43,11 +43,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && rm -rf /var/lib/apt/lists/*
 
 # Install DevSecOps tools (gitleaks, trivy, grype, syft)
-ARG TARGETARCH=arm64
+ARG TARGETARCH
 RUN set -eux; \
+    ARCH="${TARGETARCH:-$(dpkg --print-architecture)}"; \
     # Gitleaks
     GITLEAKS_VERSION=8.21.2; \
-    if [ "$TARGETARCH" = "arm64" ]; then GITLEAKS_ARCH=arm64; else GITLEAKS_ARCH=x64; fi; \
+    if [ "$ARCH" = "arm64" ]; then GITLEAKS_ARCH=arm64; else GITLEAKS_ARCH=x64; fi; \
     curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_${GITLEAKS_ARCH}.tar.gz" \
       | tar xz -C /usr/local/bin gitleaks; \
     # Trivy

docker-compose.coolify.yml

@@ -0,0 +1,195 @@
+# =========================================================
+# BreakPilot Core — Shared Infrastructure (Coolify)
+# =========================================================
+# Deployed via Coolify. SSL termination handled by Traefik.
+# External services (managed separately in Coolify):
+#   - PostgreSQL (PostGIS), Qdrant, S3-compatible storage
+# Network: breakpilot-network (shared across all 3 repos)
+# =========================================================
+
+networks:
+  breakpilot-network:
+    name: breakpilot-network
+    driver: bridge
+
+volumes:
+  valkey_data:
+  embedding_models:
+  paddleocr_models:
+
+services:
+
+  # =========================================================
+  # CACHE
+  # =========================================================
+  valkey:
+    image: valkey/valkey:8-alpine
+    container_name: bp-core-valkey
+    volumes:
+      - valkey_data:/data
+    command: valkey-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+    networks:
+      - breakpilot-network
+
+  # =========================================================
+  # SHARED SERVICES
+  # =========================================================
+  consent-service:
+    build:
+      context: ./consent-service
+      dockerfile: Dockerfile
+    container_name: bp-core-consent-service
+    expose:
+      - "8081"
+    environment:
+      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT:-5432}/${POSTGRES_DB}
+      JWT_SECRET: ${JWT_SECRET}
+      JWT_REFRESH_SECRET: ${JWT_REFRESH_SECRET}
+      PORT: 8081
+      ENVIRONMENT: production
+      ALLOWED_ORIGINS: "*"
+      VALKEY_URL: redis://valkey:6379/0
+      SESSION_TTL_HOURS: ${SESSION_TTL_HOURS:-24}
+      SMTP_HOST: ${SMTP_HOST}
+      SMTP_PORT: ${SMTP_PORT:-587}
+      SMTP_USERNAME: ${SMTP_USERNAME}
+      SMTP_PASSWORD: ${SMTP_PASSWORD}
+      SMTP_FROM_NAME: ${SMTP_FROM_NAME:-BreakPilot}
+      SMTP_FROM_ADDR: ${SMTP_FROM_ADDR:-noreply@breakpilot.ai}
+      FRONTEND_URL: ${FRONTEND_URL:-https://www.breakpilot.ai}
+    depends_on:
+      valkey:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8081/health"]
+      interval: 30s
+      timeout: 10s
+      start_period: 15s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - breakpilot-network
+
+  # =========================================================
+  # RAG & EMBEDDING SERVICES
+  # =========================================================
+  rag-service:
+    build:
+      context: ./rag-service
+      dockerfile: Dockerfile
+    container_name: bp-core-rag-service
+    expose:
+      - "8097"
+    environment:
+      PORT: 8097
+      QDRANT_URL: ${QDRANT_URL}
+      QDRANT_API_KEY: ${QDRANT_API_KEY:-}
+      MINIO_ENDPOINT: ${S3_ENDPOINT}
+      MINIO_ACCESS_KEY: ${S3_ACCESS_KEY}
+      MINIO_SECRET_KEY: ${S3_SECRET_KEY}
+      MINIO_BUCKET: ${S3_BUCKET:-breakpilot-rag}
+      MINIO_SECURE: ${S3_SECURE:-true}
+      EMBEDDING_SERVICE_URL: http://embedding-service:8087
+      OLLAMA_URL: ${OLLAMA_URL:-}
+      OLLAMA_EMBED_MODEL: ${OLLAMA_EMBED_MODEL:-bge-m3}
+      JWT_SECRET: ${JWT_SECRET}
+      ENVIRONMENT: production
+    depends_on:
+      embedding-service:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://127.0.0.1:8097/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 15s
+    restart: unless-stopped
+    networks:
+      - breakpilot-network
+
+  embedding-service:
+    build:
+      context: ./embedding-service
+      dockerfile: Dockerfile
+    container_name: bp-core-embedding-service
+    volumes:
+      - embedding_models:/root/.cache/huggingface
+    environment:
+      EMBEDDING_BACKEND: ${EMBEDDING_BACKEND:-local}
+      LOCAL_EMBEDDING_MODEL: ${LOCAL_EMBEDDING_MODEL:-BAAI/bge-m3}
+      LOCAL_RERANKER_MODEL: ${LOCAL_RERANKER_MODEL:-cross-encoder/ms-marco-MiniLM-L-6-v2}
+      PDF_EXTRACTION_BACKEND: ${PDF_EXTRACTION_BACKEND:-pymupdf}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+      COHERE_API_KEY: ${COHERE_API_KEY:-}
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+    deploy:
+      resources:
+        limits:
+          memory: 8G
+    healthcheck:
+      test: ["CMD", "python", "-c", "import httpx; r=httpx.get('http://127.0.0.1:8087/health'); r.raise_for_status()"]
+      interval: 30s
+      timeout: 10s
+      start_period: 120s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - breakpilot-network
+
+  # =========================================================
+  # OCR SERVICE (PaddleOCR PP-OCRv5 Latin)
+  # =========================================================
+  paddleocr-service:
+    build:
+      context: ./paddleocr-service
+      dockerfile: Dockerfile
+    container_name: bp-core-paddleocr
+    ports:
+      - "8095:8095"
+    environment:
+      PADDLEOCR_API_KEY: ${PADDLEOCR_API_KEY:-}
+      FLAGS_use_mkldnn: "0"
+    volumes:
+      - paddleocr_models:/root/.paddleocr
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://127.0.0.1:8095/health"]
+      interval: 30s
+      timeout: 10s
+      start_period: 300s
+      retries: 5
+    restart: unless-stopped
+    networks:
+      - breakpilot-network
+
+  # =========================================================
+  # HEALTH AGGREGATOR
+  # =========================================================
+  health-aggregator:
+    build:
+      context: ./scripts
+      dockerfile: Dockerfile.health
+    container_name: bp-core-health
+    expose:
+      - "8099"
+    environment:
+      PORT: 8099
+      CHECK_SERVICES: "valkey:6379,consent-service:8081,rag-service:8097,embedding-service:8087,paddleocr-service:8095"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://127.0.0.1:8099/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - breakpilot-network
+

paddleocr-service/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 libglib2.0-0 libgomp1 curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8095
+HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
+    CMD curl -f http://127.0.0.1:8095/health || exit 1
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8095"]

paddleocr-service/main.py

@@ -0,0 +1,111 @@
+"""PaddleOCR Remote Service — PP-OCRv5 Latin auf x86_64."""
+
+import io
+import logging
+import os
+import threading
+
+import numpy as np
+from fastapi import FastAPI, File, Header, HTTPException, UploadFile
+from PIL import Image
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="PaddleOCR Service")
+
+_engine = None
+_ready = False
+_loading = False
+API_KEY = os.environ.get("PADDLEOCR_API_KEY", "")
+
+
+def _load_model():
+    """Load PaddleOCR model in background thread."""
+    global _engine, _ready
+    try:
+        logger.info("Importing paddleocr...")
+        from paddleocr import PaddleOCR
+
+        logger.info("Import done. Loading PaddleOCR model...")
+        try:
+            _engine = PaddleOCR(
+                lang="en",
+                ocr_version="PP-OCRv5",
+                use_angle_cls=True,
+                show_log=False,
+            )
+            logger.info("Using PP-OCRv5 (en)")
+        except Exception as e:
+            logger.info(f"PP-OCRv5 failed ({e}), trying latin fallback...")
+            _engine = PaddleOCR(
+                lang="latin",
+                use_angle_cls=True,
+                show_log=False,
+            )
+            logger.info("Using PP-OCRv4 fallback (latin)")
+        _ready = True
+        logger.info("PaddleOCR model loaded successfully — ready to serve")
+    except Exception as e:
+        logger.error(f"Failed to load PaddleOCR model: {e}")
+
+
+@app.on_event("startup")
+def startup_load_model():
+    """Start model loading in background so health check passes immediately."""
+    global _loading
+    _loading = True
+    thread = threading.Thread(target=_load_model, daemon=True)
+    thread.start()
+    logger.info("Model loading started in background thread")
+
+
+@app.get("/health")
+def health():
+    if _ready:
+        return {"status": "ok", "model": "PP-OCRv5-latin"}
+    if _loading:
+        return {"status": "loading"}
+    return {"status": "error"}
+
+
+@app.post("/ocr")
+async def ocr(
+    file: UploadFile = File(...),
+    x_api_key: str = Header(default=""),
+):
+    if API_KEY and x_api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+    if not _ready:
+        raise HTTPException(status_code=503, detail="Model still loading")
+
+    img_bytes = await file.read()
+    img = Image.open(io.BytesIO(img_bytes)).convert("RGB")
+    img_np = np.array(img)
+
+    result = _engine.ocr(img_np)
+
+    words = []
+    for line in result[0] or []:
+        box, (text, conf) = line[0], line[1]
+        x_min = min(p[0] for p in box)
+        y_min = min(p[1] for p in box)
+        x_max = max(p[0] for p in box)
+        y_max = max(p[1] for p in box)
+        words.append(
+            {
+                "text": text.strip(),
+                "left": int(x_min),
+                "top": int(y_min),
+                "width": int(x_max - x_min),
+                "height": int(y_max - y_min),
+                "conf": round(conf * 100, 1),
+            }
+        )
+
+    return {
+        "words": words,
+        "image_width": img_np.shape[1],
+        "image_height": img_np.shape[0],
+    }

paddleocr-service/requirements.txt

@@ -0,0 +1,7 @@
+paddlepaddle==2.6.2
+paddleocr==2.8.1
+fastapi>=0.110.0
+uvicorn>=0.25.0
+python-multipart>=0.0.6
+Pillow>=10.0.0
+numpy>=1.24.0

rag-service/config.py

@@ -6,6 +6,7 @@ class Settings:
 
     # Qdrant
     QDRANT_URL: str = os.getenv("QDRANT_URL", "http://localhost:6333")
+    QDRANT_API_KEY: str = os.getenv("QDRANT_API_KEY", "")
 
     # MinIO
     MINIO_ENDPOINT: str = os.getenv("MINIO_ENDPOINT", "localhost:9000")

rag-service/qdrant_client_wrapper.py

@@ -46,7 +46,11 @@ class QdrantClientWrapper:
     @property
     def client(self) -> QdrantClient:
         if self._client is None:
-            self._client = QdrantClient(url=settings.QDRANT_URL, timeout=30)
+            self._client = QdrantClient(
+                url=settings.QDRANT_URL,
+                api_key=settings.QDRANT_API_KEY or None,
+                timeout=30,
+            )
             logger.info("Connected to Qdrant at %s", settings.QDRANT_URL)
         return self._client