Вступ¶

Є кілька способів запустити копію mkdocs, щоб точно побачити, як виглядатиме ваш документ Rocky Linux після об’єднання в живу систему. Цей документ стосується використання контейнера LXD на вашій локальній робочій станції для відокремлення коду Python у mkdocs від інших проектів, над якими ви можете працювати.

Рекомендується зберігати проекти окремо, щоб уникнути проблем із кодом робочої станції.

Це також партнерський документ для версії Docker тут.

Передумови та припущення¶

Знайомство та комфорт роботи з командним рядком
Комфортно користуватися інструментами для редагування, SSH і синхронізації або готовий слідкувати за цим і вчитися
Довідка про LXD – тут є довгий документ про створення та використання LXD на сервері, але ви будете використовувати лише базову інсталяцію на нашій робочій станції Linux
Використання lsyncd для дзеркального відображення файлів. Перегляньте документацію про це тут
Вам знадобляться відкриті ключі, згенеровані для вашого користувача та користувача «root» на локальній робочій станції за допомогою цього документа
Наш інтерфейс мосту працює на 10.56.233.1, а наш контейнер працює на 10.56.233.189 у наших прикладах. Однак ваші IP-адреси для моста та контейнера будуть різними.
"youruser" у цьому документі представляє ваш ідентифікатор користувача
Припускається, що ви вже розробляєте документацію за допомогою клону сховища документації на вашій робочій станції

Контейнер `mkdocs`¶

Створіть контейнер¶

Наш перший крок — створити контейнер LXD. Використовувати типові параметри контейнера (інтерфейс мосту) тут цілком нормально.

Ви додасте контейнер Rocky до нашої робочої станції для mkdocs. Просто назвіть його "mkdocs":

lxc launch images:rockylinux/8 mkdocs

Контейнер повинен бути проксі. За замовчуванням, коли mkdocs serve запускається, він працює на 127.0.0.1:8000. Це добре, коли він знаходиться на вашій локальній робочій станції без контейнера. Однак, якщо він знаходиться в контейнері LXD на вашій локальній робочій станції, вам потрібно налаштувати контейнер із проксі-портом. Зробіть це за допомогою:

lxc config device add mkdocs mkdocsport proxy listen=tcp:0.0.0.0:8000 connect=tcp:127.0.0.1:8000

У рядку вище «mkdocs» — це ім’я нашого контейнера, «mkdocsport» — довільне ім’я, яке ви надаєте проксі-порту, тип — «proxy», і ви слухаєте всі інтерфейси TCP на порту 8000 і підключаєтеся до localhost для цього контейнера на порту 8000.

Примітка

Якщо ви запускаєте екземпляр lxd на іншій машині у вашій мережі, не забудьте переконатися, що порт 8000 відкритий у брандмауері.

Встановлення пакетів¶

Спочатку зайдіть в контейнер з:

lxc exec mkdocs bash

Зміни у requirements.txt для 8.x

Поточний requirements.txt потребуватиме новішої версії Python, ніж та, яка встановлена за замовчуванням у Rocky Linux 8.5 або 8.6. Щоб мати можливість інсталювати всі інші залежності, виконайте такі дії:

sudo dnf module enable python38
sudo dnf install python38

Якщо ви використовуєте Rocky Linux 8.x, використовуйте наступне для встановлення пакета:

dnf install git openssh-server rsync

НЕ встановлюйте python3-pip

Для Rocky Linux 9.x вам знадобиться кілька пакетів (дивіться «Зміни в requirements.txt для 8.x» для встановлення пакета 8.x!):

dnf install git openssh-server python3-pip rsync

Після встановлення вам потрібно ввімкнути та запустити sshd:

systemctl enable --now sshd

Користувачі контейнерів¶

Вам потрібно встановити пароль для нашого користувача root, а потім додати нашого користувача (користувача, якого ви використовуєте на своїй локальній машині) до списку sudoers. На даний момент ви є «root» користувачем. Щоб змінити пароль, введіть:

passwd

Встановіть надійний пароль, який ви запам'ятаєте.

Далі додайте свого користувача та встановіть пароль:

adduser youruser
passwd youruser

Додайте свого користувача до групи sudoers:

usermod -aG wheel youruser

Ви повинні мати можливість підключитися до контейнера за протоколом SSH із користувачем root або своїм користувачем із робочої станції та ввести пароль. Перш ніж продовжити, переконайтеся, що ви можете це зробити.

SSH для root і вашого користувача¶

