Skip to content
DivByDiamondPublic

About

Wiki for the OC2R Minecraft mod: page history, reader edit suggestions, key-protected API. Rust (axum + SQLite) backend, TypeScript frontend.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

73 Commits

Folders and files

Repository files navigation

OC2R Wiki

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.

Rust TypeScript SQLite License Content

English | Русский


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.


English

Overview

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.

Features

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

Tech stack

  • 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

Build

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-wiki

Read locally

An empty database is populated automatically with 121 pages from OC2R (English, Russian). After building the frontend, run:

cargo run -p oc2r-wiki

Open 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.

Configuration

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.

GitHub OAuth app

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.

API keys

Sign in as an admin, open /admin/keys, create a key with the scopes you need and copy it: it is shown once.

Deploy

Ready-made files are in deploy/:

  • nginx-wiki.conf - nginx vhost: HTTP to HTTPS redirect, certbot certificate, proxy to 127.0.0.1:8091, real client IP from CF-Connecting-IP (trusted only from Cloudflare ranges), HSTS and CSP headers
  • down.html - fallback page that nginx serves with status 503 when the app is down
  • systemd/ - unit oc2r-wiki.service (reads /etc/oc2r-wiki.env) and the weekly backup oc2r-wiki-backup.service / .timer
  • backup.sh - SQLite backup to /var/lib/oc2r-wiki/backups, keeps 60 days

Checklist (skipping an item breaks the live site):

  • DNS: an A/AAAA record wiki.loki-code.dev -> the VPS, proxied (orange cloud) in Cloudflare.
  • Cloudflare SSL/TLS mode Full (strict); with Flexible the 80-to-443 redirect loops.
  • sqlite3 installed (apt install sqlite3); the backup script needs the CLI.
  • /var/lib/oc2r-wiki owned by wiki:wiki (database, working dir and backups).
  • /etc/oc2r-wiki.env (root, mode 600) with WIKI_BIND=127.0.0.1:8091, the absolute public PUBLIC_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.html to /var/www/oc2r-wiki/down.html.
  • Units: cp deploy/systemd/* /etc/systemd/system/ && systemctl daemon-reload, then systemctl enable --now oc2r-wiki oc2r-wiki-backup.timer.
  • nginx: copy deploy/nginx-wiki.conf to /etc/nginx/sites-available/wiki.loki-code.dev, link it into sites-enabled, run certbot --nginx -d wiki.loki-code.dev, then nginx -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_ip config).

API example

curl -X PUT -H "Authorization: Bearer $KEY" --data-binary @page.md \
  "https://wiki.loki-code.dev/api/pages/start?lang=en&summary=sync"

Documentation

License

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-файла и служба не перезапущена.

OAuth-приложение GitHub

Создайте его в 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.

Ключи API

Войдите админом, откройте /admin/keys, создайте ключ с нужными правами и скопируйте его: он показывается один раз.

Деплой

Готовые файлы лежат в deploy/:

  • nginx-wiki.conf - vhost nginx: редирект с HTTP на HTTPS, сертификат certbot, проксирование на 127.0.0.1:8091, реальный IP клиента из CF-Connecting-IP (доверяется только диапазонам Cloudflare), заголовки HSTS и CSP
  • down.html - страница-заглушка, которую nginx отдаёт со статусом 503, когда приложение недоступно
  • systemd/ - unit oc2r-wiki.service (читает /etc/oc2r-wiki.env) и еженедельная копия oc2r-wiki-backup.service / .timer
  • backup.sh - копия SQLite в /var/lib/oc2r-wiki/backups, хранится 60 дней

Чеклист (пропуск любого пункта ломает живой сайт):

  • DNS: запись A/AAAA wiki.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).

Пример API

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 - роли, история, предложения, админка, API
  • docs/reader.md - разделы, стиль, настройки, ошибки, тесты
  • docs/structure.md - структура репозитория и правила кода
  • todo.md - план реализации

Лицензия

GPL-3.0-or-later, см. LICENSE.

About

Wiki for the OC2R Minecraft mod: page history, reader edit suggestions, key-protected API. Rust (axum + SQLite) backend, TypeScript frontend.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages