Контрольний список для виробництва

Використовуйте цей контрольний список перед розгортанням DocPlatform у виробничому середовищі. Кожен пункт посилається на відповідний розділ документації.

Обов’язково

Ці пункти необхідні для безпечного та надійного виробничого розгортання.

Сервер

• Постійне сховище налаштовано — Підключіть том або використовуйте стабільний шлях файлової системи для DATA_DIR. Втрата цієї директорії означає втрату всіх даних.
• Менеджер процесів на місці — Використовуйте systemd, Docker з restart: unless-stopped або оркестратор контейнерів для забезпечення перезапуску сервера після аварій або перезавантажень.
• Порт доступний — Переконайтесь, що налаштований PORT (за замовчуванням: 3000) доступний з вашої мережі або зворотного проксі.
• Достатньо ресурсів — Мінімум 128 МБ RAM, 200 МБ диску. Рекомендовано 512 МБ RAM, 1 ГБ диску.

Безпека

• TLS увімкнено — Запускайте за зворотним проксі (Caddy, nginx, хмарний балансувальник навантаження) з HTTPS. DocPlatform не здійснює TLS термінацію самостійно.
• JWT ключ захищений — Файл jwt-key.pem дає можливість підробляти автентифікаційні токени. Обмежте дозволи файлової системи: chmod 600.
• Перший користувач зареєстрований — Перший зареєстрований користувач стає Super Admin. Зареєструйте обліковий запис адміністратора перед відкриттям сервера для інших.
• Прив’язка до localhost — Якщо використовуєте зворотний проксі на тому ж хості, встановіть HOST=127.0.0.1, щоб DocPlatform не був доступний напряму.

Резервне копіювання

• Резервне копіювання увімкнено — BACKUP_ENABLED=true (за замовчуванням). Перевірте, що резервні копії створюються в {DATA_DIR}/backups/.
• Термін зберігання резервних копій встановлено — BACKUP_RETENTION_DAYS налаштовано відповідно до вашої політики (за замовчуванням: 7 днів).
• Резервне копіювання поза сервером — Копіюйте файли резервних копій на окреме місце (S3, NFS, інший сервер). Резервні копії на диску не захищають від відмови диска.

Рекомендовано

Ці пункти покращують надійність, безпеку та досвід команди.

Автентифікація

• OIDC налаштовано — Якщо ваша команда використовує Google або GitHub, увімкніть вхід через OIDC для делегування управління паролями. Див. Автентифікація.
• SMTP налаштовано — Увімкніть email для запрошень до робочих просторів та скидання паролів. Без SMTP токени виводяться в stdout. Див. Змінні середовища.

Git

• SSH deploy key створено — Для приватних репозиторіїв згенеруйте виділений deploy key із доступом на запис. Див. Інтеграція з Git.
• Webhook налаштовано — Для майже миттєвої синхронізації налаштуйте push webhook у вашому провайдері git хостингу. Polling (за замовчуванням: 5 хвилин) працює, але додає затримку.
• Git встановлено на хості — Хоча go-git обробляє більшість операцій, нативний git CLI потрібен для великих репозиторіїв (>1 ГБ).

Моніторинг

• Ендпоінт здоров’я під контролем — Опитуйте GET /health з вашої системи моніторингу (Uptime Robot, Prometheus blackbox exporter тощо).
• Логи збираються — DocPlatform виводить JSON-структуровані логи в stdout. Перенаправте їх до вашого агрегатора логів (ELK, Datadog, CloudWatch).
• Використання диска під контролем — Бази даних SQLite та пошукові індекси зростають із контентом. Налаштуйте сповіщення, коли використання диска перевищує 80%.

Операції

• docplatform doctor запущено — Виконайте docplatform doctor після початкового налаштування для перевірки узгодженості FS/DB, стану пошуку та битих посилань.
• Процес оновлення задокументовано — Задокументуйте, як ваша команда оновлює DocPlatform (заміна бінарного файлу + перезапуск, або Docker pull + пересоздання).
• План відкату на місці — Зберігайте попередню версію бінарного файлу та знайте, як відновити з резервної копії бази даних.

Обмеження ресурсів Community Edition

Community Edition включає наступні жорстко закодовані обмеження:

Community Edition не має обмежень функціональності. Усі можливості доступні без ліцензійного ключа.

Міркування щодо масштабування

DocPlatform Community Edition працює як єдиний екземпляр із базою даних SQLite з одним записувачем. Це правильна архітектура для цільового масштабу:

Якщо вам потрібно масштабуватися за ці межі, майбутні видання підтримуватимуть розгортання кількох екземплярів, зовнішні бази даних та Meilisearch.

Посилення безпеки

Мережа

• Запускайте за зворотним проксі з TLS
• Встановіть HOST=127.0.0.1 для блокування прямого доступу
• Використовуйте правила файрвола для обмеження доступу до сервера
• Проксі WebSocket — переконайтесь, що ваш зворотний проксі підтримує WebSocket upgrade. Без цього присутність у реальному часі та живі оновлення не працюватимуть. І Caddy, і nginx (з proxy_http_version 1.1 та заголовками Upgrade) підтримують це.

Заголовки відповіді

DocPlatform автоматично встановлює заголовки безпеки на всі відповіді:

Файлова система

• Запускайте під виділеним непривілейованим користувачем (systemd: User=docplatform)
• Обмежте дозволи директорії даних: chmod 700 {DATA_DIR}
• Обмежте дозволи JWT ключа: chmod 600 {DATA_DIR}/jwt-key.pem

Автентифікація

• Увімкніть OIDC для зменшення кількості локально збережених облікових даних
• Використовуйте надійні паролі (DocPlatform використовує argon2id — стійкий до перебору)
• Регулярно переглядайте активні сесії (Admin panel → Users → Sessions)

Оновлення

• Підпишіться на GitHub releases для отримання оновлень безпеки
• Оновлюйте оперативно при випуску патчів безпеки
• Запускайте docplatform doctor після кожного оновлення

Приклад: мінімальне виробниче налаштування

# 1. Install
sudo mv docplatform /usr/local/bin/

# 2. Create service user and data directory
sudo useradd -r -s /sbin/nologin docplatform
sudo mkdir -p /var/lib/docplatform
sudo chown docplatform:docplatform /var/lib/docplatform

# 3. Initialize workspace
cd /var/lib/docplatform
sudo -u docplatform docplatform init \
  --workspace-name "Docs" \
  --slug docs

# 4. Configure environment
sudo mkdir -p /etc/docplatform
sudo tee /etc/docplatform/.env <<EOF
PORT=3000
HOST=127.0.0.1
DATA_DIR=/var/lib/docplatform
BACKUP_RETENTION_DAYS=30
EOF

# 5. Create systemd service (see Binary Deployment guide)
# 6. Set up reverse proxy with TLS (see Binary Deployment guide)

# 7. Start and verify
sudo systemctl enable --now docplatform
docplatform doctor

# 8. Register admin account at https://docs.yourcompany.com