Большинство инструментов для самостоятельного хостинга документации требуют базу данных, обратный прокси и полдня правки 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 в боковой панели
- Дайте ей заголовок: «Начало работы»
- Напишите контент — вставьте существующий markdown, если он есть
- Нажмите Ctrl+S (или Cmd+S на macOS) для сохранения
Страница сохраняется в локальную базу данных SQLite DocPlatform (встроенную в бинарный файл — без внешней базы данных). Каждое сохранение создаёт версию, к которой можно откатиться.
Попробуйте создать дочернюю страницу: наведите на «Начало работы» в боковой панели и нажмите иконку +. Теперь у вас есть иерархия страниц.
Шаг 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-коммит, а каждый 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-синхронизацию, темы и управление пользователями
- Создание первого workspace — подробная настройка workspace
- Варианты установки — все способы скачивания, включая сборки для ARM
Community Edition DocPlatform бесплатен, без ограничений на пользователей, страницы и функции. Скачайте бинарный файл и начните писать. Всё необходимое — в одном файле.