У цій процедурі root-користувач (як мінімум) повинен мати можливість входити в контейнер через SSH без введення пароля; це через процес lsyncd, який ви запроваджуватимете. Тут припускається, що ви можете використовувати sudo для користувача root на вашій локальній робочій станції:

sudo -s

Також припускається, що користувач root має ключ id_rsa.pub у каталозі ./ssh. Якщо ні, створіть його за допомогою цієї процедури:

ls -al .ssh/
drwx------  2 root root 4096 Feb 25 08:06 .
drwx------ 14 root root 4096 Feb 25 08:10 ..
-rw-------  1 root root 2610 Feb 14  2021 id_rsa
-rw-r--r--  1 root root  572 Feb 14  2021 id_rsa.pub
-rw-r--r--  1 root root  222 Feb 25 08:06 known_hosts

Щоб отримати доступ SSH до нашого контейнера без необхідності вводити пароль, за умови наявності ключа id_rsa.pub, як це робиться вище, просто запустіть:

ssh-copy-id root@10.56.233.189

Однак для нашого користувача вам потрібен увесь каталог .ssh/, скопійований у наш контейнер. Ви збережете все те саме для цього користувача, щоб наш доступ до GitHub через SSH був однаковим.

Щоб скопіювати все до нашого контейнера, вам просто потрібно зробити це як ваш користувач, а не sudo:

scp -r .ssh/ youruser@10.56.233.189:/home/youruser/

Далі введіть SSH у контейнер як ваш користувач:

ssh -l youruser 10.56.233.189

Вам потрібно зробити речі ідентичними. Ви робите це за допомогою ssh-add. Для цього переконайтеся, що у вас є ssh-agent:

eval "$(ssh-agent)"
ssh-add

Клонування сховищ¶

Вам потрібно клонувати два репозиторії, але не потрібно додавати віддалені git. У сховищі документації тут відображатиметься лише поточна документація (віддзеркалена з вашої робочої станції) і документи.

Репозиторій rockylinux.org призначений для запуску mkdocs serve і використовуватиме дзеркало як джерело. Виконайте всі ці кроки від імені користувача без права root. Якщо ви не можете клонувати репозиторії як свій ідентифікатор користувача, то Є проблема з вашою ідентичністю, що стосується git, і ви потрібно переглянути кілька останніх кроків для повторного створення вашого ключового середовища (вище).

Спочатку клонуйте документацію:

git clone git@github.com:rocky-linux/documentation.git

Далі клонуйте docs.rockylinux.org:

git clone git@github.com:rocky-linux/docs.rockylinux.org.git

Якщо ви бачите помилки, поверніться до наведених вище кроків і переконайтеся, що всі вони правильні, перш ніж продовжити.

Налаштування `mkdocs`¶

Встановлення необхідних плагінів виконується за допомогою pip3 і файлу «requirements.txt» у каталозі docs.rockylinux.org. Хоча цей процес буде суперечити вам щодо використання користувача root для запису змін до системних каталогів, ви повинні запустити його як root.

Ви можете зробити це за допомогою sudo тут.

Перейти в каталог:

cd docs.rockylinux.org

Потім запустіть:

sudo pip3 install -r requirements.txt

Далі ви повинні налаштувати mkdocs з додатковим каталогом. mkdocs вимагає створення каталогу документів, а потім каталогу документації/документів, пов’язаного з ним. Зробіть це за допомогою:

mkdir docs
cd docs
ln -s ../../documentation/docs

Тестування `mkdocs`¶

Тепер, коли ви налаштували mkdocs, спробуйте запустити сервер. Пам’ятайте, що цей процес буде стверджувати, що це схоже на виробництво. Це не так, тому ігноруйте попередження. Запустіть mkdocs serve за допомогою:

mkdocs serve -a 0.0.0.0:8000

У консолі ви побачите щось подібне:

INFO     -  Building documentation...
WARNING  -  Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a
            proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please
            use a third party production-ready server instead.
INFO     -  Adding 'sv' to the 'plugins.search.lang' option
INFO     -  Adding 'it' to the 'plugins.search.lang' option
INFO     -  Adding 'es' to the 'plugins.search.lang' option
INFO     -  Adding 'ja' to the 'plugins.search.lang' option
INFO     -  Adding 'fr' to the 'plugins.search.lang' option
INFO     -  Adding 'pt' to the 'plugins.search.lang' option
WARNING  -  Language 'zh' is not supported by lunr.js, not setting it in the 'plugins.search.lang' option
INFO     -  Adding 'de' to the 'plugins.search.lang' option
INFO     -  Building en documentation
INFO     -  Building de documentation
INFO     -  Building fr documentation
INFO     -  Building es documentation
INFO     -  Building it documentation
INFO     -  Building ja documentation
INFO     -  Building zh documentation
INFO     -  Building sv documentation
INFO     -  Building pt documentation
INFO     -  [14:12:56] Reloading browsers

