Wiki for the OC2R Minecraft mod, with page history, reader edit suggestions and a key-protected API. Rust backend, TypeScript frontend, one binary, one SQLite file.
Status: local wiki with bundled OC2R documentation. See content and import guide for startup, sources, and safe updates. Hosting and GitHub sign-in require deployment configuration.
OC2R Wiki is the documentation site for OC2R at wiki.loki-code.dev, aimed at players and script authors. Pages live in a database, every edit is a revision, and any old version can be opened, compared and restored.
Admins and API keys edit pages directly. Everyone else signs in with GitHub and sends a suggestion, which an admin accepts or rejects.
| Feature | Description |
|---|---|
| Page history | Every edit is an immutable revision with author and comment. Open any version, diff two versions, roll back |
| Edit suggestions | Readers sign in with GitHub and propose changes, admins review a diff and accept or reject |
| API by key | PUT pages from CI or scripts with a scoped key (read, write, export), keys are stored hashed |
| Admin panel | Markdown editor with live preview, suggestion queue, history and rollback, key management |
| Server-side rendering | Markdown is rendered and sanitized on the server, pages work without JavaScript |
| Search | Full-text search (SQLite FTS5) |
| Languages | English, Russian; browser detection, remembered choice, English fallback |
| Reader settings | Light or dark theme, accent color, font size, optional pixel borders, stored in the browser |
- Backend: Rust (edition 2024), axum, SQLite (rusqlite), pulldown-cmark, ammonia
- Frontend: TypeScript without runtime libraries, built with Bun
- Deploy: one binary and one database file behind nginx, Cloudflare in front
The frontend must be built before cargo build: the server embeds the assets from web/dist into the binary. Build web/ first: a release build fails when web/dist/app.js or app.css is missing, a debug build only warns, and cargo test needs the build too.
cd web && bun install --frozen-lockfile && bun run build
cd .. && cargo build --release -p oc2r-wikiAn empty database is populated automatically with 121 pages from OC2R (English, Russian). After building the frontend, run:
cargo run -p oc2r-wikiOpen http://127.0.0.1:8080/en/start. Existing databases are left untouched on startup; use WIKI_DB=/path/wiki.db ./target/release/oc2r-wiki --sync-content to import/update bundle-owned pages while preserving editor changes. See content sources and updates.
| Variable | Description |
|---|---|
WIKI_BIND |
Listen address, default 127.0.0.1:8080 |
WIKI_DB |
Path to the SQLite file, default wiki.db |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET |
GitHub login credentials |
PUBLIC_URL |
Public site URL, used for the login callback |
ADMIN_GITHUB_IDS |
Comma-separated numeric GitHub user ids that become admins on sign-in |
RUST_LOG |
Log level, for example info |
On the production server all variables are read from /etc/oc2r-wiki.env (root, mode 600), with WIKI_BIND=127.0.0.1:8091 and PUBLIC_URL=https://wiki.loki-code.dev. Port 8080 is taken there by another container.
ADMIN_GITHUB_IDS is applied on every sign-in: demoting that user in /admin/users is undone the next time they sign in unless the id is removed from the env file and the service is restarted.
Create one at GitHub: Settings, Developer settings, OAuth Apps, New. Set the callback URL to <PUBLIC_URL>/auth/github/callback, then put the client id and secret into GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET. Find your numeric id at https://api.github.com/users/<login> and list it in ADMIN_GITHUB_IDS.
Sign in as an admin, open /admin/keys, create a key with the scopes you need and copy it: it is shown once.
Ready-made files are in deploy/:
nginx-wiki.conf- nginx vhost: HTTP to HTTPS redirect, certbot certificate, proxy to127.0.0.1:8091, real client IP fromCF-Connecting-IP(trusted only from Cloudflare ranges), HSTS and CSP headersdown.html- fallback page that nginx serves with status 503 when the app is downsystemd/- unitoc2r-wiki.service(reads/etc/oc2r-wiki.env) and the weekly backupoc2r-wiki-backup.service/.timerbackup.sh- SQLite backup to/var/lib/oc2r-wiki/backups, keeps 60 days
Checklist (skipping an item breaks the live site):
- DNS: an
A/AAAArecordwiki.loki-code.dev-> the VPS, proxied (orange cloud) in Cloudflare. - Cloudflare SSL/TLS mode Full (strict); with Flexible the 80-to-443 redirect loops.
sqlite3installed (apt install sqlite3); the backup script needs the CLI./var/lib/oc2r-wikiowned bywiki:wiki(database, working dir and backups)./etc/oc2r-wiki.env(root, mode 600) withWIKI_BIND=127.0.0.1:8091, the absolute publicPUBLIC_URL=https://wiki.loki-code.dev(a wrong value makes every admin POST 403 and points the OAuth callback at loopback),GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,ADMIN_GITHUB_IDS=<numeric id>.- Copy
deploy/down.htmlto/var/www/oc2r-wiki/down.html. - Units:
cp deploy/systemd/* /etc/systemd/system/ && systemctl daemon-reload, thensystemctl enable --now oc2r-wiki oc2r-wiki-backup.timer. - nginx: copy
deploy/nginx-wiki.confto/etc/nginx/sites-available/wiki.loki-code.dev, link it intosites-enabled, runcertbot --nginx -d wiki.loki-code.dev, thennginx -t && systemctl reload nginx. - Firewall: allow 80/443 only from Cloudflare ranges so the origin is not reachable directly (belt and braces with the nginx
real_ipconfig).
curl -X PUT -H "Authorization: Bearer $KEY" --data-binary @page.md \
"https://wiki.loki-code.dev/api/pages/start?lang=en&summary=sync"docs/design.md- decisions, architecture, data model, deploydocs/workflows.md- roles, history, suggestions, admin panel, APIdocs/reader.md- sections, style, settings, errors, testsdocs/structure.md- repository layout and code rulestodo.md- implementation plan
GPL-3.0-or-later, see LICENSE.
OC2R Wiki - сайт документации мода OC2R на wiki.loki-code.dev для игроков и авторов скриптов. Страницы хранятся в базе, каждая правка - это ревизия, а любую старую версию можно открыть, сравнить и восстановить.
Админы и API-ключи правят страницы напрямую. Остальные входят через GitHub и отправляют предложения, которые админ принимает или отклоняет.
| Возможность | Описание |
|---|---|
| История страниц | Каждая правка - неизменяемая ревизия с автором и комментарием. Можно открыть любую версию, сравнить две версии, откатить |
| Предложения правок | Читатели входят через GitHub и предлагают изменения, админ смотрит diff и принимает или отклоняет |
| API по ключу | PUT страниц из CI или скриптов ключом с правами (read, write, export), ключи хранятся хешами |
| Админка | Markdown-редактор с живым превью, очередь предложений, история и откат, управление ключами |
| Рендер на сервере | Markdown рендерится и очищается на сервере, страницы работают без JavaScript |
| Поиск | Полнотекстовый поиск (SQLite FTS5) |
| Языки | Английский, русский; выбор по браузеру, сохранение языка, откат на английский |
| Настройки читателя | Светлая или тёмная тема, акцентный цвет, размер шрифта, пиксель-рамки по желанию, хранятся в браузере |
- Бэкенд: Rust (edition 2024), axum, SQLite (rusqlite), pulldown-cmark, ammonia
- Фронтенд: TypeScript без рантайм-библиотек, сборка через Bun
- Деплой: один бинарник и один файл базы за nginx, спереди Cloudflare
Фронтенд нужно собрать до cargo build: сервер встраивает ассеты из web/dist в бинарник. Сначала соберите web/: релизная сборка падает, если нет web/dist/app.js или app.css, отладочная только предупреждает, а cargo test тоже требует сборки.
cd web && bun install --frozen-lockfile && bun run build
cd .. && cargo build --release -p oc2r-wikiВ пустую базу автоматически загружаются 121 страниц из OC2R на русском и английском. После сборки фронтенда:
cargo run -p oc2r-wikiОткрыть http://127.0.0.1:8080/ru/start. Существующая база при запуске не меняется. Импорт и обновление страниц пакета с сохранением ручных правок: WIKI_DB=/path/wiki.db ./target/release/oc2r-wiki --sync-content. Подробнее: источники, наполнение и обновление.
| Переменная | Описание |
|---|---|
WIKI_BIND |
Адрес для прослушивания, по умолчанию 127.0.0.1:8080 |
WIKI_DB |
Путь к файлу SQLite, по умолчанию wiki.db |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET |
Данные приложения GitHub для входа |
PUBLIC_URL |
Публичный адрес сайта, нужен для callback входа |
ADMIN_GITHUB_IDS |
Числовые id пользователей GitHub через запятую, которые становятся админами при входе |
RUST_LOG |
Уровень логов, например info |
На продакшен-сервере все переменные читаются из /etc/oc2r-wiki.env (root, режим 600), там WIKI_BIND=127.0.0.1:8091 и PUBLIC_URL=https://wiki.loki-code.dev. Порт 8080 там занят другим контейнером.
ADMIN_GITHUB_IDS применяется при каждом входе: если снять с пользователя админку в /admin/users, она вернётся при следующем входе, пока id не убран из env-файла и служба не перезапущена.
Создайте его в GitHub: Settings, Developer settings, OAuth Apps, New. Callback URL: <PUBLIC_URL>/auth/github/callback. Client id и secret положите в GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET. Числовой id узнать можно на https://api.github.com/users/<login>, его нужно указать в ADMIN_GITHUB_IDS.
Войдите админом, откройте /admin/keys, создайте ключ с нужными правами и скопируйте его: он показывается один раз.
Готовые файлы лежат в deploy/:
nginx-wiki.conf- vhost nginx: редирект с HTTP на HTTPS, сертификат certbot, проксирование на127.0.0.1:8091, реальный IP клиента изCF-Connecting-IP(доверяется только диапазонам Cloudflare), заголовки HSTS и CSPdown.html- страница-заглушка, которую nginx отдаёт со статусом 503, когда приложение недоступноsystemd/- unitoc2r-wiki.service(читает/etc/oc2r-wiki.env) и еженедельная копияoc2r-wiki-backup.service/.timerbackup.sh- копия SQLite в/var/lib/oc2r-wiki/backups, хранится 60 дней
Чеклист (пропуск любого пункта ломает живой сайт):
- DNS: запись
A/AAAAwiki.loki-code.dev-> VPS, проксируется (оранжевое облако) в Cloudflare. - Режим SSL/TLS в Cloudflare Full (strict); при Flexible редирект с 80 на 443 зацикливается.
- Установлен
sqlite3(apt install sqlite3); он нужен скрипту копии. - Каталог
/var/lib/oc2r-wikiпринадлежитwiki:wiki(база, рабочий каталог и копии). /etc/oc2r-wiki.env(root, режим 600) сWIKI_BIND=127.0.0.1:8091, абсолютным публичнымPUBLIC_URL=https://wiki.loki-code.dev(неверное значение делает каждый admin POST 403 и уводит callback OAuth на loopback),GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,ADMIN_GITHUB_IDS=<числовой id>.- Скопировать
deploy/down.htmlв/var/www/oc2r-wiki/down.html. - Unit-файлы:
cp deploy/systemd/* /etc/systemd/system/ && systemctl daemon-reload, затемsystemctl enable --now oc2r-wiki oc2r-wiki-backup.timer. - nginx: скопировать
deploy/nginx-wiki.confв/etc/nginx/sites-available/wiki.loki-code.dev, слинковать вsites-enabled, выполнитьcertbot --nginx -d wiki.loki-code.dev, затемnginx -t && systemctl reload nginx. - Фаервол: разрешить 80/443 только диапазонам Cloudflare, чтобы origin нельзя было открыть напрямую (подстраховка к
real_ipв nginx).
curl -X PUT -H "Authorization: Bearer $KEY" --data-binary @page.md \
"https://wiki.loki-code.dev/api/pages/start?lang=en&summary=sync"docs/design.md- решения, архитектура, данные, деплойdocs/workflows.md- роли, история, предложения, админка, APIdocs/reader.md- разделы, стиль, настройки, ошибки, тестыdocs/structure.md- структура репозитория и правила кодаtodo.md- план реализации
GPL-3.0-or-later, см. LICENSE.