Метод Incus

примітка

Хоча цей метод все ще працює для LXD, автор надає перевагу Incus. Причина полягає в тому, що з точки зору розробки, Incus, здається, випереджає LXD, враховуючи доступні зображення. Станом на вересень 2025 року на Incus є образи для Rocky Linux 10 та інших образів RHEL rebuild 10. Образи LXD наразі містять лише дев'ять збірок. Це може бути пов'язано зі зміною ліцензування, оголошеною керівником проекту Linux Containers Стефаном Грабером ще у грудні 2023 року.

Крім того, ця процедура все ще працює з поточною версією документації. Якщо документ створено або відредаговано в будь-якій з гілок версій (main, rocky-9 та rocky-8), документ, синхронізований з контейнером, відображатиме правильний вміст. Це означає, що ви можете продовжувати використовувати цю процедуру як є. Включено деякі додаткові примітки, важливі для керування версіями.

Підказка

Якщо ви використовуєте Rocky Linux 10 як робочу станцію, пам’ятайте, що на момент переробки цього документа lsyncd недоступний з EPEL. Вам потрібно буде використовувати метод встановлення з вихідного коду.

Вступ¶

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

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

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

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

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

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

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

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

incus launch images:rockylinux/10 mkdocs

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

incus 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.

Примітка

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

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

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

incus shell mkdocs bash

Для Rocky Linux 10 вам знадобиться кілька пакетів:

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/ у контейнер. Ви збережете все незмінним для цього користувача, щоб ваш SSH-доступ до GitHub залишався незмінним.

Щоб скопіювати все до контейнера, вам просто потрібно зробити це від імені користувача, не 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 вимагає створення каталогу docs, а потім каталогу documentation/docs, на який посилання розміщено нижче. Зробіть це за допомогою:

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 за допомогою RPM-пакета з EPEL (Додаткові пакети для Enterprise Linux) та з вихідного коду. Якщо ви використовуєте інші дистрибутиви Linux (наприклад, Ubuntu), вони зазвичай мають власні пакети, хоча й з нюансами.

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

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

Примітка

На момент написання цієї статті, lsyncd недоступний з EPEL для Rocky Linux 10. Вам потрібно буде використовувати метод встановлення з вихідного коду, якщо це версія вашої робочої станції.

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

Примітка

Користувач 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

Примітки щодо версій¶

Вам потрібен клон репозиторію документації Rocky Linux. Ця частина важлива, тому що якщо ви натомість клонували власний форк репозиторію, то ваша можливість git checkout гілок rocky-8 та rocky-9 буде недоступна. Доступна буде лише головна гілка.

Налаштування робочої станції GitHub¶

Ці кроки не для вашого контейнера, а для копії документації вашої робочої станції:

Клонуйте репозиторій документації Rocky Linux:
```
git clone git@github.com:rocky-linux/documentation.git
```
Ім'я git remote буде "upstream", а не "origin". Перевірте ім'я віддаленого пристрою за допомогою:
```
git remote -v
```
Відразу після клонування це показує:
```
origin git@github.com:rocky-linux/documentation.git (fetch)
origin git@github.com:rocky-linux/documentation.git (push)
```
Перейменуйте за допомогою:
```
git remote rename origin upstream
```
Знову запустіть git remote -v, і ви побачите:
```
upstream git@github.com:rocky-linux/documentation.git (fetch)
upstream git@github.com:rocky-linux/documentation.git (push)
```

Додайте свою гілку як віддалену з назвою "origin". Замініть своє фактичне ім'я користувача GitHub:

git remote add origin git@github.com:[your-github-user-name]/documentation.git

Знову запустіть git remote -v, і ви побачите:

origin git@github.com:[your-github-user-name]/documentation.git (fetch)
origin git@github.com:[your-github-user-name]/documentation.git (push)
upstream git@github.com:rocky-linux/documentation.git (fetch)
upstream git@github.com:rocky-linux/documentation.git (push)

Вам потрібно заповнити ваш fork гілками версій (окрім main). Гілка main наразі містить інформацію про версію 10. Ви хочете об'єднати свою гілку з гілками rocky-8 та rocky-9, щоб мати змогу редагувати документи в цих старіших версіях. Перший крок — виконати команду git checkout для цих імен гілок:
```
git checkout rocky-8
```
Коли ви це зробите вперше, ви побачите:
```
branch 'rocky-8' set up to track 'upstream/rocky-8'.
Switched to a new branch 'rocky-8'
```
Далі:
```
git push origin rocky-8
```
Це діє так, ніби створює новий пул-реквест, але коли ви перевірите вміст вашої гілки fork, ви побачите, що rocky-8 тепер є однією з гілок.

Повторіть ці кроки з гілкою rocky-9.

Як це стосується цієї процедури¶

Після створення гілок, якщо ви хочете редагувати README.md лише для rocky-9, вам потрібно створити нову гілку на основі гілки версії rocky-9:

git checkout -b fixes_for_rocky9_readme rocky-9

Потім відредагуйте документ звичайним способом. Під час збереження вашої роботи ваші документи-контейнери оновлюватимуться, і запуск команди mkdocs serve, як описано в цьому документі, відобразить цей вміст.

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

Висновок¶

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

Author: Steven Spencer

Contributors: Ezequiel Bruni, Ganna Zhyrnova

Метод Incus

Вступ¶

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

Контейнер mkdocs¶

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

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

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

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

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

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

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

lsyncd¶

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

Примітки щодо версій¶

Налаштування робочої станції GitHub¶

Як це стосується цієї процедури¶

Висновок¶

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

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

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

`lsyncd`¶