Operations

Svelte Flow Showcase uses one loopback Node listener and one systemd unit. The companion wiki is a separate static Quartz release. This page documents the checked-in deployment contract; a successful build alone is not evidence that either public host serves it.

Runtime topology

flowchart LR
    Browser["Browser"] --> AppEdge["sflw.loca.zone · nginx"]
    Browser --> WikiEdge["wiki.sflw.loca.zone · nginx"]
    AppEdge --> Node["127.0.0.1:51939 · sflw.service"]
    Node --> Build["build/index.js · timestamped release"]
    WikiEdge --> Wiki["wikis/sflw/current · Quartz release"]

Surface	Contract
Source	/home/loca/dev/sflw
Runtime	/usr/bin/node and npm; not Bun
Unit	sflw.service, system scope, User=loca, Group=loca
Listener	HOST=127.0.0.1, PORT=51939
Public origin	ORIGIN=https://sflw.loca.zone
Entry	/usr/bin/node build/index.js from the app root
Optional environment	EnvironmentFile=-/etc/sflw/sflw.env; absence is valid
Effective request body cap	256 KiB: BODY_SIZE_LIMIT=256K in the unit and the assistant’s streamed input cap; nginx permits 1m
App proxy	http://127.0.0.1:51939, forwarding host, client address, and scheme
Wiki source	/home/loca/dev/wikis/sflw/content and quartz.config.yaml
Wiki nginx root	/home/loca/dev/wikis/sflw/current

No DATA_DIR or ReadWritePaths is configured. The hardened service has read-only home and system views, private temporary storage/devices, no capabilities, and restricted namespaces and address families. Node’s JIT is permitted through MemoryDenyWriteExecute=no. The default assistant needs no provider credentials or external model; see assistant.

Source assets and edge headers

• deploy/sflw.service installs to /etc/systemd/system/sflw.service.
• deploy/sflw.loca.zone.nginx.conf installs to /etc/nginx/sites-available/sflw.loca.zone, linked from sites-enabled.
• The checked-in nginx file is an HTTP bootstrap for both names. It does not refer to certificates that have not yet been issued. Certbot adds TLS and redirects after the initial configuration check and reload.
• The app includes snippets/security-headers-app.conf; the application supplies its own Content-Security-Policy.
• The wiki includes snippets/security-headers.conf and resolves paths with try_files $uri $uri.html $uri/ =404.
• A single certificate name, sflw.loca.zone, covers sflw.loca.zone and wiki.sflw.loca.zone.

Do not replace a working TLS configuration with the HTTP bootstrap during an ordinary application release. Reinstall edge templates only for an intentional infrastructure change.

App releases

From /home/loca/dev/sflw, scripts/deploy.sh performs these ordered operations:

1. Refuse to replace a non-symlink build path.
2. Run npm ci --no-audit --no-fund with /usr/bin first on PATH.
3. Build with BUILD_OUT=build-<UTC timestamp> and npx vite build. The timestamp includes nanoseconds to distinguish successive releases.
4. Require that release’s index.js before publication.
5. Create a temporary symlink and atomically rename it over build; report the previous target.
6. If sflw.service is installed, restart it using the script’s only privileged command, sudo -n systemctl restart sflw, then check its active state without sudo. If the unit is not yet installed, leave the prepared release for first-launch installation.
7. Retain the five newest generated timestamped release directories, always protecting the active target. Never prune build-dev or matching symlinks.

The adapter’s ordinary output is build-dev; setting BUILD_OUT overrides it. The service consumes the build symlink, not local preview output. A failed restart is a failed deployment; the script does not claim an automatic rollback or an HTTP health check.

Canonical gate order

Run final gates only after concurrent source owners have finished. Stop at the first failure and preserve its evidence.

1. npx svelte-check; use npm run check when SvelteKit synchronization is needed.
2. npm test, the project’s focused Vitest gate.
3. BUILD_OUT=build-dev npx vite build for the integrated app build.
4. scripts/deploy.sh for the timestamped service release.
5. For first launch: install the unit and nginx vhost, reload systemd, run nginx -t, reload nginx, issue TLS using Certbot, then enable/start sflw.service. On later releases perform only the applicable approved infrastructure operations.
6. Under umask 022, run /home/loca/dev/wikis/build.sh sflw.
7. Run scripts/e2e.mjs with /usr/bin/node using its supported Chrome CDP invocation against the intended app. Inspect real mouse/keyboard behavior and a rendered screenshot.
8. Check loopback, both public HTTPS hosts, loaded assets, documentation navigation, and rendered recipe anchors.
9. Record exact commands, observed results, app build target, wiki current target, and receipt hashes for the artifacts actually served.

