Skip to content

Latest commit

 

History

History
284 lines (222 loc) · 9.09 KB

deployment_docker_multiarch.md

File metadata and controls

284 lines (222 loc) · 9.09 KB

ThemisDB Multi-Architecture Docker Build-Strategie

Stand: 26. Dezember 2025
Version: v1.3.1
Kategorie: 🚀 Deployment

📑 Inhaltsverzeichnis

Übersicht

ThemisDB unterstützt drei Zielplattformen mit optimierten Docker-Images:

Plattform Architektur vcpkg Triplet Primärer Use Case
AMD64 x86_64 x64-linux Server, Cloud (AWS/Azure/GCP)
ARM64 aarch64 arm64-linux Raspberry Pi 4/5, ARM-Server (Graviton)
ARMv7 armhf arm-linux Raspberry Pi 3, ältere ARM-Devices

Build-Strategie

1. Compiler-Matrix

Windows (Lokale Entwicklung)

  • Primary: MSVC (Visual Studio 2022) + Ninja
  • Secondary: ClangCL (für cross-platform Konsistenz)
  • Package Manager: vcpkg (system-weit via VCPKG_ROOT)
  • Tools: clang-tidy (Code-Qualität), clang-format (Formatierung)

Linux/Docker (Production Deployment)

  • Compiler: gcc/g++ 11.4.0 (Ubuntu 22.04 base)
  • Generator: Ninja
  • Package Manager: vcpkg Manifest Mode (Container-isoliert)
  • Strategie: Konsistenter Toolchain über alle Architekturen

2. Dockerfile Multi-Arch Support

# Auto-detect und Triplet-Mapping
ARG TARGETARCH  # Docker BuildKit variable (amd64|arm64|arm)

RUN TRIPLET="${VCPKG_TRIPLET}"; \
    if [ -z "$TRIPLET" ]; then \
      case "${TARGETARCH}" in \
        amd64) TRIPLET=x64-linux ;; \
        arm64) TRIPLET=arm64-linux ;; \
        arm) TRIPLET=arm-linux ;; \
        *) TRIPLET=x64-linux ;; \
      esac; \
    fi && \
    echo "export VCPKG_TRIPLET=${TRIPLET}" > /etc/profile.d/vcpkg.sh

Wichtig:

  • TARGETARCH wird automatisch von Docker BuildKit gesetzt bei docker buildx build --platform
  • Fallback auf x64-linux für unbekannte Architekturen
  • Triplet wird in /etc/profile.d/vcpkg.sh persistiert für alle Build-Stages

3. vcpkg Dependency Management

Strategie: Manifest Mode mit Baseline-Pinning

// vcpkg.docker.json (Container-spezifisch)
{
  "dependencies": [
    "openssl",
    "rocksdb",
    { "name": "arrow", "features": ["json", "filesystem"] },
    "boost-asio",
    "boost-beast",
    // ... weitere 20 Pakete
  ]
}

Vorteile:

  • ✅ Reproduzierbare Builds: Baseline-Commit pinnt exakte Dependency-Versionen
  • ✅ Layer Caching: Manifest-Copy vor Source-Copy → Dependencies ändern sich seltener
  • ✅ Cross-Arch Konsistenz: Gleiche vcpkg-Versionen auf x64/arm64/arm
  • ✅ Binary Caching: Potenzial für CI/CD-Beschleunigung (aktuell deaktiviert)

Baseline-Synchronisierung:

RUN cd ${VCPKG_ROOT} \
    && VCPKG_BASELINE=$(git rev-parse HEAD) \
    && echo "{\"default-registry\":{\"kind\":\"builtin\",\"baseline\":\"$VCPKG_BASELINE\"}}" \
        > /src/vcpkg-configuration.json

4. Raspberry Pi ARM-Spezifika

ARMv8 (64-bit) - Raspberry Pi 4/5

  • Triplet: arm64-linux
  • NEON SIMD: Vollständig unterstützt (128-bit Vektoren)
  • FMA Support: ARMv8.2+ (ab Pi 4)
  • Optimierungen: 
    # CMakeLists.txt automatische NEON-Erkennung
if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
    target_compile_options(themis_core PRIVATE -march=armv8-a+fp+simd)
endif()

ARMv7 (32-bit) - Raspberry Pi 2/3

  • Triplet: arm-linux
  • NEON SIMD: Optional (abhängig von CPU-Modell)
  • Einschränkungen:
    • Weniger RAM (1-2GB typisch)
    • Langsamere Builds (single-/dual-core)
  • Empfehlung: Cross-Compilation von x64-Host bevorzugen

Build-Zeit-Optimierungen für ARM:

ENV VCPKG_MAX_CONCURRENCY=2  # Reduziert RAM-Verbrauch
ENV VCPKG_USE_ARIA2=1        # Schnellere Downloads

5. Multi-Arch Image Build

Lokaler Build (Single-Arch):

# AMD64 (Standard)
docker build -t themis:latest -f Dockerfile .

# ARM64 (mit BuildKit Emulation)
docker buildx build --platform linux/arm64 -t themis:arm64 -f Dockerfile .

Multi-Arch Manifest (Docker Hub):

