From 9d70f17587142bf98a38662c80eb33adca245fba Mon Sep 17 00:00:00 2001
From: Leo Vasanko <git@vasanko.com>
Date: Thu, 3 Sep 2026 16:14:59 +0000
Subject: [PATCH] Pass CLI config to the app as JSON in PAGERITE_CONFIG

---
 docs/frontend-runtime.md |  3 ++-
 pagerite/__main__.py     | 23 +++++++++--------------
 pagerite/app.py          |  5 ++---
 pagerite/config.py       | 28 ++++++++++++++++++++++++++++
 pagerite/state.py        |  8 ++++++--
 pagerite/views.py        |  9 +++++++--
 6 files changed, 54 insertions(+), 22 deletions(-)
 create mode 100644 pagerite/config.py

diff --git a/docs/frontend-runtime.md b/docs/frontend-runtime.md
index 839a0de..c3c011a 100644
--- a/docs/frontend-runtime.md
+++ b/docs/frontend-runtime.md
@@ -26,6 +26,7 @@ Vite builds ES-module `.js` outputs; in dev the backend links them as `<script t
 
 All site data lives under `<hostname>/` in the cwd — `content.kantadb`,
 `analytics.json` and `files/` — where `<hostname>` is the CLI's first
-positional argument (default `localhost`, exported as `PAGERITE_HOSTNAME`;
+positional argument (default `localhost`, passed to the app as JSON in
+`PAGERITE_CONFIG`, see `pagerite/config.py`;
 `PAGERITE_DB`/`PAGERITE_ANALYTICS`/`PAGERITE_FILES` override individual
 paths). gitignored. Do not delete it without asking.
diff --git a/pagerite/__main__.py b/pagerite/__main__.py
index 15d892e..b11d6ed 100644
--- a/pagerite/__main__.py
+++ b/pagerite/__main__.py
@@ -4,8 +4,10 @@ import argparse
 import os
 from pathlib import Path
 
+import msgspec
 from fastapi_vue import server
-from fastapi_vue.hostutil import parse_endpoints
+
+from pagerite.config import Config
 
 DEFAULT_PORT = 8100
 DEVMODE = os.getenv("PAGERITE_DEV") == "1"
@@ -36,19 +38,12 @@ def main() -> None:
         help="Download/update the DB-IP city lite database before starting.",
     )
     args = parser.parse_args()
-    # Export the hostname before pagerite.app is imported: it derives the
-    # data directory and public origin from it at import time.
-    os.environ["PAGERITE_HOSTNAME"] = args.hostname
-    # And the listen port: the app prints the translator WS URL at startup,
-    # which for localhost includes the actual port.
-    for endpoint in parse_endpoints(args.listen, DEFAULT_PORT):
-        if "port" in endpoint:
-            os.environ["PAGERITE_PORT"] = str(endpoint["port"])
-            break
-    # --dbip: the app lifespan downloads/updates the DB-IP database, where
-    # logging is already set up.
-    if args.dbip:
-        os.environ["PAGERITE_DBIP"] = "1"
+    # Hand configuration to the app as JSON in PAGERITE_CONFIG; it must be
+    # set before pagerite.app is imported, as state.py reads it at import
+    # time (data directory, public origin).
+    os.environ["PAGERITE_CONFIG"] = msgspec.json.encode(
+        Config(hostname=args.hostname, dbip=args.dbip)
+    ).decode()
     run_args: dict = {}
     if args.hostname != "localhost":
         # A public site sits behind TLS on its hostname; show that URL in the
diff --git a/pagerite/app.py b/pagerite/app.py
index 36be04d..11e5599 100644
--- a/pagerite/app.py
+++ b/pagerite/app.py
@@ -30,7 +30,6 @@ walking the tree (``resolve``), moves are slot detach/attach
 
 import asyncio
 import logging
-import os
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI, Request
@@ -39,7 +38,7 @@ from fastapi.responses import Response
 from pagerite import api, files, pages, tracking
 from pagerite.__main__ import DEVMODE
 from pagerite.files import file_store
-from pagerite.state import analytics_store, frontend, kanta
+from pagerite.state import analytics_store, config, frontend, kanta
 from collections.abc import AsyncGenerator
 logger = logging.getLogger(__name__)
 
@@ -53,7 +52,7 @@ async def lifespan(_app: FastAPI) -> AsyncGenerator:
         # --dbip: update the DB-IP database first, then decompress/open the
         # MMDB once.  Lookups are then read-only and safe to run in
         # background ``to_thread`` workers.
-        if os.environ.get("PAGERITE_DBIP") == "1":
+        if config.dbip:
             await asyncio.to_thread(tracking._download_dbip)
         await asyncio.to_thread(tracking._geoip._load)
         analytics_store.subscribe(tracking._schedule_analytics_broadcast)
diff --git a/pagerite/config.py b/pagerite/config.py
new file mode 100644
index 0000000..7d77ea2
--- /dev/null
+++ b/pagerite/config.py
@@ -0,0 +1,28 @@
+"""CLI → app configuration, passed as JSON in the ``PAGERITE_CONFIG`` env var.
+
+Kept dependency-free (msgspec only) so ``__main__`` can build and serialize
+the config before any app module is imported, and the app side parses the
+same struct back.  Import-time safe: nothing here reads the environment
+until ``load()`` is called.
+"""
+
+import os
+
+import msgspec
+
+
+class Config(msgspec.Struct):
+    """Configuration passed from the CLI entry point to the app."""
+
+    #: Public hostname of the site; names the per-site data directory
+    #: ``<hostname>/{content.kantadb, analytics.json, files}`` under the cwd.
+    hostname: str = "localhost"
+    #: Download/update the DB-IP city lite database at startup (--dbip).
+    dbip: bool = False
+
+
+def load() -> Config:
+    """Parse ``PAGERITE_CONFIG``, or the defaults when unset."""
+    if raw := os.getenv("PAGERITE_CONFIG"):
+        return msgspec.json.decode(raw.encode(), type=Config)
+    return Config()
diff --git a/pagerite/state.py b/pagerite/state.py
index 21ce3d1..d0d7d28 100644
--- a/pagerite/state.py
+++ b/pagerite/state.py
@@ -29,6 +29,7 @@ from zstandard import ZstdCompressor
 from pagerite import analytics, i18n, seed, translate, views
 from pagerite.__main__ import DEVMODE
 from pagerite.chunks import store_chunks
+from pagerite.config import load
 from pagerite.data import (
     Data,
     Node,
@@ -39,10 +40,13 @@ from pagerite.data import (
 
 logger = logging.getLogger(__name__)
 
+#: The CLI-passed configuration (PAGERITE_CONFIG) for this process.
+config = load()
+
 # Site identity: the hostname comes from the CLI (first positional argument,
-# exported as PAGERITE_HOSTNAME) and names the per-site data directory
+# passed in PAGERITE_CONFIG) and names the per-site data directory
 # ``<hostname>/{content.kantadb, analytics.json, files}`` under the cwd.
-HOSTNAME = os.getenv("PAGERITE_HOSTNAME", "localhost")
+HOSTNAME = config.hostname
 SITE_DIR = Path(HOSTNAME)
 #: Public origin of the site, used for absolute social/canonical/sitemap
 #: URLs. Localhost serves varying ports, so it falls back to the request's
diff --git a/pagerite/views.py b/pagerite/views.py
index 7ae3c1a..4557b89 100644
--- a/pagerite/views.py
+++ b/pagerite/views.py
@@ -25,6 +25,7 @@ from html5tagger import HTML, Document, E, Template
 from platformdirs import site_data_dir, user_data_path
 
 from pagerite import i18n
+from pagerite.config import load as _load_config
 from pagerite.data import Data, Node, node_markdown, prettify, resolve, sorted_nodes
 from pagerite.i18n import Translation
 from pagerite.markdown import render
@@ -45,6 +46,10 @@ def _data_roots() -> list[Path]:
     return [Path(r) for r in roots]
 
 
+#: The CLI-passed configuration (PAGERITE_CONFIG) for this process.
+config = _load_config()
+
+
 def _theme_dirs() -> list[Path]:
     """Theme search roots, most specific first; first match wins per file.
 
@@ -57,7 +62,7 @@ def _theme_dirs() -> list[Path]:
     """
     return [
         Path("themes"),
-        Path(os.getenv("PAGERITE_HOSTNAME", "localhost")) / "themes",
+        Path(config.hostname) / "themes",
         *(root / "themes" for root in _data_roots()),
         Path(__file__).parent / "themes",
     ]
@@ -73,7 +78,7 @@ THEME_DIRS = _theme_dirs()
 # built-in --font-* variables.
 FONT_DIRS = [
     Path("fonts"),
-    Path(os.getenv("PAGERITE_HOSTNAME", "localhost")) / "fonts",
+    Path(config.hostname) / "fonts",
     *(root / "fonts" for root in _data_roots()),
 ]