# Site Operations

Operational guide for managing an htmx-ssr consumer site (L3 instance).
All recipes run from the **site root** — the directory that contains `site/`.

## Runtime boundary

The htmx-ssr binary separates what is compiled-in from what is read at runtime.
This determines whether a change requires a restart, a rebuild, or nothing.

| What you change                          | Binary effect | Action needed                         |
|------------------------------------------|---------------|---------------------------------------|
| Markdown content, NCL metadata           | None          | `just content` — no restart           |
| JSON content indexes (`site/r/`)         | None          | Already written by `just content`     |
| Knowledge graph (`content_graph.json`)   | None          | `just graph` — no restart             |
| Static assets (CSS, images)              | None          | Copy to `site/public/` — no restart   |
| Jinja templates (`.j2`)                  | None          | `just templates` + server restart     |
| FTL strings (`site/i18n/locales/`)       | None          | Server restart only                   |
| RBAC (`site/rbac.ncl`)                   | None          | **Automatic hot-reload** — nothing    |
| Routes or menus (`site/config/routes.ncl`) | **Baked**   | Binary rebuild (see §Routes & menus)  |
| New language (routes.ncl + site.ncl)     | **Baked**     | Binary rebuild (see §New language)    |

---

## 1. Update content — preview locally

Content = markdown posts, NCL metadata, and project/blog/recipe pages.

```sh
# Edit markdown files:
#   site/content/{type}/{lang}/{category}/{slug}/index.md
#   site/content/{type}/{lang}/{category}/{slug}/index.ncl  (metadata)

# Regenerate JSON indexes:
just content                        # all types, all langs
just content type=blog              # single type
just content type=blog lang=en      # single type + lang
just content type=blog lang=en category=rust  # single category (uses --category)

# Watch mode (auto-regenerate on save):
just content-watch
just content-watch type=blog lang=en

# Start server and open browser:
just dev                            # http://localhost:3030
```

Changes in `site/content/` are served directly — no server restart.
The JSON indexes in `site/r/` are what the server reads; always run `just content` after editing NCL metadata or adding new files.

---

## 2. Update content including the knowledge graph

The knowledge graph connects posts to ontology nodes and to each other.
Requires `ONTOREF_NICKEL_IMPORT_PATH` and `CONTENT_GRAPH_IMPL_ONTOLOGY` in `.env`.

```sh
just content                        # rebuild JSON indexes first
just graph                          # rebuild content_graph.json
just dev                            # preview
```

The graph is pre-built: `gen-content-graph --site .` writes `site/r/content_graph.json`.
The server reads it as a static file — no restart after regeneration.

---

## 3. Publish content to production (no binary rebuild)

Content changes do not need a new container image. Update the PV directly.

**Kubernetes / docker-compose (PVC):**
```sh
# Sync the JSON indexes to the running pod's PVC:
kubectl cp site/r/ <pod-name>:/var/www/site/r/

# Sync source content (if the server reads markdown directly):
kubectl cp site/content/ <pod-name>:/var/www/site/content/

# No rollout restart needed — server reads these on next request.
```

**Full PV resync (after template or FTL changes too):**
```sh
kubectl cp site/ <pod-name>:/var/www/site/
kubectl rollout restart deployment/<deployment-name>
```

**New container image (when binary was rebuilt):**
Run `just build-push-remote` from `website-htmx-rustelo/code/`.
This builds a new image via lian-build and pushes it to the registry.
Deployment manifests reference the new tag.

---

## 4. Update templates — preview locally and publish

Templates are Jinja2 (`.j2`) files loaded at server startup from `HTMX_TEMPLATE_PATH`.

```sh
# Edit source templates in the L2 project:
#   website-htmx-rustelo/code/crates/pages_htmx/templates/pages/{slug}.j2
#   website-htmx-rustelo/code/crates/pages_htmx/templates/partials/{name}.j2

# Reassemble htmx-templates in the consumer site:
just templates                      # copies framework + project templates to htmx-templates/

# Restart server (templates loaded at startup):
just dev                            # kills old server, starts fresh

# Publish: sync htmx-templates to PV + rollout restart
kubectl cp htmx-templates/ <pod-name>:/var/www/htmx-templates/
kubectl rollout restart deployment/<deployment-name>
```

