feat: add one-command Traefik deployment

.env.example

@@ -0,0 +1,8 @@
+# Optional overrides for compose.yaml. Its defaults already match production.
+TOOLBOX_HOST=toolbax.add-ideas.de
+TRAEFIK_NETWORK=internal
+TRAEFIK_CERT_RESOLVER=netcup
+
+# Keep these two values paired when deploying a newer published toolbox release.
+TOOLBOX_RELEASE_VERSION=0.2.0
+TOOLBOX_RELEASE_SHA256=60b37de7f26ae430737cb014a86e8b9b15e9eafe0a6883d6a28d06d9611ee237

.gitignore

@@ -5,4 +5,5 @@ artifacts/
 coverage/
 public/THIRD_PARTY_LICENSES.txt
 *.log
+.env
 .DS_Store

.prettierrc.json

@@ -2,5 +2,13 @@
   "singleQuote": true,
   "semi": true,
   "trailingComma": "es5",
-  "printWidth": 80
+  "printWidth": 80,
+  "overrides": [
+    {
+      "files": "compose.yaml",
+      "options": {
+        "singleQuote": false
+      }
+    }
+  ]
 }

Containerfile.release

@@ -0,0 +1,34 @@
+ARG NGINX_IMAGE=nginxinc/nginx-unprivileged:1.31.3-alpine@sha256:18d67281256ded39ff65e010ae4f831be18f19356f83c60bc546492c7eb6dd23
+
+FROM ${NGINX_IMAGE} AS release
+
+ARG TOOLBOX_RELEASE_VERSION=0.2.0
+ARG TOOLBOX_RELEASE_SHA256=60b37de7f26ae430737cb014a86e8b9b15e9eafe0a6883d6a28d06d9611ee237
+ARG TOOLBOX_RELEASE_BASE_URL=https://git.add-ideas.de/zemion/toolbox-portal/releases/download
+
+RUN set -eu; \
+    archive="add-ideas-toolbox-${TOOLBOX_RELEASE_VERSION}.zip"; \
+    curl --fail --location --silent --show-error --proto '=https' \
+      --proto-redir '=https' --tlsv1.2 \
+      --output "/tmp/${archive}" \
+      "${TOOLBOX_RELEASE_BASE_URL}/v${TOOLBOX_RELEASE_VERSION}/${archive}"; \
+    echo "${TOOLBOX_RELEASE_SHA256}  /tmp/${archive}" | sha256sum -c -; \
+    mkdir -p /tmp/toolbox; \
+    unzip -q "/tmp/${archive}" -d /tmp/toolbox; \
+    test -f /tmp/toolbox/index.html; \
+    test -f /tmp/toolbox/toolbox.catalog.json; \
+    test -f /tmp/toolbox/toolbox.release.json; \
+    test -f /tmp/toolbox/apps/pdf/toolbox-app.json; \
+    test -f /tmp/toolbox/apps/xslt/toolbox-app.json; \
+    test -f /tmp/toolbox/apps/onenote/toolbox-app.json; \
+    rm "/tmp/${archive}"
+
+FROM ${NGINX_IMAGE}
+
+COPY --chown=101:101 deploy/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=release --chown=101:101 /tmp/toolbox/ /usr/share/nginx/html/
+
+USER 101:101
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --quiet --spider http://127.0.0.1:8080/toolbox.catalog.json || exit 1

README.md

@@ -63,6 +63,43 @@ transmit preferences. Because Toolbox apps share an origin, code explicitly
 trusted in an app can access same-origin browser storage; review each app's
 privacy and executable-code warning. Light, dark, and system modes are supported.
 
+## Production deployment behind Traefik
+
+The committed `compose.yaml` is the shortest production path. Its release
+container downloads the immutable Toolbox 0.2.0 ZIP during the image build,
+verifies SHA-256 before extracting it, and then copies only the verified static
+files into the pinned unprivileged nginx image. Node.js and a local portal
+assembly are not required on the deployment host.
+
+Prerequisites:
+
+- Docker with the Compose plugin;
+- Traefik attached to the existing external Docker network `internal`;
+- a Traefik HTTPS entrypoint named `websecure`;
+- a certificate resolver named `netcup`;
+- DNS for `toolbax.add-ideas.de` pointing to that Traefik instance; and
+- outbound HTTPS access to `git.add-ideas.de` while the image is built.
+
+Deploy a fresh clone with:
+
+```sh
+git clone https://git.add-ideas.de/zemion/toolbox-portal.git
+cd toolbox-portal
+docker compose up -d --build
+docker compose ps
+```
+
+No host port is published. Traefik routes
+`https://toolbax.add-ideas.de` to nginx on the shared network at port 8080 and
+obtains its TLS certificate through `netcup`. The hostname, network, resolver,
+release version, and matching checksum can be overridden through environment
+variables; copy `.env.example` to `.env` only when an override is needed. For
+example, set `TOOLBOX_HOST=toolbox.add-ideas.de` if that spelling is preferred.
+
+The external network is deliberately not created by this project. Creating a
+private project-local network would prevent an independently managed Traefik
+container from reaching the service.
+
 ## Exact release assembly
 
 Every app release ZIP must put these items at its archive root:
@@ -150,7 +187,7 @@ npm run package:static -- \
 
 This also emits a `.sha256` sidecar.
 
-## Container image
+## Local assembled container and publication
 
 `Containerfile` serves only the assembled files with unprivileged nginx on port 8080. It adds restrictive browser headers, same-origin isolation, immutable
 caching only for Vite-hashed assets, and revalidation for all other files.
