Document deployment and stop tracking generated output

1 files changed, 70 insertions, 0 deletions

diff --git a/_docs/OPERATIONS.md b/_docs/OPERATIONS.md
new file mode 100644
index 0000000..a4a6d13
--- /dev/null
+++ b/_docs/OPERATIONS.md
@@ -0,0 +1,70 @@
+# Weft operations
+
+## Caddy source protection
+
+Before enabling public notes, place these matchers before `file_server` in the
+site block and reload Caddy:
+
+```caddyfile
+@underscore path_regexp underscore (^|/)_[^/]*
+respond @underscore 404
+
+@templates path *.tmpl
+respond @templates 404
+```
+
+The first matcher denies any URL with an underscore-prefixed path component,
+including an entire `_private/` subtree. The second denies template sources.
+Markdown is intentionally not denied and may remain downloadable. Validate the
+active configuration with `caddy validate --config /etc/caddy/Caddyfile` before
+`systemctl reload caddy`.
+
+## Syncthing
+
+Each device keeps this device-local, non-synchronized `.stignore` at the vault
+root:
+
+```text
+#include .stignore.shared
+```
+
+The synchronized `.stignore.shared` contains:
+
+```text
+*.html
+```
+
+The local include lets every device load one shared rule without trying to
+synchronize `.stignore` itself. The shared rule excludes generated HTML at
+every depth in both directions while leaving Markdown synchronized.
+
+## Scheduled build
+
+Install the Weft binary at `/usr/local/bin/weft`, then use a cron entry like:
+
+```cron
+17 * * * * sleep 60 && flock -n /run/lock/weft.lock /usr/local/bin/weft /srv/tjp.lol >>/var/log/weft.log 2>&1 || logger -t weft 'build failed or lock unavailable'
+```
+
+The 60-second delay gives Syncthing time to settle, `flock -n` prevents
+overlapping builds, build output goes to `/var/log/weft.log`, and failure is
+also recorded in the system log under the `weft` tag. Adjust the delay only
+after observing the server's real sync latency. These paths assume a root
+crontab; for an unprivileged account, use lock and log paths it can write.
+
+## Rollout
+
+- [ ] Install Weft and run one manual build on the server.
+- [ ] Add and validate the Caddy matchers above before serving the source tree.
+- [ ] Put the local `.stignore` on every Syncthing device and synchronize
+  `.stignore.shared`.
+- [ ] Connect only the deliberately selected public vault content.
+- [ ] Verify generated note pages, internal links, and underscore privacy on the
+  deployed host.
+- [ ] Install the locked, delayed cron build and confirm a forced failure is
+  logged.
+- [ ] Restore Notes navigation and homepage links only after real public notes
+  are present and verified.
+
+Notes remains hidden: no real selected vault content exists in this repository,
+so vault connection and server activation are intentionally pending.