`just templates` runs `assemble-htmx-templates.nu` — it overlays framework defaults
with the L2 project's templates. Project templates always win over framework defaults.

If `just local-install` was run (binary rebuild), the installed share templates at
`~/.local/share/rustelo-htmx-server/htmx-templates/` are also updated. The site's
`htmx-templates/` directory takes precedence over the installed share.

---

## 5. Change menus or routes

Routes and menus are **compiled into the binary** from `site/config/routes.ncl` at
build time. Changing them requires rebuilding the binary.

```sh
# 1. Edit in the consumer site (jpl/site, etc.):
#    site/site/config/routes.ncl   — add/change URL paths and menu entries
#    site/site/config/site.ncl     — confirm language list is current

# 2. Copy to the L2 source project (website-htmx-rustelo/code):
#    cp site/site/config/routes.ncl website-htmx-rustelo/code/site/config/routes.ncl

# 3. Rebuild the binary from website-htmx-rustelo/code:
cd /path/to/website-htmx-rustelo/code
just local-install                  # builds release binary + installs wrapper

# 4. Restart the consumer site server:
cd /path/to/jpl/site
just dev
```

`just local-install` takes ~2 min on first build, incremental afterward (sccache).
The new binary at `~/.local/libexec/rustelo-htmx-server` is picked up immediately
on next `just dev` — no path changes needed.

**Route component name convention:**
```
URL: /my-tool    → Component: "MyToolPage"
URL: /lian-build → Component: "LianBuildPage"
```

---

## 6. Update FTL strings (i18n text)

FTL files are loaded at **server startup** from `site/i18n/locales/{lang}/`.
No rebuild needed; restart applies the changes.

```sh
# Edit FTL files:
#   site/i18n/locales/en/pages/{slug}.ftl
#   site/i18n/locales/es/pages/{slug}.ftl
#   site/i18n/locales/en/common.ftl    (shared UI strings)

# Apply changes (restart server):
just dev                            # kills existing server, starts with fresh FTL

# Publish: sync i18n to PV + rollout restart
kubectl cp site/i18n/ <pod-name>:/var/www/site/i18n/
kubectl rollout restart deployment/<deployment-name>
```

FTL is fail-open: missing keys render as empty string, never crash.
Both languages (`en` and `es`) must be kept in sync — add every key to both.

---

## 7. Add a new language

Adding a language requires both FTL files (runtime) and route paths (compile-time).

```sh
# Step 1 — Create FTL translations (runtime, no rebuild):
mkdir -p site/i18n/locales/{lang}/pages
cp site/i18n/locales/en/*.ftl site/i18n/locales/{lang}/
# Translate all strings in the copied files

# Step 2 — Register the language (requires rebuild):
# In site/config/site.ncl — add to the languages list
# In site/config/routes.ncl — add "{lang} = /{path}" to every route

# Step 3 — Rebuild binary:
cd /path/to/website-htmx-rustelo/code
just local-install

# Step 4 — Restart:
cd /path/to/consumer-site
just dev
```

If the new language shares URL paths with English (e.g., language detection via
`Accept-Language` header only), steps 2 and 3 may be skipped — only FTL is needed.
Verify with `just htmx-smoke` after starting the server.

---

## 8. Change RBAC permissions

RBAC is hot-reloaded automatically. The server watches `site/rbac.ncl` for changes
and applies them without restart.

```sh
# Edit:
#   site/rbac.ncl   — roles, groups, protected paths, anonymous deny paths

# No action needed — the running server picks up changes within ~1s.
# Confirm in server logs: "rbac hot-reload: N groups, M overrides"
```

If the server is not running, changes take effect on next `just dev`.

**For deployment**: sync `site/rbac.ncl` to the PVC — no rollout restart needed.
```sh
kubectl cp site/rbac.ncl <pod-name>:/var/www/site/rbac.ncl
```

---

## Quick reference

```sh
just dev                            # start local server
just content [type] [lang]          # regenerate content indexes
just content-watch [type] [lang]    # watch + auto-regenerate
just graph                          # rebuild content_graph.json
just templates                      # rebuild htmx-templates from source
just sync                           # templates + content (no graph)
just sync-full                      # templates + content + graph
```

**When to rebuild the binary** (`just local-install` in `website-htmx-rustelo/code`):
- Routes or menu structure changed
- New language with distinct URL paths
- New page component type added