Release vNext: Embed API, ARM64 Docker Support, Data Hygiene UX Improvements & Documentation Enhancements

.github/workflows/docker.yml

@@ -16,22 +16,11 @@ env:
   REGISTRY: ghcr.io
 
 jobs:
-  build-and-push:
+  prepare-tags-and-names:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        service:
-          - name: frontend
-            image: librislog
-            dockerfile: ./frontend/Dockerfile
-            context: ./frontend
-          - name: backend
-            image: librislog-api
-            dockerfile: ./backend/Dockerfile
-            context: ./backend
+
     permissions:
       contents: read
-      packages: write
 
     steps:
       - name: Checkout repository
@@ -59,6 +48,54 @@ jobs:
           SANITIZED="$(echo "$SANITIZED" | sed 's/^[^a-zA-Z0-9_]\+//')"
           echo "sanitized_tag=${SANITIZED:0:128}" >> "$GITHUB_OUTPUT"
 
+      - name: Normalize repository name
+        id: repo
+        uses: actions/github-script@v7
+        with:
+          result-encoding: string
+          script: return `${context.repo.owner}/${context.repo.repo}`.toLowerCase()
+
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      sha_short: ${{ steps.version.outputs.sha_short }}
+      sanitized_tag: ${{ steps.sanitize.outputs.sanitized_tag }}
+      repository: ${{ steps.repo.outputs.result }}
+
+  build-and-push:
+    runs-on: ${{ matrix.runner }}
+    needs: prepare-tags-and-names
+    strategy:
+      fail-fast: false
+      matrix:
+        service:
+          - name: frontend
+            image: librislog
+            dockerfile: ./frontend/Dockerfile
+            context: ./frontend
+          - name: backend
+            image: librislog-api
+            dockerfile: ./backend/Dockerfile
+            context: ./backend
+
+        arch: [amd64, arm64]
+
+        include:
+          - arch: amd64
+            runner: ubuntu-latest
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.branch || github.ref }}
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -72,14 +109,14 @@ jobs:
       - name: Generate image tags
         id: tags
         run: |
-          IMAGE="${{ env.REGISTRY }}/${{ github.repository }}/${{ matrix.service.image }}"
-          SHA_SHORT="${{ steps.version.outputs.sha_short }}"
+          IMAGE="${{ env.REGISTRY }}/${{ needs.prepare-tags-and-names.outputs.repository }}/${{ matrix.service.image }}"
+          SHA_SHORT="${{ needs.prepare-tags-and-names.outputs.sha_short }}"
 
           if [ "${{ github.event_name }}" = "release" ]; then
-            SANITIZED="${{ steps.sanitize.outputs.sanitized_tag }}"
-            TAGS="${IMAGE}:${SANITIZED},${IMAGE}:latest"
+            SANITIZED="${{ needs.prepare-tags-and-names.outputs.sanitized_tag }}"
+            TAGS="${IMAGE}:${SANITIZED}-${{ matrix.arch }},${IMAGE}:latest-${{ matrix.arch }}"
           else
-            TAGS="${IMAGE}:develop,${IMAGE}:${SHA_SHORT}"
+            TAGS="${IMAGE}:develop-${{ matrix.arch }},${IMAGE}:${SHA_SHORT}-${{ matrix.arch }}"
           fi
 
           echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"
@@ -90,11 +127,51 @@ jobs:
           context: ${{ matrix.service.context }}
           file: ${{ matrix.service.dockerfile }}
           push: true
-          platforms: linux/amd64
+          platforms: linux/${{ matrix.arch }}
           tags: ${{ steps.tags.outputs.tags }}
           build-args: |
