guard/docs/deployment.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
2026-11-16 14:51:50 +01:00

148 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Deployment - Rampart
> Как поднять Rampart с нуля.
---
## 1. Компоненты
| Бинарь | Роль | Порт по умолчанию |
|--------|------|-------------------|
| `rampart` | Edge-нода: XDP + PoW + userspace-фильтр | 25565 (+ metrics 9090) |
| `rampart-manager` | REST API управления | 8080 |
| `rampart-cli` | Управление через Manager API | — |
## 2. Требования
### Edge
- Ubuntu 22.04+ / Debian 12, kernel 5.10+
- KVM или bare metal (OpenVZ/LXC — XDP не работает)
- Rust toolchain для сборки
Для XDP дополнительно: `libelf-dev libbpf-dev clang linux-libc-dev`.
### Manager
- Любая VDS с Docker (Redis обязателен)
## 3. Быстрый старт — Edge
```bash
# Сборка edge для Minecraft Java
git clone https://github.com/loki5512344ss/guard.git && cd guard
cargo build --release --features protocol-minecraft --bin rampart
# Установка
sudo cp target/release/rampart /usr/local/bin/
# Конфиг
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge.toml /etc/rampart/config.toml
# Отредактируй backend.upstreams под свои бэкенды
# systemd unit
cat > /etc/systemd/system/rampart.service << 'EOF'
[Unit]
Description=Rampart Edge Node
After=network.target
[Service]
Type=simple
Environment=RAMPART_CONFIG=/etc/rampart/config.toml
ExecStart=/usr/local/bin/rampart
Restart=always
RestartSec=5
LimitNOFILE=65535
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now rampart
# Проверка
journalctl -u rampart -f
```
Minecraft-конфиг рассчитан на один Paper backend. Если включён
`protocol.minecraft.send_proxy_protocol`, включи `proxies.proxy-protocol: true` в
Paper и закрой backend-порт firewall-ом от всех, кроме Rampart. Для подробной
схемы с домашним сервером и защищённым VDS см. [Minecraft Java guide](minecraft-java.md).
## 4. Быстрый старт — Manager
```bash
export REDIS_URL="redis://127.0.0.1:6379/0"
export JWT_SECRET="$(openssl rand -hex 32)" # минимум 32 байта без пробелов
export API_PASSWORD="$(openssl rand -base64 24)" # минимум 16 символов, дефолт запрещён
cargo run --release --bin rampart-manager
# API на 0.0.0.0:8080
```
Manager refuses to start with an empty `API_PASSWORD`, a password shorter than
16 characters, the default placeholder (which must not be `changeme`), or a
`JWT_SECRET` with fewer than 32 non-whitespace bytes.
Manager listens on all interfaces by default. Permit `8080` only from an admin
VPN or specific admin addresses; do not expose the API to the public Internet.
The same applies to Redis (`6379`) and monitoring endpoints such as Prometheus
(`9090`), ClickHouse (`8123`/`9000`) and Grafana (`3000`). The sample Compose
files bind published ClickHouse and Grafana ports to `127.0.0.1` only, so reach
them through an SSH tunnel or a local admin session, never through the public
interface. `deploy/docker-compose.yml` publishes no Redis port at all and the
root `docker-compose.yml` binds it to loopback; both refuse to start unless
`REDIS_PASSWORD` and `GRAFANA_PASSWORD` are set. Cross-origin access to the
manager API is disabled unless `CORS_ORIGIN` is set explicitly (`*` or a
comma-separated origin list).
Инфраструктура (Redis, ClickHouse, Grafana) требует пароли из окружения —
Compose не стартует без них:
```bash
export REDIS_PASSWORD="$(openssl rand -base64 24)"
export GRAFANA_PASSWORD="$(openssl rand -base64 24)"
docker compose up -d redis clickhouse grafana
```
Для нескольких edge и Manager укажи один и тот же защищённый Redis endpoint в
`store.redis_url` каждого edge и `REDIS_URL` Manager. Edge передаёт туда
локальные автобаны и восстанавливает общие bans после переподключения. Открой
Redis только через private network/VPN; при пустом `redis_url` edge остаётся
автономным, и автобаны между узлами не распространяются.
## 5. Docker
```bash
# Пароли обязательны: без REDIS_PASSWORD/GRAFANA_PASSWORD Compose падает
export REDIS_PASSWORD="$(openssl rand -base64 24)"
export GRAFANA_PASSWORD="$(openssl rand -base64 24)"
# Образ edge
docker build -f deploy/docker/Dockerfile.edge -t rampart-edge .
# Полный стек edge + инфраструктура
docker compose -f deploy/docker-compose.yml up -d
```
Edge подключается к Redis по имени сервиса. Поскольку Redis в Compose требует
пароль, впиши его в URL конфига edge (`deploy/config/edge-docker.toml`) — тот
же пароль, что в `REDIS_PASSWORD`:
```toml
[store]
redis_url = "redis://:PASSWORD@redis:6379/0"
```
## 6. Проверка после деплоя
```bash
☐ systemctl status rampart
☐ ss -tlnp | grep 25565
☐ curl http://localhost:9090/metrics | grep rampart_
☐ rampart-cli status # через Manager API
☐ rampart-cli doctor # диагностика
```
---
*Версия: 3.0 | Ноябрь 2026*