Improve wording in README

kachkaev · Oct 3, 2020 · c63b43f · c63b43f
1 parent 8787387
commit c63b43f
Showing 1 changed file with 57 additions and 36 deletions.
diff --git 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 <<EOF >/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.  Зайти на на страницу <https://ru.wikipedia.org/wiki/Служебная:Экспорт>
 
@@ -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`