-            APP_VERSION=${{ steps.version.outputs.version }}
+            APP_VERSION=${{ needs.prepare-tags-and-names.outputs.version }}
             GIT_SHA=${{ github.sha }}
             ${{ matrix.service.name == 'frontend' && 'PUBLIC_DEFAULT_LOCALE=en' || '' }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
+
+  create-manifest:
+    needs: [prepare-tags-and-names, build-and-push]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        service:
+          - name: frontend
+            image: librislog
+          - name: backend
+            image: librislog-api
+
+    permissions:
+      packages: write
+
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create multi-arch manifest
+        run: |
+          IMAGE="${{ env.REGISTRY }}/${{ needs.prepare-tags-and-names.outputs.repository }}/${{ matrix.service.image }}"
+          SHA_SHORT="${{ needs.prepare-tags-and-names.outputs.sha_short }}"
+
+          if [ "${{ github.event_name }}" = "release" ]; then
+            SANITIZED="${{ needs.prepare-tags-and-names.outputs.sanitized_tag }}"
+            docker buildx imagetools create -t "${IMAGE}:${SANITIZED}" "${IMAGE}:${SANITIZED}-amd64" "${IMAGE}:${SANITIZED}-arm64"
+            docker buildx imagetools create -t "${IMAGE}:latest" "${IMAGE}:latest-amd64" "${IMAGE}:latest-arm64"
+          else
+            docker buildx imagetools create -t "${IMAGE}:develop" "${IMAGE}:develop-amd64" "${IMAGE}:develop-arm64"
+            docker buildx imagetools create -t "${IMAGE}:${SHA_SHORT}" "${IMAGE}:${SHA_SHORT}-amd64" "${IMAGE}:${SHA_SHORT}-arm64"
+          fi

.github/workflows/docs.yml

@@ -12,6 +12,7 @@ concurrency:
 
 env:
   NODE_VERSION: "22"
+  PYTHON_VERSION: "3.14"
 
 jobs:
   deploy:
@@ -66,6 +67,16 @@ jobs:
             release/docs/package-lock.json
             develop/docs/package-lock.json
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Generate DB layout docs (release)
+        if: steps.check-release-docs.outputs.has_docs == 'true'
+        working-directory: release/docs
+        run: npm run docs:gen-db 2>/dev/null || echo "Skipped — docs:gen-db not in this release"
+
       - name: Build release docs
         if: steps.check-release-docs.outputs.has_docs == 'true'
         working-directory: release/docs
@@ -74,6 +85,10 @@ jobs:
           npx vitepress build
           mv .vitepress/dist /tmp/dist-release
 
+      - name: Generate DB layout docs (nightly)
+        working-directory: develop/docs
+        run: npm run docs:gen-db
+
       - name: Build nightly docs
         working-directory: develop/docs
         run: |

backend/alembic/versions/1a2b3c4d5e6f_add_embed_token_table.py

@@ -0,0 +1,52 @@
+"""add embed_token table for scoped embed tokens
+
+Revision ID: 1a2b3c4d5e6f
+Revises: f7e9d1c3b5a2
+Create Date: 2026-06-13 23:25:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.engine.reflection import Inspector
+
+
+revision: str = "1a2b3c4d5e6f"
+down_revision: Union[str, Sequence[str], None] = "f7e9d1c3b5a2"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    tables = inspector.get_table_names()
+    if "embed_token" not in tables:
+        op.create_table(
+            "embed_token",
+            sa.Column("id", sa.Integer(), nullable=False),
+            sa.Column("user_id", sa.Integer(), nullable=False),
+            sa.Column("name", sa.String(length=255), nullable=False),
+            sa.Column("token_prefix", sa.String(), nullable=False),
+            sa.Column("token_hash", sa.String(), nullable=False),
+            sa.Column("scopes", sa.String(), nullable=False, server_default="embed:stats:read"),
+            sa.Column("allowed_origins", sa.String(), nullable=True),
+            sa.Column("expires_at", sa.DateTime(), nullable=True),
+            sa.Column("last_used_at", sa.DateTime(), nullable=True),
+            sa.Column("created_at", sa.DateTime(), nullable=False),
+            sa.Column("revoked_at", sa.DateTime(), nullable=True),
+            sa.ForeignKeyConstraint(["user_id"], ["user.id"], name="fk_embed_token_user_id"),
+            sa.PrimaryKeyConstraint("id"),
+            sa.UniqueConstraint("token_hash", name="uq_embed_token_token_hash"),
+        )
+        op.create_index(op.f("ix_embed_token_token_prefix"), "embed_token", ["token_prefix"])
+        op.create_index(op.f("ix_embed_token_user_id"), "embed_token", ["user_id"])
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    tables = inspector.get_table_names()
+    if "embed_token" in tables:
+        op.drop_table("embed_token")

backend/app/auth.py

@@ -115,6 +115,31 @@ def get_api_key_prefix(api_key: str) -> str:
     return api_key[:12]
 
 
+# --- Embed token utilities ---
+
+EMBED_TOKEN_PREFIX = "le_"
+EMBED_TOKEN_SCOPE_STATS_READ = "embed:stats:read"
+
+
+def generate_embed_token() -> str:
+    """Generate a new random embed token prefixed with 'le_'."""
+    return f"{EMBED_TOKEN_PREFIX}{secrets.token_urlsafe(32)}"
+
+
+def hash_embed_token(value: str) -> str:
+    """Return a HMAC-SHA256 hex digest of the embed token."""
+    return hmac.new(
+        settings.api_key_encryption_key.encode("utf-8"),
+        value.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def get_embed_token_prefix(token: str) -> str:
+    """Return the first 12 characters of the embed token (visible prefix)."""
+    return token[:12]
+
+
 api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
 
 

backend/app/config.py

@@ -41,6 +41,7 @@ class Settings(BaseSettings):
     cover_import_timeout_seconds: int = 15
     hardcover_app_api_token: str = ""
     thalia_cover_search_enabled: bool = False
+    embed_enabled: bool = True
     forwarded_allow_ips: str = "*"
 
     @field_validator("api_key_encryption_key")

backend/app/i18n/de.json

@@ -0,0 +1,12 @@
+{
+  "embed": {
+    "stats": {
+      "books": "Bücher",
+      "reading": "Lese ich gerade",
+      "read": "Gelesen",
+      "to_read": "Möchte ich lesen",
+      "pages": "Seiten",
+      "avg_pages": "Seiten/Buch"
+    }
+  }
+}

backend/app/i18n/en.json

@@ -0,0 +1,12 @@
+{
+  "embed": {
+    "stats": {
+      "books": "Books",
+      "reading": "Reading",
+      "read": "Read",
+      "to_read": "To Read",
+      "pages": "Pages",
+      "avg_pages": "Avg/Book"
+    }
+  }
+}

backend/app/i18n/es.json

@@ -0,0 +1,12 @@
+{
+  "embed": {
+    "stats": {
+      "books": "Libros",
+      "reading": "Leyendo",
+      "read": "Leído",
+      "to_read": "Quiero leer",
+      "pages": "Páginas",
+      "avg_pages": "Páginas/Libro"
+    }
+  }
+}

backend/app/i18n/fr.json

@@ -0,0 +1,12 @@
+{
+  "embed": {
+    "stats": {
+      "books": "Livres",
+      "reading": "En cours",
+      "read": "Lu",
+      "to_read": "À lire",
+      "pages": "Pages",
+      "avg_pages": "Pages/Livre"
+    }
+  }
+}

backend/app/i18n/zh.json

@@ -0,0 +1,12 @@
+{
+  "embed": {
+    "stats": {
+      "books": "图书",
+      "reading": "正在阅读",
+      "read": "已读",
+      "to_read": "待读",
+      "pages": "页数",
+      "avg_pages": "每本页数"
+    }
+  }
+}

backend/app/main.py

@@ -13,7 +13,7 @@
 from app._build_info import __git_sha__, __version__
 from app.config import settings
 from app.logging_config import configure_logging
-from app.routers import admin, auth, books, cover_candidates, covers, data, docs, health, hygiene, import_, oidc, profile, progress, statistics, users
+from app.routers import admin, auth, books, config, cover_candidates, covers, data, docs, embed, health, hygiene, import_, oidc, profile, progress, statistics, users
 from app.services.cover_storage import cleanup_orphan_covers
 from app.services.data_import import cleanup_temp_files
 
@@ -164,4 +164,7 @@ async def proxy_headers_middleware(request: Request, call_next) -> Response:
 app.include_router(hygiene.router)
 app.include_router(statistics.router)
 app.include_router(data.router)
+app.include_router(config.router)
+if settings.embed_enabled:
+    app.include_router(embed.router)
 app.include_router(admin.router)