Categories: Шпаргалки

Установка и настройка Docusaurus на Linux

Docusaurus — проект для создания сайтов и документации на основе файлов md (Markdown), js (Javascript) и некоторых других. Мы рассмотрим процесс его установки и запуска в качестве сервиса для постоянного доступа к документации. Работать будем на системе Linux.

Установка nodejs
На системы RPM
На системы DEB
Установка Docusaurus
Настройка systemd для автозапуска
Проксирование запросов с помощью NGINX
Настройка для RPM
Настройка для DEB

В итоге, мы получим:

установленный nodejs с необходимой для работы Docusaurus версией.
созданный проект Docusaurus на основе классического шаблона.
автозапуск сервиса с использованием юнита systemd.
проксирование http-запросов с помощью NGINX.

Приступим.

Установка Nodejs

Проект Docusaurus разработан с использованием Javascript и запускается на системе с установленным Nodejs. На странице с официальной документацией смотрим, какая версия последней нам нужна. На момент обновления инструкции это была версия 18.

В зависимости от дистрибутива Linux, действия по установке будут различаться. Рассмотрим два варианта.

* подробная информация по установке NodeJS различных версий размещена на Github .

Установка Nodejs на системы RPM (Rocky, РЕД ОС, CentOS)

Устанавливаем репозиторий:

yum install https://rpm.nodesource.com/pub_18.x/nodistro/repo/nodesource-release-nodistro-1.noarch.rpm

Для RPM систем на базе RHEL 8 и выше отключаем модуль репозитория nodejs:

dnf module disable nodejs

Устанавливаем nodejs:

yum install nodejs

Проверяем:

node —version

Мы должны увидеть что-то на подобие:

v18.18.2

Установка Nodejs на системы DEB (Debian, Ubuntu, Astra)

Установим необходимые утилиты:

apt update

apt install ca-certificates curl gnupg

* где:

ca-certificates — набор корневых сертификатов.
curl — утилита отправки запросов, в частности, для загрузки файлов.
gnupg — для шифровки и дешифровки цифровых подписей.

Установим ключ репозитория:

mkdir -p /etc/apt/keyrings

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg —dearmor -o /etc/apt/keyrings/nodesource.gpg

Добавим репозиторий NodeJS для нужной версии приложения:

NODE_MAJOR=18

echo «deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main» | tee /etc/apt/sources.list.d/nodesource.list

Устанавливаем nodejs:

apt update

apt install nodejs

Проверяем:

node —version

Мы должны увидеть что-то на подобие:

v18.18.2

Установка и запуск Docusaurus

Создаем каталог, где хотим разместить портал, например:

mkdir /opt/docusaurus

Перейдем в него:

cd /opt/docusaurus

Убедимся, что у нас установлена свежая версия npm:

npm install npm -g

Создадим первый проект докузавтра:

npx create-docusaurus@latest mydoc classic

* за основу возьмем последнюю версию docusaurus, классический интерфейс. Наш проект назовем mydoc .

Подтверждаем:

Ok to proceed? (y) y

В итоге, мы должны увидеть:

…
Happy building awesome websites!

Перейдем в каталог созданного проекта и запустим его:

cd mydoc

npx docusaurus start —port 3000 —host 127.0.0.1

* данной командой мы запустим сервис на порту 3000 , который будет слушать запросы на локальной петле ( 127.0.0.1 ). Мы не станем разрешать сетевой доступ, так как планируем ниже рассказать о проксировании запросов через NGINX. Вы же можете указать опцию —host 0.0.0.0 , если хотите разрешить запросы на всех сетевых интерфейсах.

Мы должны увидеть что-то на подобие:

[INFO] Starting the development server…
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

Client
Compiled successfully in 1.17s

client (webpack 5.89.0) compiled successfully

Откроем еще одну консоль (локальную или по SSH) и выполним запрос к порталу:

curl 127.0.0.1:3000

Мы должны увидеть html-код. Пока этого достаточно.

Прерываем работу запущенного сервиса комбинацией CTRL + C .

Идем дальше.

Настройка автозапуска Docusaurus

Мы запустили вручную наше приложение — теперь настроим его автозапуск. Мы создадим юнит с @ — это позволит нам передавать имя проекта.

Создаем файл:

vi /etc/systemd/system/docusaurus@.service

[Unit]
Description=Docusaurus Service
After=network.target

[Service]
Type=simple
EnvironmentFile=/opt/docusaurus/systemd.%i.conf
ExecStart=/usr/bin/npx docusaurus start —port ${DOC_PORT} —host ${DOC_HOST}
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
WorkingDirectory=/opt/docusaurus/%i

[Install]
WantedBy=multi-user.target

* обратите внимание на %i — это переменная, которой мы будем передавать имя нашего проекта, которое соответствует названию файла, где описываются переменные окружения DOC_PORT и DOC_HOST .

Создаем файл с системными переменными:

vi /opt/docusaurus/systemd.mydoc.conf

DOC_PORT=3000
DOC_HOST=127.0.0.1

Разрешаем и запускаем наш проект:

systemctl enable docusaurus@mydoc —now

* снова повторимся. mydoc — имя проекта в нашем примере и ему соответствует каталог /opt/docusaurus/mydoc .

Посмотреть состояние службы можно командой:

systemctl status docusaurus@mydoc

После запуска ждем около 5 секунд и проверяем, что сервис слушает на нужном порту:

ss -tunlp | grep :3000

Снова проверяем, что сервис отвечает на http-запрос:

curl 127.0.0.1:3000

Если мы получили код html, то все работает. Идем дальше.

Настройка NGINX и доступ по сети

Спроксируем все наши запросы через веб-сервер NGINX. Мы настроим виртуальный домен mydoc.localnet , при обращении на который должен будет открыться наш портал документации. Это означает, что данный адрес должен разрешаться в IP-адрес. У вас это будет свое имя, которое должно быть либо добавлено на сервер DNS, либо разрешаться с помощью файла hosts.

При желании, можно не настраивать NGINX и работать как есть. Действие, описанное в данном разделе, стоит выполнить, если:

Мы хотим, чтобы URL-адреса были красивыми и удобными.
Необходима настройка TLS (https).
Нужна единая точка входа для контроля безопасности.
У нас будет много проектов, но мы не хотим открывать много портов для доступа к ним.

Возможно, у вас могут быть свои причины использовать обратный прокси.

Устанавливаем и настраиваем nginx. В зависимости от системы, наши действия будут сильно отличаться, поэтому рассмотрим их по отдельности.

Для систем на базе RPM RPM (Rocky, РЕД ОС, CentOS)

Устанавливаем nginx:

yum install nginx

Запустим сервис, разрешив его:

systemctl enable nginx —now

Настраиваем брандмауэр — разрешаем порт 80:

firewall-cmd —permanent —add-service=http

firewall-cmd —reload

Добавим виртуальный домен — создаем файл:

vi /etc/nginx/conf.d/mydoc.conf

server {
listen 80;
server_name mydoc.localnet;

location / {
proxy_pass http://127.0.0.1:3000/;
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}

* в данном примере мы все запросы, которые придут на сервер с обращением по URL mydoc.localnet будут обрабатываться данной конфигурацией и будут проксироваться на локальный сервер, порт 3000 .

Проверяем конфигурацию и перезапускаем nginx:

nginx -t && nginx -s reload

А также работу запроса:

curl mydoc.localnet