# Buildx Setup (einmalig)
docker buildx create --name themis-builder --use
docker buildx inspect --bootstrap

# Build & Push für alle Architekturen
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 \
    -t makrcode/themis:latest \
    -t makrcode/themis:1.0.0 \
    --push \
    -f Dockerfile .

# Manifest verifizieren
docker buildx imagetools inspect makrcode/themis:latest

Ergebnis:

  • Docker Hub speichert 3 Images (amd64, arm64, armv7)
  • docker pull themis:latest wählt automatisch korrekte Architektur
  • TARGETARCH wird von BuildKit automatisch pro Platform gesetzt

6. Runtime-Stage (Slim Image)

FROM ubuntu:22.04 AS runtime

# Multi-Arch Library Copy
ARG TARGETARCH
RUN VCPKG_TRIPLET_COPY="x64-linux"; \
    case "${TARGETARCH}" in \
      amd64) VCPKG_TRIPLET_COPY="x64-linux" ;; \
      arm64) VCPKG_TRIPLET_COPY="arm64-linux" ;; \
      arm) VCPKG_TRIPLET_COPY="arm-linux" ;; \
    esac && \
    cp -v /opt/vcpkg/installed/${VCPKG_TRIPLET_COPY}/lib/*.so* /usr/local/lib/

Vorteile:

  • Minimale Image-Größe (nur Runtime-Dependencies)
  • Keine Build-Tools im Production-Image
  • Identischer Entrypoint über alle Architekturen

Performance-Erwartungen

Vector-Search Benchmarks (1M vectors, 768 dims)

Plattform Architektur QPS (batch=1) Speedup vs Scalar SIMD
Intel Xeon (AVX2) x86_64 12,000 4.2x AVX2
AMD EPYC (AVX512) x86_64 18,500 6.8x AVX512
AWS Graviton3 arm64 9,200 3.1x NEON + FMA
Raspberry Pi 4 arm64 1,800 2.8x NEON
Raspberry Pi 3 armv7 420 1.9x NEON (partial)

Benchmark: bench_vector_search mit HNSW Index, ef=64

Build-Zeiten (vcpkg Dependencies + ThemisDB)

Plattform Vollständiger Build Incremental Rebuild
x64 (16 cores, 32GB RAM) ~12 Minuten ~2 Minuten
ARM64 (4 cores, 8GB RAM) ~45 Minuten ~8 Minuten
ARMv7 (4 cores, 2GB RAM) ~2.5 Stunden ~15 Minuten

Empfehlung für ARMv7: Cross-Compilation verwenden

QNAP-Spezifika (Separate Strategie)

QNAP-NAS-Systeme benötigen statisch gelinkte Binaries wegen alter GLIBC-Versionen:

# Dockerfile.qnap (separates File)
FROM ubuntu:20.04  # GLIBC 2.31 (älter als 22.04)

# Static Linking
RUN cmake ... -DTHEMIS_STATIC_BUILD=ON

Separate Manifest: vcpkg.qnap.json mit statischen Library-Varianten

Tags:

  • themis:latest → Standard (Ubuntu 22.04, dynamisch gelinkt)
  • themis-qnap:latest → QNAP (Ubuntu 20.04, statisch gelinkt)

Deployment-Matrix

Ziel-Umgebung Empfohlenes Image Architektur Besonderheiten
AWS EC2 (x86) themis:latest amd64 AVX2-Optimierung
AWS Graviton themis:latest arm64 NEON-Optimierung
Azure VMs themis:latest amd64 Standard
Raspberry Pi 4/5 themis:latest arm64 4GB+ RAM empfohlen
Raspberry Pi 3 themis:latest arm/v7 Swap-File notwendig
QNAP NAS themis-qnap:latest amd64/arm64 Static Build
Synology NAS themis:latest amd64/arm64 Docker Package

Best Practices

1. Layer Caching Optimieren

# ✅ Gut: Manifest vor Source-Code kopieren
COPY vcpkg.docker.json ./vcpkg.json
RUN vcpkg install --triplet=${VCPKG_TRIPLET}
COPY . /src

# ❌ Schlecht: Source-Änderungen invalidieren Dependency-Layer
COPY . /src
RUN vcpkg install

2. Cross-Compilation für ARM verwenden

# Auf x64-Host: ARM64-Image bauen (mit QEMU)
docker run --privileged --rm tonistiigi/binfmt --install all
docker buildx build --platform linux/arm64 -t themis:arm64 .

10-20x schneller als nativer ARM-Build auf Raspberry Pi

3. Binary Caching (CI/CD)

ENV VCPKG_BINARY_SOURCES="clear;nuget,GitHub,readwrite"

Spart ~80% Build-Zeit bei wiederholten Builds (nicht in ersten Release implementiert)

4. Healthcheck implementieren

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

Nächste Schritte

  • GitHub Actions Workflow für automatische Multi-Arch Builds
  • Docker Hub Push-Automation mit Tags latest, 1.0.0, arm64, qnap
  • Binary Caching via GitHub Packages für CI-Beschleunigung
  • ARM-Benchmarks dokumentieren (siehe docs/ARM_BENCHMARKS.md)
  • Cross-Compilation Toolchain für lokale ARM-Entwicklung auf x64

Referenzen