services/Distributed-Wiki-New.md
... ...
@@ -0,0 +1,169 @@
1
+# The New Distributed Wiki
2
+
3
+> This document replaces the legacy Gollum/ExaBGP setup notes. It explains how to deploy the Go-based wiki mirror while keeping the original structure for easy comparison.
4
+
5
+Thanks to [wiki-ng](https://git.dn42.dev/wiki/wiki-ng), based on their work, [dn42-wiki-go](https://github.com/iedon/dn42-wiki-go) can provide both static site generation and live edit.
6
+
7
+## Overview
8
+
9
+`dn42-wiki-go` provides a statically rendered, Git-backed documentation site for dn42. The binary can run in two modes:
10
+
11
+- **Live mode** (the default) serves HTTP directly, watches the upstream Git repository, and rebuilds pages on change.
12
+- **Static build mod (`live=false or run with --build`)e** produces pre-rendered HTML into `dist/` once, suitable for delivery by any web server.
13
+
14
+Nginx or another TLS proxy is still recommended for public access, but the application ships with native HTTPS and webhook support.
15
+
16
+## Prerequisites
17
+
18
+- A stable dn42-connected host with enough CPU and disk to cache the Git repository and generated site (`~500 MB`).
19
+- Operational Git access to `git.dn42.dev/wiki/wiki` (read-only for mirrors, write access if you contribute edits).
20
+- Software:
21
+ - [Go ≥ 1.24](https://go.dev/dl/) (only needed for building from source).
22
+ - [Git](https://git-scm.com/).
23
+ - Optional but recommended: [Nginx](https://nginx.org/) or [Caddy](https://caddyserver.com/) for TLS termination.
24
+ - Optional: [Docker](https://docs.docker.com/) / [Docker Compose](https://docs.docker.com/compose/) if you prefer containers.
25
+- Solid operational knowledge—production mirrors are expected to run reliably and coordinate with the dn42 maintainers.
26
+
27
+## Network
28
+
29
+- The daemon listens on the address configured in `config.json` (`listen`, default `:8080`). Use firewalling or a reverse proxy to expose the service on your chosen anycast/unicast IPs.
30
+- You may terminate HTTPS in-process (set `enableTLS`, `tlsCert`, `tlsKey`) or offload TLS to Nginx/Caddy.
31
+- If you operate an anycast mirror, advertise `172.23.0.80/32` and `fd42:d42:d42:80::1/64` only when the health checks succeed. ExaBGP or native BGP daemons work well; see the _Monitoring & Routing_ section.
32
+
33
+## Repository Synchronisation
34
+
35
+The wiki content lives in Git. The application already performs periodic pulls (configured via `git.pullIntervalSec`) and exposes a webhook for faster updates. You still need an initial clone and credentials.
36
+
37
+### Initial clone
38
+
39
+```bash
40
+git clone [email protected]:wiki/wiki.git repo
41
+```
42
+
43
+Populate `config.json` with the same `remote` URL and point `git.localDirectory` at the clone (default `./repo`).
44
+
45
+### Optional external sync script
46
+
47
+If you want an **independent** watchdog, a minimal cron job keeps the repository fresh:
48
+
49
+```bash
50
+#!/bin/sh
51
+set -euo pipefail
52
+cd /srv/dn42-wiki/repo
53
+/usr/bin/git pull --ff-only
54
+/usr/bin/git push # if you have write access
55
+```
56
+
57
+Schedule it every 5–15 minutes. Avoid overlapping with the built-in poll interval to reduce churn.
58
+
59
+## Application Setup
60
+
61
+1. Copy `config.example.json` to `config.json` and adjust:
62
+ - `live`: set `true` for mirrors that serve HTTP directly; set `false` to produce static HTML.
63
+ - `editable`: mirrors that allow edits should be reachable from dn42 only.
64
+ - `git.remote`: use your git.dn42 credentials. Leave empty to run against a local repository only.
65
+ - `webhook.enabled`: enable for fast sync and provide a shared secret.
66
+ - `webhook.polling`: set `enabled` and `endpoint` if you need active polling. `skipRemoteCert` lets you disable TLS verification for trusted endpoints. See also `dn42notifyd`.
67
+ - `trustedProxies`: add your reverse proxy or load balancer networks.
68
+
69
+2. Compile the binary:
70
+
71
+```bash
72
+./build.sh
73
+```
74
+
75
+3. Launch the service:
76
+
77
+```bash
78
+./dn42-wiki-go --config ./config.json
79
+```
80
+
81
+The first run performs a full static build into `dist/`. Subsequent requests serve directly from disk, and background pulls rebuild the output as needed.
82
+
83
+### Static-only build
84
+
85
+If you just need HTML assets:
86
+
87
+```bash
88
+./dn42-wiki-go --config ./config.json --build
89
+```
90
+
91
+Deploy `dist/` with any web server or object store.
92
+
93
+### Systemd unit (example)
94
+
95
+See [dn42-wiki-go.service](dn42-wiki-go.service) and [dn42-wiki-go.socket](dn42-wiki-go.socket).
96
+
97
+Reload systemd, enable, and start the service.
98
+
99
+## Reverse Proxy / TLS
100
+
101
+Place a reverse proxy in front of the daemon for certificate management and to present the canonical hostnames.
102
+
103
+The repository includes `nginx-vhost.conf` with a more complete example (HTTP -> HTTPS redirect, QUIC, static asset caching, and API proxying). Adjust:
104
+
105
+- `root` so it points at your rendered `dist/` directory when serving static files directly.
106
+- `proxy_pass` directives if you run the Go binary on a different port or on a Unix socket.
107
+- Certificate paths, `X-SiteID`, and anycast/unicast listener addresses to match your deployment.
108
+
109
+To keep HPKP/HSTS behaviour consistent with the legacy setup, reuse the same headers. Coordinate DNS and certification with the dn42 Automatic CA workflow when exposing official mirrors.
110
+
111
+## Docker & Compose
112
+
113
+The repository ships with a multi-stage `Dockerfile` and `docker-compose.yml`.
114
+
115
+```bash
116
+# Build and start
117
+docker compose up --build -d
118
+
119
+# Logs
120
+docker compose logs -f
121
+```
122
+
123
+Bind-mount `./config/config.json` to override settings and use `./data/dist` plus `./data/repo` for persistent state. The container runs as a non-root user and exposes port `8080`.
124
+
125
+## Webhooks & Polling
126
+
127
+- `/api/webhook/pull` and `/api/webhook/push` require the shared secret. Integrate them with your Git hosting or ExaBGP watchdog to trigger immediate pulls or pushes.
128
+- The optional poller registers with a remote notification service specified in `webhook.polling.endpoint`. Set `skipRemoteCert` only if the endpoint uses self-signed certificates you trust.
129
+
130
+## Monitoring & Routing
131
+
132
+For anycast mirrors, advertise the service prefix only when the local HTTP endpoint is healthy. A trimmed-down watchdog using ExaBGP:
133
+
134
+```bash
135
+#!/bin/sh
136
+set -eu
137
+check() {
138
+ curl -fsS --max-time 5 https://127.0.0.1:8443/ | grep -qi "dn42" # adjust scheme/port
139
+}
140
+
141
+announce() {
142
+ printf 'announce route 172.23.0.80/32 next-hop %s\n' "$NEXT_HOP"
143
+ printf 'announce route fd42:d42:d42:80::/64 next-hop %s\n' "$NEXT_HOP6"
144
+}
145
+
146
+withdraw() {
147
+ printf 'withdraw route 172.23.0.80/32 next-hop %s\n' "$NEXT_HOP"
148
+ printf 'withdraw route fd42:d42:d42:80::/64 next-hop %s\n' "$NEXT_HOP6"
149
+}
150
+
151
+state=down
152
+while sleep 30; do
153
+ if check; then
154
+ [ "$state" = down ] && { announce; state=up; }
155
+ else
156
+ [ "$state" = up ] && { withdraw; state=down; }
157
+ fi
158
+done
159
+```
160
+
161
+Run the script under an ExaBGP `process` stanza. Ensure your IGP routes traffic correctly to the service when announced.
162
+
163
+## Maintenance Checklist
164
+
165
+- Monitor `dist/` age and `dn42-wiki-go` logs for build errors.
166
+- Keep Go and system packages patched; rebuild after Go security releases.
167
+- Track upstream configuration changes (`config.example.json`) and merge them into your `config.json`.
168
+- Verify TLS certificates before expiry and renew via the Automatic CA process.
169
+- Coordinate with other maintainers (mailing list/IRC) when adding or retiring mirrors.