Установка и настройка 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 и работать как есть. Действие, описанное в данном разделе, стоит выполнить, если:

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

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

Устанавливаем и настраиваем 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

Для систем на базе DEB (Debian, Ubuntu, Astra)

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

apt install nginx

Если в нашей системе используется брандмауэр, разрешим порт 80:

iptables -I INPUT -p tcp --dport 80 -j ACCEPT

Для сохранения правила используем iptables-persistent:

apt install iptables-persistent

netfilter-persistent save

Добавим виртуальный домен в nginx. Для этого создаем файл:

vi /etc/nginx/sites-enabled/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

# DevOps # Linux # Серверы
Дмитрий Моск — частный мастер
Была ли полезна вам эта инструкция?

Да            Нет