Більшість інструментів документації на власному сервері вимагають бази даних, зворотного проксі та половини дня редагування YAML, перш ніж ви побачите екран привітання. DocPlatform — це один бінарний файл на Go без зовнішніх залежностей. Ця інструкція проведе вас від нуля до опублікованої документації приблизно за п’ять хвилин.
Передумови
Вам потрібен комп’ютер з Linux, macOS або Windows. Це все. Ні Docker, ні PostgreSQL, ні Node.js. DocPlatform компілюється в один статичний бінарний файл — середовище Go вбудоване. Якщо вам цікава мова реалізації, Go створює самодостатні виконувані файли, що працюють без встановлення будь-чого на хості.
Крок 1: Завантаження та встановлення
На Linux або macOS скрипт встановлення зробить все автоматично:
curl -fsSL https://valoryx.org/install.sh | bash
Це завантажує останній реліз у /usr/local/bin/docplatform (або ~/.local/bin/, якщо у вас немає прав root). На macOS з Homebrew також можна виконати:
brew install valoryx/tap/docplatform
На Windows завантажте .exe зі сторінки релізів та додайте його до PATH.
Перевірте встановлення:
docplatform version
# DocPlatform v1.x.x (linux/amd64)
Крок 2: Запуск сервера
Запустіть сервер із налаштуваннями за замовчуванням:
docplatform serve
Ви побачите приблизно таке:
INFO Starting DocPlatform server
INFO Data directory: ./data
INFO Listening on http://localhost:3000
INFO Full-text search index: ready
INFO Admin setup required — visit http://localhost:3000 to create your account
Відкрийте http://localhost:3000 у браузері. DocPlatform обслуговує і редактор, і опублікований сайт з одного бінарного файлу на одному порті. Окремий крок збірки фронтенду не потрібен.
При першому запуску ви побачите екран налаштування адміністратора. Виберіть ім’я користувача та пароль. Це створює обліковий запис суперадміністратора — того, хто може керувати всім. Інших користувачів можна додати пізніше через панель адміністратора.
Крок 3: Створення першого workspace
Після входу на панелі керування відображається порожній список workspace. Натисніть New Workspace і заповніть:
- Name:
engineering-handbook(або те, що ви документуєте) - Slug:
engineering-handbook(стане частиною URL) - Theme: Виберіть одну з 7 вбудованих тем — її можна змінити пізніше
Натисніть Create. Тепер у вас є workspace з кореневою сторінкою, готовою до редагування.
Крок 4: Напишіть документацію
Зайдіть у новий workspace, і ви потрапите до WYSIWYG-редактора. Він підтримує markdown-скорочення — введіть ## з пробілом, щоб створити H2, використовуйте зворотні лапки для вбудованого коду, потрійні зворотні лапки для блоків коду. Все, що ви очікуєте від сучасного редактора, але з рендерингом форматованого тексту під час введення.
Створіть кілька сторінок, щоб відчути процес:
- Натисніть New Page на бічній панелі
- Дайте назву: “Getting Started”
- Напишіть контент — можете вставити існуючий markdown
- Натисніть Ctrl+S (або Cmd+S на macOS) для збереження
Сторінка зберігається в локальній базі даних SQLite DocPlatform (вбудованій у бінарний файл — зовнішня база даних не потрібна). Кожне збереження створює версію, до якої можна повернутися.
Спробуйте створити дочірню сторінку: наведіть курсор на “Getting Started” на бічній панелі та натисніть іконку +. Тепер у вас є ієрархія сторінок.
Крок 5: Публікація документації
Щоб зробити документацію публічно доступною, перейдіть до Workspace Settings > Publishing і переключіть стан публікації на On. Ваша документація тепер доступна за адресою:
http://localhost:3000/s/engineering-handbook
Префікс /s/ обслуговує опубліковане подання тільки для читання. Воно використовує обрану вами тему, має повнотекстовий пошук на базі Bleve та навігаційне дерево на бічній панелі, побудоване з ієрархії ваших сторінок.
Ось і все. П’ять команд, жодних конфігураційних файлів, і у вас працюючий сайт документації.
Що працює під капотом
Коли ви запустили docplatform serve, ви запустили один процес, який обробляє:
- HTTP-сервер — обслуговує UI редактора, API та опублікований сайт документації
- База даних SQLite — зберігає користувачів, workspace, сторінки та версії
- Пошуковий індекс Bleve — повнотекстовий пошук із толерантністю до помилок і ранжуванням за релевантністю
- Автентифікація WebAuthn/passkey — сучасна безпарольна автентифікація поряд із традиційною за логіном/паролем
- RBAC — 5 ролей (суперадмін, адмін, редактор, переглядач, гість) із детальними дозволами
Все це працює в одному процесі, використовуючи приблизно 50–80 МБ оперативної пам’яті. Жодних фонових воркерів, черг повідомлень чи мікросервісів.
Крок 6: Підключення Git (необов’язково)
Якщо ви хочете зберігати документацію в git-репозиторії — з контролем версій, перевірками, можливістю редагування з IDE — DocPlatform підтримує двосторонню синхронізацію з git. Прочитайте посібник зі швидкого старту для повного налаштування, але коротко:
- Перейдіть до Workspace Settings > Git Sync
- Вставте URL репозиторію та deploy key
- Виберіть гілку
- Натисніть Enable Sync
Відтепер кожне збереження в редакторі створює git commit, а кожен push до репозиторію з IDE чи CI-конвеєра відображається в редакторі. Це не одностороннє дзеркало — це справжня двостороння синхронізація з використанням патерну Content Ledger (див. Чому git-інструменти для документації ламають синхронізацію для технічного пояснення).
Запуск у продакшені
Для розгортання у продакшені вам знадобиться встановити кілька змінних середовища:
export DOCPLATFORM_PORT=3000
export DOCPLATFORM_DATA_DIR=/var/lib/docplatform
export DOCPLATFORM_BASE_URL=https://docs.yourcompany.com
docplatform serve
Поставте його за зворотний проксі (Nginx, Caddy або Cloudflare Tunnel) для терминації HTTPS. Використовуйте systemd unit або аналог для підтримки роботи:
[Unit]
Description=DocPlatform Documentation Server
After=network.target
[Service]
ExecStart=/usr/local/bin/docplatform serve
WorkingDirectory=/var/lib/docplatform
Restart=always
User=docplatform
[Install]
WantedBy=multi-user.target
Регулярно робіть резервні копії директорії даних — вона містить базу даних SQLite та пошуковий індекс. Просте cp або rsync під час роботи сервера працює нормально (SQLite коректно обробляє конкурентне читання).
Наступні кроки
Тепер у вас працююча платформа документації. Ось куди рухатися далі:
- Повний посібник зі швидкого старту — охоплює git sync, теми та управління користувачами
- Створення першого workspace — детальна конфігурація workspace
- Варіанти встановлення — всі методи завантаження, включаючи збірки для ARM
Community Edition DocPlatform безкоштовний, без обмежень на кількість користувачів, сторінок і без функціональних обмежень. Завантажте бінарний файл і починайте писати. Все необхідне міститься в одному файлі.