The project slash commands in .omp/commands/gates.md and .omp/commands/publish.md preserve this order. Passing source checks does not replace browser or public-edge verification. Do not call a skipped gate a pass.

Four privileged operation classes

The launch allowlist has exactly four sudo operation classes. The commands below are operator instructions, not evidence they have already run.

1. Install the unit

sudo -n install -m 0644 deploy/sflw.service /etc/systemd/system/sflw.service
sudo -n systemctl daemon-reload

2. Install and reload the nginx site

sudo -n install -m 0644 deploy/sflw.loca.zone.nginx.conf /etc/nginx/sites-available/sflw.loca.zone
sudo -n ln -sfn ../sites-available/sflw.loca.zone /etc/nginx/sites-enabled/sflw.loca.zone
sudo -n nginx -t
sudo -n systemctl reload nginx

Do not reload if the configuration check fails.

3. Issue TLS for these two hosts

sudo -n certbot --nginx --non-interactive --agree-tos --redirect \
  -m admin@loca.zone --cert-name sflw.loca.zone \
  -d sflw.loca.zone -d wiki.sflw.loca.zone

4. Enable or restart the app

First launch:

sudo -n systemctl enable --now sflw.service

Later application deployments use the restart already contained in scripts/deploy.sh. Do not use sudo for npm, app builds, wiki publication, status checks, or unrelated services. Optional provider configuration is not part of the default credential-free launch.

Wiki publication

The configuration is adapted from the chat wiki, with pageTitle: Svelte Flow Showcase, baseUrl: wiki.sflw.loca.zone, and fontOrigin: googleFonts. The app and wiki have independent dependency/build paths; app CSS changes do not modify Quartz.

umask 022
/home/loca/dev/wikis/build.sh sflw

The shared publisher builds into a temporary output, checks for index.html, moves it to a dist-* release, and atomically updates current. It preserves the active target and five inactive releases. A check-only build is available as /home/loca/dev/wikis/build.sh sflw --check-only, but is not a publication receipt. Do not edit generated releases, caches, or the shared Quartz engine to make a per-wiki content change.

Before publishing, check sibling wikilinks, Markdown fence balance, and recipe headings against assistant KB identifiers. After publishing, confirm actual page identity and rendered content. A request for /recipes#add-node sends only /recipes to the server: the add-node anchor must exist in the rendered DOM. HTTP 200 alone does not prove that anchor, a diagram, or a stylesheet loaded.

Rollback and observation

For an app rollback, first select a retained release with its index.js present. Assign that directory name to previous, then run from the app root:

test -n "${previous:-}" && test -f "$previous/index.js" &&
  ln -s "$previous" build.rollback &&
  mv -T build.rollback build &&
  sudo -n systemctl restart sflw
systemctl is-active --quiet sflw

The temporary link command deliberately refuses to overwrite an existing build.rollback. Check its provenance rather than deleting an unexpected path. A source revert is separate from selecting a retained release.

For a wiki rollback, choose a retained dist-* directory containing index.html, create a fresh temporary link to it within /home/loca/dev/wikis/sflw, and atomically rename that link over current. Do not use sudo. Recheck the public content and record the selected target.

Useful unprivileged observations:

systemctl status sflw --no-pager
systemctl is-active sflw
readlink build
readlink /home/loca/dev/wikis/sflw/current
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:51939/
curl -fsS -o /dev/null -w '%{http_code}\n' https://sflw.loca.zone/
curl -fsS -o /dev/null -w '%{http_code}\n' https://wiki.sflw.loca.zone/

A release receipt must distinguish source files, generated artifacts, and live-response evidence. Record the observed target before hashing; a later publication can legitimately change build or current.

Related

• assistant for local-first behavior and proposal boundaries.
• recipes for canonical assistant links.
• index for the documentation map.