Documentation menu

Maintaining Flog

flog.run website

The Primate application in web/ is the source for the flog website. The repository root declares it as a flog workspace, and flog.lock is the only JavaScript dependency lockfile.

Local verification#

Use the stable installed flog on your PATH. From the repository root, install the dependencies pinned by flog.lock (if not already installed), then build and check the website:

flog install
flog run --cwd web build
flog run --cwd web check

The production image is different: web/Containerfile builds Flog from the checked-out commit, then uses that executable and the committed flog.lock to install, build, and check the website in a clean context. It does not use another JavaScript package manager. Build the image from the repository root:

podman build -f web/Containerfile -t flog-web .

The /install route reads scripts/install directly. Its smoke test compares the response body byte-for-byte with that canonical file and also checks /, an unknown route, status codes, and response content types.

Documentation pages#

The /docs section renders the repository's Markdown files through Primate's Markdown view module. web/server/docs.js defines the stable route, navigation label, and short description for each canonical file; it does not contain a second copy of the documentation prose. The build runs web/scripts/sync-docs.js to copy the reviewed root files into the generated view input directory before Primate compiles them into the server artifact. Add or remove an experimental command in the root experimental-commands.json; the same build validates that list and generates command-page status for the website without changing the CLI. Subcommands inherit their parent's status. Add or rename a public page by updating the catalog and the canonical Markdown file together. Command pages live in docs/commands/; the sync step copies Markdown recursively. Getting started, Guides, Commands, Reference, and Maintaining Flog are the public navigation groups. Native HTML disclosures keep lookup sections compact: only the section containing the current page is initially expanded. This also applies to Getting started, which opens on the documentation landing page and its introductory guides, but stays collapsed on other sections' pages.

Home, documentation, and not-found pages use adjacent Marko route views and shared site components. Navigation is ordinary server-rendered HTML; the desktop sidebar and narrow-screen disclosure menu require no client-side JavaScript. The optional, same-origin web/static/theme.js script enables an icon button that cycles System → Light → Dark and remembers explicit choices in local storage. Monitor, sun, and moon icons are imported directly from Lucide's individual icon modules in web/server/theme-icons.js and rendered as inline SVG on the server: no Lucide browser bundle or icon font is loaded. The button's tooltip and accessible name identify both the current mode and the next choice. It loads in the head to apply a saved preference before first paint. CSS follows the system colour scheme even without JavaScript; blocked storage does not prevent switching themes for the current page. No inline script is required. Site styling is emitted from web/client/master.css, and page metadata is inserted through Primate's server-side page response. The production image also copies /docs beside the compiled application so the canonical reviewed sources remain available in the runner.

Repopack App#

web/repopack-app.json is the versioned App blueprint. The production runner listens on port 6161 and needs no secrets or persistent volumes. The Repopack App uses the reserved platform origin https://flog.repopack.app.

Deploy only a pushed commit SHA, and expose flog.run only from reviewed master. Configure automatic deployments from master so a task-branch deployment at the platform origin is replaced after merge rather than becoming a second release path.

flog.run DNS and TLS#

Changing public DNS is a separate operator action and is not performed by the repository build or deployment:

  1. Verify /, /install, and installer byte equality at https://flog.repopack.app.
  2. Add flog.run as a custom domain in the hosting control plane and record the exact DNS target and ownership records it provides.
  3. Add those records at the authoritative DNS provider. Do not proxy or cache /install while domain validation is pending.
  4. Wait for the hosting control plane to report a valid certificate for flog.run, then verify HTTPS and redirect any HTTP request to HTTPS.
  5. Compare curl -fsSL https://flog.run/install with scripts/install before publishing the domain as the canonical installation endpoint.

Keep the platform origin available for rollback and health checks. TLS private keys belong to the hosting platform and must not be committed to this repository.