Є кілька способів запустити копію mkdocs, щоб точно побачити, як виглядатиме ваш документ Rocky Linux після об’єднання в живу систему. Цей документ стосується використання контейнера LXD на вашій локальній робочій станції для відокремлення коду Python у mkdocs від інших проектів, над якими ви можете працювати.
Рекомендується зберігати проекти окремо, щоб уникнути проблем із кодом робочої станції.
Комфортно користуватися інструментами для редагування, SSH і синхронізації або готовий слідкувати за цим і вчитися
Довідка про LXD – тут є довгий документ про створення та використання LXD на сервері, але ви будете використовувати лише базову інсталяцію на нашій робочій станції Linux
Використання lsyncd для дзеркального відображення файлів. Перегляньте документацію про це тут
Вам знадобляться відкриті ключі, згенеровані для вашого користувача та користувача «root» на локальній робочій станції за допомогою цього документа
Наш інтерфейс мосту працює на 10.56.233.1, а наш контейнер працює на 10.56.233.189 у наших прикладах. Однак ваші IP-адреси для моста та контейнера будуть різними.
"youruser" у цьому документі представляє ваш ідентифікатор користувача
Припускається, що ви вже розробляєте документацію за допомогою клону сховища документації на вашій робочій станції
Наш перший крок — створити контейнер LXD. Використовувати типові параметри контейнера (інтерфейс мосту) тут цілком нормально.
Ви додасте контейнер Rocky до нашої робочої станції для mkdocs. Просто назвіть його "mkdocs":
lxc launch images:rockylinux/8 mkdocs
Контейнер повинен бути проксі. За замовчуванням, коли mkdocs serve запускається, він працює на 127.0.0.1:8000. Це добре, коли він знаходиться на вашій локальній робочій станції без контейнера. Однак, якщо він знаходиться в контейнері LXD на вашій локальній робочій станції, вам потрібно налаштувати контейнер із проксі-портом. Зробіть це за допомогою:
У рядку вище «mkdocs» — це ім’я нашого контейнера, «mkdocsport» — довільне ім’я, яке ви надаєте проксі-порту, тип — «proxy», і ви слухаєте всі інтерфейси TCP на порту 8000 і підключаєтеся до localhost для цього контейнера на порту 8000.
Примітка
Якщо ви запускаєте екземпляр lxd на іншій машині у вашій мережі, не забудьте переконатися, що порт 8000 відкритий у брандмауері.
Поточний requirements.txt потребуватиме новішої версії Python, ніж та, яка встановлена за замовчуванням у Rocky Linux 8.5 або 8.6. Щоб мати можливість інсталювати всі інші залежності, виконайте такі дії:
Вам потрібно встановити пароль для нашого користувача root, а потім додати нашого користувача (користувача, якого ви використовуєте на своїй локальній машині) до списку sudoers. На даний момент ви є «root» користувачем. Щоб змінити пароль, введіть:
passwd
Встановіть надійний пароль, який ви запам'ятаєте.
Далі додайте свого користувача та встановіть пароль:
adduser youruser
passwd youruser
Додайте свого користувача до групи sudoers:
usermod -aG wheel youruser
Ви повинні мати можливість підключитися до контейнера за протоколом 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:
Вам потрібно клонувати два репозиторії, але не потрібно додавати віддалені git. У сховищі документації тут відображатиметься лише поточна документація (віддзеркалена з вашої робочої станції) і документи.
Репозиторій rockylinux.org призначений для запуску mkdocs serve і використовуватиме дзеркало як джерело. Виконайте всі ці кроки від імені користувача без права root. Якщо ви не можете клонувати репозиторії як свій ідентифікатор користувача, то Є проблема з вашою ідентичністю, що стосується git, і ви потрібно переглянути кілька останніх кроків для повторного створення вашого ключового середовища (вище).
Встановлення необхідних плагінів виконується за допомогою pip3 і файлу «requirements.txt» у каталозі docs.rockylinux.org. Хоча цей процес буде суперечити вам щодо використання користувача root для запису змін до системних каталогів, ви повинні запустити його як root.
Ви можете зробити це за допомогою sudo тут.
Перейти в каталог:
cd docs.rockylinux.org
Потім запустіть:
sudo pip3 install -r requirements.txt
Далі ви повинні налаштувати mkdocs з додатковим каталогом. 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):
Ви майже готові, якщо побачили документацію у веб-переглядачі. Останнім кроком є синхронізація документації у вашому контейнері з документацією на локальній робочій станції.
Як зазначено вище, ви робите це тут за допомогою lsyncd.
Встановлення lsyncd відрізняється залежно від вашої версії Linux. Цей документ описує способи його встановлення на Rocky Linux і з джерела. Якщо ви використовуєте інші типи Linux (Ubuntu, наприклад), вони зазвичай мають власні пакети, але мають нюанси.
Ubuntu, наприклад, називає файл конфігурації по-різному. Просто майте на увазі, що якщо ви використовуєте інший тип робочої станції Linux, відмінний від Rocky Linux, і не бажаєте встановлювати його з вихідного коду, ймовірно, для вашої платформи є доступні пакунки.
Наразі ми припускаємо, що ви використовуєте робочу станцію Rocky Linux і використовуєте метод встановлення RPM із включеного документа.
Вам також потрібно створити файл виключення, навіть якщо в цьому випадку ви нічого не виключаєте:
touch /etc/lsyncd.exclude
Нарешті, вам потрібно створити файл конфігурації. У цьому прикладі ми використовуємо vi як наш редактор, але ви можете використовувати будь-який редактор, який вам зручно:
vi /etc/lsyncd.conf
Потім помістіть цей вміст у цей файл і збережіть його. Обов’язково замініть «youruser» на фактичного користувача, а IP-адресу — на власну IP-адресу контейнера:
Коли ви зараз працюєте над документацією вашої робочої станції, будь то git pull чи гілка, яку ви створюєте, щоб створити документ (як цей!), ви побачите, як зміни з’являться у вашій документації в контейнері , і mkdocs serve покаже вам вміст у вашому веб-переглядачі.
Рекомендована практика полягає в тому, що весь Python має працювати окремо від будь-якого іншого коду, який ви можете розробити. Контейнери LXD можуть зробити це простіше. Спробуйте цей метод і перевірте, чи він вам підходить.