develop

.env.example

@@ -1,11 +1,11 @@
 # Backend settings
 DATABASE_URL=sqlite:///./data/librislog.db
-GOOGLE_BOOKS_API_KEY=        # REQUIRED for Google Books fallback — without this key Google's API returns 503.
-                             # Create one at https://console.cloud.google.com → APIs & Services → Credentials.
+GOOGLE_BOOKS_API_KEY=        # optional — see https://codebude.github.io/librislog/guide/api-keys
 CORS_ORIGINS=["http://localhost", "http://localhost:5173"]
 LOG_LEVEL=INFO               # DEBUG | INFO | WARNING | ERROR | CRITICAL
 COVERS_DIR=./data/covers     # Directory where downloaded cover images are stored locally.
-API_KEY_ENCRYPTION_KEY=CHANGE_ME_TO_32PLUS_CHARS
+# Generate a real secret:  openssl rand -base64 32
+API_KEY_ENCRYPTION_KEY=CHANGE_ME_TO_32PLUS_CHARS  # <-- YOU MUST CHANGE THIS
 AUTH_COOKIE_NAME=librislog_session
 AUTH_COOKIE_SECURE=false        # set true in production (HTTPS)
 AUTH_COOKIE_SAMESITE=lax        # lax | strict | none

.github/workflows/docker.yml

@@ -0,0 +1,100 @@
+name: Docker Build & Publish
+
+on:
+  push:
+    branches: [develop]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch to build from"
+        required: false
+        default: develop
+
+env:
+  REGISTRY: ghcr.io
+
+jobs:
+  build-and-push:
+    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
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.branch || github.ref }}
+
+      - name: Derive version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            VERSION="${{ github.event.release.tag_name }}"
+          else
+            VERSION="$(git describe --tags --always 2>/dev/null || echo 'v0.0.0-dev')"
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "sha_short=$(echo '${{ github.sha }}' | cut -c1-7)" >> "$GITHUB_OUTPUT"
+
+      - name: Sanitize version for Docker tag
+        id: sanitize
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          SANITIZED="$(echo "$VERSION" | sed 's/[^a-zA-Z0-9_.-]/-/g')"
+          SANITIZED="$(echo "$SANITIZED" | sed 's/^[^a-zA-Z0-9_]\+//')"
+          echo "sanitized_tag=${SANITIZED:0:128}" >> "$GITHUB_OUTPUT"
+
+      - 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: Generate image tags
+        id: tags
+        run: |
+          IMAGE="${{ env.REGISTRY }}/${{ github.repository }}/${{ matrix.service.image }}"
+          SHA_SHORT="${{ steps.version.outputs.sha_short }}"
+
+          if [ "${{ github.event_name }}" = "release" ]; then
+            SANITIZED="${{ steps.sanitize.outputs.sanitized_tag }}"
+            TAGS="${IMAGE}:${SANITIZED},${IMAGE}:latest"
+          else
+            TAGS="${IMAGE}:develop,${IMAGE}:${SHA_SHORT}"
+          fi
+
+          echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: ${{ matrix.service.context }}
+          file: ${{ matrix.service.dockerfile }}
+          push: true
+          platforms: linux/amd64
+          tags: ${{ steps.tags.outputs.tags }}
+          build-args: |
+            APP_VERSION=${{ steps.version.outputs.version }}
+            GIT_SHA=${{ github.sha }}
+            ${{ matrix.service.name == 'frontend' && 'PUBLIC_DEFAULT_LOCALE=en' || '' }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docs.yml

@@ -0,0 +1,109 @@
+name: Docs
+
+on:
+  push:
+    branches: [develop]
+  release:
+    types: [published]
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: "22"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          path: release
+
+      - uses: actions/checkout@v6
+        with:
+          ref: develop
+          path: develop
+
+      - name: Determine release ref
+        id: release-ref
+        working-directory: release
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            REF="${{ github.event.release.tag_name }}"
+          else
+            DEFAULT_BRANCH=$(git remote show origin | sed -n '/HEAD branch/s/.*: //p')
+            REF=$(git tag --list 'v*' --sort=-version:refname | head -1)
+            REF="${REF:-$DEFAULT_BRANCH}"
+          fi
+          echo "ref=${REF}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout release ref
+        working-directory: release
+        run: git checkout "${{ steps.release-ref.outputs.ref }}"
+
+      - name: Check if release ref has docs
+        id: check-release-docs
+        working-directory: release
+        run: |
+          if [ -f docs/package.json ] && [ -f docs/.vitepress/config.ts ]; then
+            echo "has_docs=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_docs=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: |
+            release/docs/package-lock.json
+            develop/docs/package-lock.json
+
+      - name: Build release docs
+        if: steps.check-release-docs.outputs.has_docs == 'true'
+        working-directory: release/docs
+        run: |
+          npm ci
+          npx vitepress build
+          mv .vitepress/dist /tmp/dist-release
+
+      - name: Build nightly docs
+        working-directory: develop/docs
+        run: |
+          npm ci
+          cp .vitepress/config.ts .vitepress/config.original.ts
+          cp .vitepress/config.nightly.ts .vitepress/config.ts
+          npx vitepress build
+          mv .vitepress/dist /tmp/dist-nightly
+
+      - name: Prepare full deploy (release + nightly)
+        if: steps.check-release-docs.outputs.has_docs == 'true'
+        run: |
+          mv /tmp/dist-release ./dist
+          mkdir -p ./dist/next
+          cp -a /tmp/dist-nightly/. ./dist/next/
+
+      - name: Prepare nightly-only deploy
+        if: steps.check-release-docs.outputs.has_docs != 'true'
+        run: cp -a /tmp/dist-nightly/. ./dist/
+
+      - uses: peaceiris/actions-gh-pages@v4
+        if: steps.check-release-docs.outputs.has_docs == 'true'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist
+          keep_files: false
+
+      - uses: peaceiris/actions-gh-pages@v4
+        if: steps.check-release-docs.outputs.has_docs != 'true'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist
+          destination_dir: next
+          keep_files: false