diff --git a/README.md b/README.md index 92c37f1..7f6f21a 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,12 @@ [Вики Горпроектов](https://city4people-wiki.ru) работает на [Медиавики](https://mediawiki.org) — том же движке, что и Википедия. Этот выбор определяет низкий порог входа для участников, а также задаёт понятные и проверенные правила для взаимодействия в сообществе. -Все технические компоненты вики имеют свободную лицензию и не требуют оплаты. -Если учитывать, что обслуживание ресурса осуществляется волонтёрами, платным остаётся только веб-хостинг. +Все технические компоненты вики имеют открытый исходный код и не требуют платных лицензий. +Если обслуживание ресурса осуществляется волонтёрами, платным остаётся только веб-хостинг. Движок настроен так, чтобы процесс редактирования содержимого мало чем отличался от Википедии. -Единственная существенная разница в настройке — Медиавики авторизация через Телеграм при помощи [виджета](https://core.telegram.org/widgets/login). -Благодаря этой интеграции участникам не приходится придумывать логины и пароли, а администраторам проще модерировать правки. +Единственная существенная разница в настройке Медиавики — [авторизация через Телеграм](https://core.telegram.org/widgets/login). +Благодаря этой интеграции участникам не приходится придумывать логины и пароли, а администраторам проще отслеживать и модерировать правки. Войти в вики может любой пользователь Телеграма при наличии имени пользователя в профиле. Существует техническая возможность варьировать доступ к страницам в зависимости от статуса человека в федеральной сети ГП — это требует дополнительной настройки. @@ -31,9 +31,11 @@ Песочница служит местом экспериментов как для системных администраторов, так и для участников. Перед тем, как выкатывать техническое обновление на основной экземпляр вики, оно пробуется в песочнице. -В результате этой работы инструкции по развёртыванию обновляются соответствующим образом. -При обновлении основного экземпляра вики системный администратор выполняет уже опробованные шаги. -Инструкции должны быть достаточно точными, чтобы оперативно пересоздать вики в случае серьёзной технической аварии. +В процессе этой работы инструкции в этом репозитории обновляются. +Таким образом, при технических изменениях в основном экземпляре вики системный администратор выполняет уже опробованные шаги. +Это уменьшает риск недоступности сайта или потери данных. + +Полнота инструкций должна позволить оперативно починить систему в случае серьёзной технической аварии. --- @@ -45,30 +47,31 @@ - [Исходники телеграм-бота](./telegram-bot), [скрипт для его контейнеризации](./github/workflow/docker.yml) и [хемл-чарт для развёртывания](./helm-charts/webapp-ingress) (в этом репозитории) - Образ контейнера для телеграм-бота [хранится на Гитхабе](https://github.com/kachkaev/city4people-wiki/packages/410942) и автоматически обновляется при создании нового [релиза](https://github.com/kachkaev/city4people-wiki/releases). - ---- +Образ контейнера для телеграм-бота [хранится на Гитхабе](https://github.com/kachkaev/city4people-wiki/packages) и автоматически обновляется при создании нового [релиза](https://github.com/kachkaev/city4people-wiki/releases). -Возможен перенос основной вики на другой домен (например, `wiki.city4people.ru`). -Это требует настройки `DNS` записей домена `city4people.ru`. - -## Разворачивание +## Развёртывание ### Требования к среде 1. Кластер на [Кубернетисе](https://kubernetes.io) - - Возможность создавать хранилища _(persistent volumes)_ в режиме `ReadWriteMany` + - ☑️ Возможность удовлетворять запросы на создания хранилищ _(persistent volume claims)_ в режиме `ReadWriteMany` Для каждого экземпляра вики рекомендуется выделять минимум 10 гигабайт для БД И 20 гигабайт для медиа-загрузок - - [Трафик](https://traefik.io) в качестве ингрес-контроллера с настроенным резолвером сертификатов [Летс-энкрипт](https://??) + - ☑️ [Трафик](https://traefik.io) в качестве ингрес-контроллера Если используется другой контроллер, от инструкций ниже придётся немного отступить -1. Локально установленные команды `kubectl` и `helm`, настроенный доступ к кластеру (`KUBECONFIG`) + - Автоматический резолвер сертификатов [Летс-энкрипт](https://letsencrypt.org) в ингрес-контроллере + +1. Локально установленные команды `kubectl` и `helm` -1. Доступ по `SSH` к хранилищам в кластере (для загрузки и обновления плагинов и других ресурсов Медиавики, не встроенных в чарт) +1. Настроенный доступ к кластеру (`KUBECONFIG`) с правом создавать ресурсы в пространстве имён `city4people-wiki` + +1. Доступ по `SSH` к хранилищам в кластере + + Требуется для загрузки и обновления ресурсов Медиавики (настройки, дополнительные расширения, и т. д.) 1. Доступ к реестру с образами контейнеров на Гитхабе @@ -83,9 +86,11 @@ ### Развёртывание Медиавики -- [README](https://hub.helm.sh/charts/bitnami/mediawiki) +Используется хелм-чарт, созданный компанией Битнами -- [values.yaml](https://github.com/bitnami/charts/blob/master/bitnami/mediawiki/values.yaml) +- [документация](https://hub.helm.sh/charts/bitnami/mediawiki) +- [исходники](https://github.com/bitnami/charts/tree/master/bitnami/mediawiki) +- [файл values.yaml](https://github.com/bitnami/charts/blob/master/bitnami/mediawiki/values.yaml) ```sh helm repo add bitnami https://charts.bitnami.com/bitnami @@ -96,6 +101,12 @@ MEDIAWIKI_NAME="Вики Горпроектов" # MARIADB_ROOTUSER_PASSWORD= # MEDIAWIKI_PASSWORD= +INSTANCE=sandbox +INSTANCE_HOST=sandbox.city4people-wiki.ru +MEDIAWIKI_NAME="Вики-песочница" +# MARIADB_ROOTUSER_PASSWORD= +# MEDIAWIKI_PASSWORD= + cat </tmp/values-for-webapp.yaml image: tag: 1.35.0-debian-10-r8 @@ -134,6 +145,11 @@ helm upgrade --namespace=city4people-wiki "${INSTANCE}-webapp" bitnami/mediawiki ### Настройка внешнего доступа к вики +В отдельном [хелм-чарте для ингреса](./helm-charts/webapp-ingress) используются [нестандартные ресурсы Кубернетиса](https://doc.traefik.io/traefik/v2.3/providers/kubernetes-crd/) _(Custom Resource Definitions)_. +Они помогают настроить перенаправления с поддомена `www`, заголовки `HTTP`-запросов и сжатие данных. + +Если вместо Трафика используется nginx или другой тип ингрес-контроллера, чарт придётся подправить. + ```sh INSTANCE=main INSTANCE_HOST=city4people-wiki.ru @@ -160,13 +176,13 @@ helm upgrade --namespace=city4people-wiki "${INSTANCE}-webapp-ingress" ./helm-ch ### Развёртывание Телеграм-бота -Авторизация через Телеграм требует наличия бота. -Этот бот должен быть привязан к домену сервера, на котором размещается [кнопка для входа](https://core.telegram.org/widgets/login). +[Авторизация через Телеграм](https://core.telegram.org/widgets/login) требует наличия бота. +Этот бот должен быть привязан к домену сервера, на котором размещена кнопка входа. Для создания бота следует отправить команду `/newbot` боту [@BotFather](https://t.me/BotFather). Привязка бота к домену настраивается там же. -Разворачивать сервер для бота строго говоря не обязательно, так как весь процесс авторизации проводит сам Телеграм. +Развёртывать сервер для бота строго говоря не обязательно, так как весь процесс авторизации проводит сам Телеграм. Работающий бот лишь отвечает на сообщения пользователей ссылкой на вики. ```sh @@ -209,17 +225,17 @@ helm upgrade --namespace=city4people-wiki "${INSTANCE}-telegram-bot" ./helm-char # helm uninstall --namespace=city4people-wiki "${INSTANCE}-telegram-bot" ``` -### Донастройка Медиавики после разворачивания +### Донастройка Медиавики после развёртывания ```sh MEDIAWIKI_PV_SSH_HOST=kachkaev--firstvds--city4people-wiki MEDIAWIKI_PV_PATH=/var/www/local-pvs/city4people-wiki-main-mediawiki ``` -#### Синхронизация настроек из этого репозитория +#### Синхронизация ресурсов Медиавики из этого репозитория Хранилище пода с Медиавики содержит файл `mediawiki/LocalSettings.php`. -После создания _нового_ экземпляра веб-приложения следует вручну добавить в него эти строчки +После создания _нового_ экземпляра веб-приложения следует вручну добавить в него эти две строчки: ```php // в начале файла @@ -234,17 +250,21 @@ import "./LocalSettingsDebug.php"; ```sh ## модуль для авторизации через Телеграм rsync --archive --delete --stats --human-readable custom-mediawiki-resources/extensions/TelegramAuth/ ${MEDIAWIKI_PV_SSH_HOST}:${MEDIAWIKI_PV_PATH}/mediawiki/extensions/TelegramAuth +``` +```sh ## Донастройка движка (LocalSettingsDebug.php и LocalSettingsTailoring.php) rsync --archive --stats --human-readable custom-mediawiki-resources/LocalSettings*.php ${MEDIAWIKI_PV_SSH_HOST}:${MEDIAWIKI_PV_PATH}/mediawiki/ +``` +```sh ## Логотипы rsync --archive --stats --human-readable visuals/main/mediawiki/*.png ${MEDIAWIKI_PV_SSH_HOST}:${MEDIAWIKI_PV_PATH}/mediawiki/images/ ``` #### Группа `ssotelegram` -Участникам, вошедшим через Телеграм, автоматически присваивается группа `ssotelegram` (`SSO` — _Single sign-on_). +Участникам, вошедшим через Телеграм, автоматически присваивается группа `ssotelegram` (_SSO – Single sign-on_). Это может упростить контроль [прав доступа](https://www.mediawiki.org/wiki/Manual:User_rights) в будущем. Чтобы группа `ssotelegram` отображалась на страницах вики по-русски, следует создать три служебные страницы: @@ -304,7 +324,7 @@ wget -c https://extdist.wmflabs.org/dist/skins/MinervaNeue-REL1_35-bb52d27.tar.g #### Шаблоны и стили После создания нового экземпляра вики следует импортировать шаблоны и стили из русской Википедии. -Действия ниже можно периодически повторять, чтобы получать обновлённые версии. +Действия ниже можно периодически повторять для обновления. 1. Зайти на на страницу @@ -320,9 +340,9 @@ wget -c https://extdist.wmflabs.org/dist/skins/MinervaNeue-REL1_35-bb52d27.tar.g 1. Поставить все три галочки - 1. Нажать «Экспортировать» и сохранить файл локально. + 1. Нажать «Экспортировать» и сохранить файл локально -1. Зайти на страницу `Служебная:Импорт` +1. Зайти на страницу `Служебная:Импорт` нужного экземпляра вики 1. Выбрать скаченный файл `xml` @@ -332,10 +352,11 @@ wget -c https://extdist.wmflabs.org/dist/skins/MinervaNeue-REL1_35-bb52d27.tar.g 1. Закомменировать стили главной страницы в `Mobile.css`, чтобы убрать серый фон -#### Настройка плагина для авторизации через Телеграм +#### Настройка расширения для авторизации через Телеграм Настройки расширения `TelegramAuth` включены в файл `LocalSettingsTailoring.php`. -В случае изменения токена перегенерировать его хэш поможет эта команда: +В случае изменения токена бота, его хэш придётся перегенерировать. +Поможет эта команда: ```sh # export TELEGRAM_BOT_TOKEN= @@ -350,9 +371,9 @@ node --eval 'console.log(require("crypto").createHash("sha256").update(process.e ### Хаки для песочницы -Чтобы песочница визуально отличалась от основной вики, следует добавить следующий код в начало двух страниц `Mediawiki:*.css` — фон станет жёлтым. +Чтобы песочница визуально отличалась от основной вики, следует добавить следующий код в начало двух страниц `MediaWiki:*.css` — фон станет жёлтым. -`Mediawiki:Common.css` (настольный режим) +`MediaWiki:Common.css` (настольный режим) ```css /* begin sandbox hacks */ @@ -385,7 +406,7 @@ body { /* end sandbox hacks */ ``` -`Mediawiki:Mobile.css` (мобильный режим) +`MediaWiki:Mobile.css` (мобильный режим) ```css /* begin sandbox hacks */ @@ -401,7 +422,7 @@ body { ## Заметки по Медиавики -### Важные служебные страницы +### Полезные служебные страницы - `MediaWiki:Sitenotice` - `Special:Version`