diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..5a69356 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 158ac61..decb68d 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ artifacts/ coverage/ public/THIRD_PARTY_LICENSES.txt *.log +.env .DS_Store diff --git a/.prettierrc.json b/.prettierrc.json index 94e30b6..e1577e1 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -2,5 +2,13 @@ "singleQuote": true, "semi": true, "trailingComma": "es5", - "printWidth": 80 + "printWidth": 80, + "overrides": [ + { + "files": "compose.yaml", + "options": { + "singleQuote": false + } + } + ] } diff --git a/Containerfile.release b/Containerfile.release new file mode 100644 index 0000000..3381a40 --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 4da0836..dc8c225 100644 --- a/README.md +++ b/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 . diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..fb56fdb --- /dev/null +++ b/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}" diff --git a/scripts/deployment.test.ts b/scripts/deployment.test.ts new file mode 100644 index 0000000..41b34a5 --- /dev/null +++ b/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); + }); +});