¶ Развёртывание и настройка Wikijs
Небольшое предисловие. Для хранения и редактирования документации я выбрал wikijs не случайно. Я протестировал Hugo, Sphinx, MKDocs, Gitbook, Gi (offline, не поддерживается, имеет ветку deprecated), GitHub Pages. Пробовал даже Jupiter notebook и локальные варианты, вроде Obsidian с публикацией на Git и кувырканиями с PDF через pandoc и построением диаграмм с mermaid.
В итоге дропнул все варианты, потому что всё не то. Везде есть недочёты, огрехи, ограничения бесплатных версий и всякое разное "не то".
На Wikijs остановился потому что это:
- Опенсорс, который стабильно развивается;
- Имеет API, причём неплохо документированный;
- Хорошо рендерит статику, лучше того же MKDocs или Gitbook;
- Имеет нормальную логинку;
- Имеет интеграцию с Git и различные варианты управления версиями (синхронизация сейчас, забрать всё, конфликты и т.д);
- Имеет встроенные инструменты управления группами, доступом;
- Имеет много стилей оформления текста: от стандартного Markdown до JS-сценариев. Последнее едва ли когда-то понадобится, но всё же;
- Умеет оставлять комментарии с указанием, кто оставил и когда;
- Имеет интеграцию с SMTP;
- Имеет человеческий поиск + позволяет использовать другие поисковые либы + поддерживает индексы в базе;
- Имеет средства по управлению SSL. Если на стороне веб-сервера не реализовано, то можно так, подключаешь let's encrypt на этапе развёртывания контейнера и вперёд;
- Позволяет использовать веб-аналитику, типа YaMetrika;
- Другие, небольшие, но доставляющие приятность, функции.
Есть и дурацкие особенности. Например:
- Своя, нетипичная структура каталогов и баги, связанные с этим. Не получится просто взять из репозитория файл с документами и отрендерить их, придётся потанцевать с бубном. К тому же при загрузке файлов в репу через wikijs, создаётся другая структура, неведомая, непонятная, несуществующая. Так, например, при выборе файла в качестве фона страницы авторизации видим такое:
Причём, например, каталог 666-test не существует ни в локальном репозитории на хостинге, ни в удалённом репозитории. Очистка кэша не помогает и как это лечить - ХЗ. Но с этим +- можно жить и со временем это перестаёт резать глаза и мозг.
Сразу хочу отметить, что это не инструкция по линукс, поэтому базовые шаги по настройке сервера, пользователей, установке git и созданию нужных каталогов на машине я пропускаю.
¶ Шаг 1. Создание конфига
В удобном месте создаём каталог для контейнера с wikijs. В моём случае это:
/home/fovendor/docker
Создаём в этом каталоге конфигурационный файл: docker-compose.yml, заполняем его содержимым из образа на докер хабе. Порт и таймзона настраиваются ситуативно. PUID и PGID вводятся в соответствии с выводом команды id. У меня вывод такой:
uid=1000(fovendor) gid=1000(fovendor) groups=1000(fovendor),27(sudo),33(www-data),998(docker)
В моём случае содержимое docker-compose такое:
version: "3"
services:
wikijs:
image: lscr.io/linuxserver/wikijs:latest
container_name: wikijs
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Amsterdam
- DB_TYPE=sqlite #optional
- DB_HOST= #optional
- DB_PORT= #optional
- DB_NAME= #optional
- DB_USER= #optional
- DB_PASS= #optional
volumes:
- ./config:/config
- ./data:/data
- ~/.ssh/id_rsa:/app/ssh/id_rsa:ro
ports:
- 9190:3000
restart: unless-stopped
¶ Шаг 2. Установка Docker
Я устанавливаю докер с помощью sh-скрипта, который предоставляет дополнительные фичи и инструменты для установки. Получить скрипт можно курлом отсюда. После скачивания скрипта нужно сделать файл исполняемым и запустить установку командой:
chmod +x install_docker_nproxyman.sh
Состав установки (остальное не устанавливаем):
- Docker-CE;
- Docker-Compose;
- Portainer.
Выбираем полную установку "Full Portainer-CE (Web GUI)"
Дождаться окончания установки.
¶ Шаг 3. Запуск Portainer
Для запуска Web GUI инструмента по управлению контейнерами (чтобы ручками команды не вводить и логи в шелле не смотреть) надо перейти на локальный сайт и создать там пользователя. Ссылка - это IP-адрес хостинга и порт, на который прицелен Portainer. В моём случае это такая ссылка http://193.38.54.183:9000/#!/init/admin.
Создаём пользователя-админа и логинимся в системе. Тут в разделе local будет всё необходимое окружение.
¶ Шаг 4. Установка wikijs
Чтобы установить Wikijs через образ Docker, нужно в каталоге /home/fovendor/docker выполнить команду docker-compose up -d. Важно не забывать параметр -d, иначе контейнер убьётся после того, как текущая сессия контейнера в шелле закроется после установки.
По окончанию установки контейнер появится в панели управления Portainer: local -> containers -> wikijs и можно будет там просмотреть логи. Надо чтобы в логах было так:
Видно, что сервер wikijs работает. Чтобы удобно было переходить на сайт, нужно создать переменную с IP-адресом хоста в разделе Environments -> Add environment:
После сохранения переменной можно перейти на сайт по адресу IP:port и перейти к настройке. Нужно:
- Ввести почту админа (это будет логин);
- Пароль;
- Домен, на который будет прицелен сайт. В моём случае это https://wiki.ethermemory.ru
Важно! На конце url не ставится знак слеша
/
Теперь можно залогиниться.
¶ Шаг 5. Настройка веб-сервера
Я использую Nginx. Предполагается, что он уже установлен.
-
Создать конфиг
sudo nano /etc/nginx/sites-available/домен; -
Наполнить содержимым (заменить
yourdomain.comиwww.yourdomain.com):
server {
listen 80;
server_name yourdomain.com www.yourdomain.com;
root /path/to/your/website/files;
index index.html index.htm;
location / {
try_files $uri $uri/ =404;
}
}
- Создать символическую ссылку (заменить
yourdomain.com):
sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
- Для получения бесплатных SSL-сертификатов от Let's Encrypt:
sudo apt update
sudo apt install certbot python3-certbot-nginx
- Зупустить скрипт на получение (регистрацию) ssl для домена (заменить
yourdomain.com):
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
Важно! Для одного домена можно зарегистрировать и получить только один домен в сутки! Не пытайтесь выполнить команду второй раз, если в первый всё сработало. В ином случае только через сутки можно настроить ssl.
- Автоматическое обновление сертификата:
sudo crontab -e
# для обновления каждый день в 3 утра по таймзоне из конфига docker-compose
0 3 * * * /usr/bin/certbot renew --quiet
Время от времени Let's Encrypt будет направлять письма подобного содержания:
Так как настроено автоматическое обновление сертификатов, то бояться нечего, но я бы проверял, не протух ли сертик при получении такого письма (мало ли, не отработал cron и всё, не будет https). Проверить можно такой командой для обоих доменов:
openssl s_client -connect docs.ethermemory.ru:443 -servername docs.ethermemory.ru | openssl x509 -noout -dates
Вывод должен быть примерно таким:
- Проверка на наличие nginx в systemd
Чтобы веб-сервер стартовал вместе с системой после перезагрузки, надо его включить в systemd. По идее должен стартовать сам, но, чтобы удостовериться, выполняем:
sudo systemctl enable nginx
- Перезапуск nginx
После всего нужно перезапустить сервис Nginx командой:
sudo systemctl reload nginx
¶ Шаг 6. Настройка интеграции с Git
Встроенная система подключения к git работает, но инструкций много и от раза к разу, видимо, из-за положения звёзд что-то не работает и синхронизация не отрабатывает. Ниже скрины, как точно работает:
В репозитории, в настройках профиля, надо зарегистрировать свой публичный ssh-ключ id-rsa:
Внутри контейнера находится приватный ключ тут:
После изменения каждого поля надо сохранять настройки. Админка странно сохраняет изменения и иногда она сохраняет, но не сохраняет и надо проверять всё.
В конце, когда синхронизация заработала, нужно получить файлы удалённого репозитория. Перед выполнением рекомендую открыть логи контейнера wikijs в Portainer и смотреть глазками, когда выполнение первой команды закончится. На сайте может вернуться ошибка о том, что что-то сломалось в процессе загрузки файлов из удалённого репозитория, но это, часто, обман и надо смотреть, что в логах.
Только после того, как Import Everything закончилась успешно, можно запустить Forse Sync и тоже смотреть логи.
