Вступ¶
Є кілька способів запустити копію 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