@@ -167,8 +204,11 @@ podman run --rm -p 8080:8080 \
   git.add-ideas.de/zemion/toolbox:0.2.0
 ```
 
-For a local deployment, copy `compose.example.yaml` to `compose.yaml` and run
-`docker compose up --build -d` (or the Podman Compose equivalent).
+For a direct-port local deployment after assembly, use the separate example:
+
+```sh
+docker compose -f compose.example.yaml up -d --build
+```
 
 Publish both common architectures from a buildx-enabled workstation or Gitea
 runner:
@@ -177,7 +217,7 @@ runner:
 docker login git.add-ideas.de
 docker buildx build \
   --platform linux/amd64,linux/arm64 \
-  --file Containerfile \
+  --file Containerfile.release \
   --tag git.add-ideas.de/zemion/toolbox:0.2.0 \
   --tag git.add-ideas.de/zemion/toolbox:0.2 \
   --push .

compose.yaml

@@ -0,0 +1,37 @@
+name: addideas-toolbox
+
+services:
+  toolbox:
+    build:
+      context: .
+      dockerfile: Containerfile.release
+      args:
+        TOOLBOX_RELEASE_VERSION: "${TOOLBOX_RELEASE_VERSION:-0.2.0}"
+        TOOLBOX_RELEASE_SHA256: "${TOOLBOX_RELEASE_SHA256:-60b37de7f26ae430737cb014a86e8b9b15e9eafe0a6883d6a28d06d9611ee237}"
+    image: "git.add-ideas.de/zemion/toolbox:${TOOLBOX_RELEASE_VERSION:-0.2.0}"
+    restart: unless-stopped
+    read_only: true
+    tmpfs:
+      - /tmp:size=16m,mode=1777
+      - /var/cache/nginx:size=16m,uid=101,gid=101
+      - /var/run:size=1m,uid=101,gid=101
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    networks:
+      - internal
+    labels:
+      traefik.enable: "true"
+      traefik.docker.network: "${TRAEFIK_NETWORK:-internal}"
+      traefik.http.routers.addideas-toolbox.rule: "Host(`${TOOLBOX_HOST:-toolbax.add-ideas.de}`)"
+      traefik.http.routers.addideas-toolbox.entrypoints: websecure
+      traefik.http.routers.addideas-toolbox.tls: "true"
+      traefik.http.routers.addideas-toolbox.tls.certresolver: "${TRAEFIK_CERT_RESOLVER:-netcup}"
+      traefik.http.routers.addideas-toolbox.service: addideas-toolbox
+      traefik.http.services.addideas-toolbox.loadbalancer.server.port: "8080"
+
+networks:
+  internal:
+    external: true
+    name: "${TRAEFIK_NETWORK:-internal}"

scripts/deployment.test.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const projectRoot = process.cwd();
+const compose = readFileSync(path.join(projectRoot, 'compose.yaml'), 'utf8');
+const containerfile = readFileSync(
+  path.join(projectRoot, 'Containerfile.release'),
+  'utf8'
+);
+const releaseLock = JSON.parse(
+  readFileSync(path.join(projectRoot, 'release', 'toolbox.lock.json'), 'utf8')
+) as { releaseVersion: string };
+
+describe('production deployment', () => {
+  it('keeps the release version and checksum pins synchronized', () => {
+    const containerVersion = containerfile.match(
+      /^ARG TOOLBOX_RELEASE_VERSION=(\S+)$/mu
+    )?.[1];
+    const composeVersion = compose.match(
+      /\$\{TOOLBOX_RELEASE_VERSION:-([^}]+)\}/u
+    )?.[1];
+    const containerChecksum = containerfile.match(
+      /^ARG TOOLBOX_RELEASE_SHA256=([a-f0-9]{64})$/mu
+    )?.[1];
+    const composeChecksum = compose.match(
+      /\$\{TOOLBOX_RELEASE_SHA256:-([a-f0-9]{64})\}/u
+    )?.[1];
+
+    expect(containerVersion).toBe(releaseLock.releaseVersion);
+    expect(composeVersion).toBe(containerVersion);
+    expect(composeChecksum).toBe(containerChecksum);
+  });
+
+  it('verifies the release before extraction and retains a rootless final image', () => {
+    expect(containerfile).toContain("--proto-redir '=https' --tlsv1.2");
+    expect(containerfile.indexOf('sha256sum -c -')).toBeGreaterThan(0);
+    expect(containerfile.indexOf('unzip -q')).toBeGreaterThan(
+      containerfile.indexOf('sha256sum -c -')
+    );
+    expect(containerfile).toContain(
+      'COPY --from=release --chown=101:101 /tmp/toolbox/'
+    );
+    expect(containerfile).toMatch(/\nUSER 101:101\nEXPOSE 8080\n/u);
+  });
+
+  it('uses only the requested external Traefik network and HTTPS router', () => {
+    expect(compose).toContain('dockerfile: Containerfile.release');
+    expect(compose).toContain('traefik.enable: "true"');
+    expect(compose).toContain(
+      'traefik.docker.network: "${TRAEFIK_NETWORK:-internal}"'
+    );
+    expect(compose).toContain(
+      'traefik.http.routers.addideas-toolbox.rule: "Host(`${TOOLBOX_HOST:-toolbax.add-ideas.de}`)"'
+    );
+    expect(compose).toContain(
+      'traefik.http.routers.addideas-toolbox.entrypoints: websecure'
+    );
+    expect(compose).toContain(
+      'traefik.http.routers.addideas-toolbox.tls.certresolver: "${TRAEFIK_CERT_RESOLVER:-netcup}"'
+    );
+    expect(compose).toContain('external: true');
+    expect(compose).not.toMatch(/^\s+ports:/mu);
+  });
+});