А тепер момент істини! Якщо ви зробили все правильно, ви зможете відкрити веб-браузер і перейти до IP-адреси свого контейнера на порту :8000 і переглянути сайт документації.

У нашому прикладі введіть наступне в адресу веб-переглядача (ПРИМІТКА Щоб уникнути непрацюючих URL-адрес, IP-адресу тут змінено на «ip-адресу вашого-сервера». Потрібно просто підставити в IP):

http://your-server-ip:8000

`lsyncd`¶

Ви майже готові, якщо побачили документацію у веб-переглядачі. Останнім кроком є синхронізація документації у вашому контейнері з документацією на локальній робочій станції.

Як зазначено вище, ви робите це тут за допомогою lsyncd.

Встановлення lsyncd відрізняється залежно від вашої версії Linux. Цей документ описує способи його встановлення на Rocky Linux і з джерела. Якщо ви використовуєте інші типи Linux (Ubuntu, наприклад), вони зазвичай мають власні пакети, але мають нюанси.

Ubuntu, наприклад, називає файл конфігурації по-різному. Просто майте на увазі, що якщо ви використовуєте інший тип робочої станції Linux, відмінний від Rocky Linux, і не бажаєте встановлювати його з вихідного коду, ймовірно, для вашої платформи є доступні пакунки.

Наразі ми припускаємо, що ви використовуєте робочу станцію Rocky Linux і використовуєте метод встановлення RPM із включеного документа.

Конфігурація¶

Примітка

Користувач root повинен запускати демон, тому ви повинні бути root для створення файлів конфігурації та журналів. Для цього ми припускаємо sudo -s.

Для запису lsyncd потрібно мати деякі файли журналу:

touch /var/log/lsyncd-status.log
touch /var/log/lsyncd.log

Вам також потрібно створити файл виключення, навіть якщо в цьому випадку ви нічого не виключаєте:

touch /etc/lsyncd.exclude

Нарешті, вам потрібно створити файл конфігурації. У цьому прикладі ми використовуємо vi як наш редактор, але ви можете використовувати будь-який редактор, який вам зручно:

vi /etc/lsyncd.conf

Потім помістіть цей вміст у цей файл і збережіть його. Обов’язково замініть «youruser» на фактичного користувача, а IP-адресу — на власну IP-адресу контейнера:

settings {
   logfile = "/var/log/lsyncd.log",
   statusFile = "/var/log/lsyncd-status.log",
   statusInterval = 20,
   maxProcesses = 1
   }

sync {
   default.rsyncssh,
   source="/home/youruser/documentation",
   host="root@10.56.233.189",
   excludeFrom="/etc/lsyncd.exclude",
   targetdir="/home/youruser/documentation",
   rsync = {
     archive = true,
     compress = false,
     whole_file = false
   },
   ssh = {
     port = 22
   }
}

Припускаючи, що ви ввімкнули lsyncd під час встановлення, на цьому етапі вам потрібно просто запустити або перезапустити процес:

systemctl restart lsyncd

Щоб переконатися, що все працює, перевірте журнали, зокрема lsyncd.log, який має показати вам щось на кшталт цього, якщо все запущено правильно:

Fri Feb 25 08:10:16 2022 Normal: --- Startup, daemonizing ---
Fri Feb 25 08:10:16 2022 Normal: recursive startup rsync: /home/youruser/documentation/ -> root@10.56.233.189:/home/youruser/documentation/
Fri Feb 25 08:10:41 2022 Normal: Startup of "/home/youruser/documentation/" finished: 0
Fri Feb 25 08:15:14 2022 Normal: Calling rsync with filter-list of new/modified files/dirs

Висновок¶

Коли ви зараз працюєте над документацією вашої робочої станції, будь то git pull чи гілка, яку ви створюєте, щоб створити документ (як цей!), ви побачите, як зміни з’являться у вашій документації в контейнері , і mkdocs serve покаже вам вміст у вашому веб-переглядачі.

Рекомендована практика полягає в тому, що весь Python має працювати окремо від будь-якого іншого коду, який ви можете розробити. Контейнери LXD можуть зробити це простіше. Спробуйте цей метод і перевірте, чи він вам підходить.

Author: Steven Spencer

Contributors: Ezequiel Bruni, Ganna Zhyrnova