Восемнадцатого сентября у ClewWiki не было ни одного релиза. Когда я писал о заявках на страницы, образа и npm-пакета не было, ставить можно было только из исходников. Через семнадцать дней вышла версия 0.9.0 — десятый тег подряд, образ лежит в GHCR, MCP-сервер ставится через npx.
Эта статья для тех, кто выбирает вики для команды и хочет держать её у себя. Без агентов, без MCP — про них отдельный текст. Здесь только то, что нужно людям: как поставить, как привести коллег, как перенести старые страницы и где проект пока слабее давно существующих.
Что нужно, чтобы поднять#
Docker с Compose, git и openssl. Больше ничего. Ни Redis, ни почтового сервера, ни аккаунта у стороннего провайдера входа. Весь стек: приложение и PostgreSQL 16.
git clone https://github.com/Dodecaidr/clewwiki.git
cd clewwiki
cp .env.example .env && chmod 600 .env
sed -i "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 32)|" .env
sed -i "s|^BETTER_AUTH_SECRET=.*|BETTER_AUTH_SECRET=$(openssl rand -base64 48)|" .env
docker compose up -d
docker compose logs web | grep "setup token"На macOS вместо sed -i пишется sed -i ''. Дальше http://localhost:3000, setup-токен из лога и первый администратор. Паролей по умолчанию нет, угадывать нечего.
На сервере нужны ещё две вещи: BETTER_AUTH_URL с публичным https://-адресом и обратный прокси перед приложением. Приложение говорит по обычному HTTP и публикует порт только на 127.0.0.1, так что TLS остаётся за вами. В docs/deploy.md разобраны Caddy, Traefik и nginx.
Зависимостей мало намеренно. Вики в небольшой команде часто поднимает человек, у которого нет ни времени, ни желания администрировать четыре сервиса. Каждый лишний контейнер — ещё одна вещь, которая упадёт в субботу.
Как привести людей без почтового сервера#
Регистрации с улицы нет. Человек попадает в вики одним из трёх путей.
Приглашение-ссылка. Администратор в разделе Members вводит адрес и роль, получает ссылку. Она показывается один раз, срабатывает один раз и живёт семь дней. Письмо не отправляется: ссылку вы передаёте сами, в мессенджере или лично. Поэтому инстанс без SMTP ничем не урезан. В базе хранится только хеш ссылки.
Заявка на вступление. Если администраторы её включили, на странице входа появляется Ask to join. Человек оставляет имя, адрес, пароль и записку — и видит «ожидает подтверждения», пока администратор не одобрит его с конкретной ролью или не отклонит. Самому себе войти нельзя. Пять заявок в час с одного адреса.
Единый вход через OpenID Connect. Достаточно трёх переменных (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET), и на странице входа появляется кнопка. Вход по паролю при этом продолжает работать: если провайдер упал, администратор не остаётся снаружи. Провайдер решает, кто человек, но не пускать ли его: профиль без email_verified отклоняется, OIDC_ALLOWED_EMAIL_DOMAINS сужает круг по домену, а членство остаётся решением администратора, пока вы явно не включите OIDC_SIGN_UP.
Ролей три. Администратор управляет участниками, токенами агентов и пространствами. Редактор пишет страницы, участвует в обсуждениях и принимает правки агентов. Viewer появился в 0.6 для тех, для кого вики пишется: продакт, тестировщик, инженер заказчика. Он читает всё, что ему видно, — страницы, обсуждения, историю, поиск, экспорт — и ничего не меняет. Ограничение сидит там же, где у токена агента «только чтение»: запрос, которому нужно больше, получает 403. Последнего администратора нельзя ни понизить, ни удалить.
Забытый пароль раньше лечился удалением человека и новым приглашением, то есть новым аккаунтом. Теперь администратор делает ссылку сброса: одноразовая, на сутки, хранится хешем, после использования завершает все сессии аккаунта.
Несколько команд на одном сервере#
В 0.8 появились организации. Один инстанс держит несколько, у каждой свои участники, пространства, токены агентов, администраторы и настройки. Один аккаунт может состоять в нескольких и переключаться между ними меню у логотипа, а у каждой организации свой вход по адресу /o/<адрес>.
Внутри организации — пространства по проектам, в том числе закрытые: такое пространство видят только его участники. Если удалить человека из одной организации, аккаунт и членство в остальных остаются.
Для студии или агентства, которое ведёт документацию нескольких заказчиков, это ровно тот случай, когда раньше приходилось поднимать по вики на клиента.
Как перенести то, что уже написано#
Вики, в которую нельзя переехать, никто не выберет. Импорт в ClewWiki всегда идёт через промежуточный шаг: вы видите дерево страниц, которое получится, путь каждой страницы, её Markdown и пометки о том, что не сконвертировалось. Пока не нажата кнопка, ничего не создано.
Откуда можно переехать:
- Пространство Confluence — из облака через REST API v2, с собственного Server или Data Center через v1. Переносятся иерархия, заголовки, списки, таблицы, блоки кода с языком, информационные панели, раскрывающиеся блоки, ссылки между импортированными страницами и картинки. С включёнными файлами переезжают и вложения — вместе с прежними версиями, датой и комментарием.
- Экспорт Notion и архив Markdown — с картинками и файлами, на которые ссылаются страницы.
- PDF размером до 200 МБ.
Обратная дверь открыта так же широко: страница уходит в Markdown или HTML, пространство — в ZIP, по желанию вместе с файлами. Страницы хранятся как Markdown, поэтому уйти из ClewWiki — это скачать архив.
Здесь важны ограничения, и я назову их прямо. Комментарии, метки, права и история страниц из Confluence не читаются. Макрос, у которого нет аналога в Markdown, — списки задач Jira, дерево страниц, включения, диаграммы — становится видимой заметкой с его именем, а не рабочим содержимым. Импорт с Server и Data Center проверен на живом публичном инстансе и на фикстурах, но за ним нет лет эксплуатации. Если ваша вики держится на макросах и маркетплейсе — переезд не будет прозрачным, и docs/compare.md в репозитории так и говорит.
Почему эта тема вообще актуальна: Atlassian прекращает поддержку Data Center 28 марта 2029 года — после этой даты такие инсталляции становятся только для чтения, а новым клиентам их не продают с весны 2026-го. У команд, которые держали вики у себя по причинам безопасности или закона, причина никуда не делась, а продукт уходит.
Файлы рядом с документацией#
Начиная с 0.7 к странице можно приложить файл любого типа: сборку, установщик, спецификацию. Логику я подсмотрел у того, как команды на самом деле публикуют релизы.
Загрузили файл с тем же именем — появилась следующая версия под той же ссылкой. Ссылка всегда отдаёт последнюю, поэтому её можно один раз вставить в release notes и больше не трогать; ?version=3 закрепляет конкретную. Те же байты второй раз ничего не добавляют. Restore делает старую версию последней, добавляя её как новую, так что скачанная однажды версия не меняется никогда.
Кто подписан на страницу или пространство, видит новую версию во входящих. Хранятся файлы на локальном диске или в любом S3-совместимом бакете. Сборочный пайплайн публикует файл одной командой:
curl -fsS -X PUT --data-binary @dist/app-2.4.1.apk \
-H "Authorization: Bearer $CLEWWIKI_TOKEN" \
"https://wiki.example.com/api/v1/pages/$PAGE_ID/files/app-2.4.1.apk?note=Signed%20build"Токену нужен scope pages:write, и больше ничего. Повтор того же запроса вернёт 200 вместо 201 и новую версию не создаст, так что ретраи в CI безопасны.
Задачи и таблицы прямо в страницах#
В 0.8 вики научилась смотреть наружу.
Трекеры. YouTrack, Jira и любой трекер с ключами вида KEY-123. Администратор организации указывает адрес, ключи проектов и имя переменной окружения с токеном на чтение. Сам токен в базу не попадает. После этого ключи задач в тексте становятся ссылками, а страница показывает список упомянутых задач со статусом и исполнителем. Из редактора можно вставить задачу целиком, с описанием и комментариями, или таблицу задач по запросу YouTrack или JQL.
Тут одна оговорка, которую я не буду прятать: клиенты YouTrack и Jira протестированы на записанных ответах API, на живом инстансе — ещё нет. Если у вас есть тестовый проект, обратная связь будет очень кстати.
Таблицы. Диалог Import table or document принимает книгу Excel (.xlsx), CSV и TSV — в том числе с точкой с запятой, как их сохраняет русский или немецкий Excel, — и вставляет листы таблицами. Ячейки переносятся такими, какими их видно. Формула приходит результатом, дата датой, скрытые листы пропускаются. Ссылка на Google Таблицу или Google Документ с доступом «всем, у кого есть ссылка» тоже работает. В обратную сторону страница с таблицами экспортируется в .xlsx: лист на таблицу, название по заголовку над ней, шапка жирная и закреплена. Всё это написано собственным кодом проекта, без библиотеки для таблиц. Старый двоичный .xls не читается.
Где команда видит, что выпускается#
Версия 0.9.0, вышедшая 5 октября, добавляет в каждое пространство раздел Development. Это ответ на вопрос, который в маленьких командах задают на каждом созвоне: «а это уже в релизе?»
Раздел читает связанный с пространством git-репозиторий и заводит по потоку работы на каждую ветку: последний коммит, на сколько она впереди и позади основной, слита или нет, удалена ли. К потоку привязывается цель, задачи из трекера с их состоянием, страница документации и «проблемы», то есть обсуждения того, что мешает. Когда проблема решена, решение записывается страницей в документацию потока.
Мне самым полезным кажется подсвеченный список слито без релиза. Это работа, которая уже в основной ветке, но ни в один запланированный релиз не попала. Именно такие вещи потом всплывают фразой «а мы это вообще выкатывали?». Релиз отказывается отмечаться выпущенным, пока в нём есть неслитые потоки. Выпустить вопреки можно, но это попадает в аудит вместе с тем, что осталось за бортом.
Чего пока нет#
Список честный, он же есть в README:
- SAML и LDAP. Единый вход только через OpenID Connect, синхронизации с каталогом нет.
- Мобильного приложения. Веб-интерфейс работает на телефоне, нативного клиента нет.
- Лет в продакшене. Первый тег — 18 сентября 2026 года. У соседей по
docs/compare.mdот трёх до двадцати с лишним лет. Миграции между версиями 0.x пока идут часто, и делать резервную копию базы перед обновлением — не формальность. - Сообщества и компании за проектом. Это открытый проект одного автора. Если вам нужен вендор с SLA, ClewWiki вам сейчас не подходит.
Что есть в обмен: одна редакция под AGPL-3.0, где всё перечисленное выше бесплатно и не спрятано за платным тарифом на место, и стек, который поднимается одной командой. Интерфейс на русском и английском.
С чего начать#
Поднимите инстанс по команде выше на ноутбуке, импортируйте одно небольшое пространство и посмотрите на промежуточный экран — по нему за десять минут видно, переедет ваша вики или упрётся в макросы. Код, документация и трекер задач — в репозитории на GitHub, обзор проекта — на странице ClewWiki.
Если в вашей команде к вики подключены или скоро будут подключены AI-агенты, следующая статья — о том, что они получают в 0.9.
