Установка и настройка генератора сайтов Docusaurus с сохранением в локальной системе контроля версий Gitlab и автоматической публикацией в Gitlab Pages

Данная инструкция предполагает что установка выполняется в локальной сети на виртуальную машину Ubuntu 20.04 (настройка ВМ выходит за рамки данной инструкции)

На виртуальной машине будут установлены:

  • Docker - в контейнере будет выполнятся генерация сайта Docusaurus
  • Gitlab CE - система контроля версий
  • Gitlab runners - необходим для запуска CI процесса

Дополнительно, для первичной иничиализации git репозитория будет развернут генератор сайтов Docusaurus.

Обновление Ubuntu 20.04

После "чистой" установки ОС необходимои обновить пакетную базу и выполнить установку дополнительных пакетов

sudo apt update && sudo apt -y upgrade
sudo apt install -y openssh-server vim git

Установка Docker

Добавляем ключи GPG

sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Добавляем репозиторий 

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Производим установку Docker

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Дополнительные настройки для работы Docker от имени пользователя

sudo usermod -aG docker $USER
newgrp docker

Установка Gitlab CE

Устанавливаем дополнительные пакеты, добавляем репозиторий и выполняем установку Gitlab CE

sudo apt-get install -y curl ca-certificates tzdata perl
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo apt-get install gitlab-ce

Вносим изменения в конфигурацию 

sudo vi /etc/gitlab/gitlab.rb

Правим следующие параметры

...
external_url 'http://192.168.0.16'
...
pages_external_url "http://pages.local/"
gitlab_pages['enable'] = true
....

ВАЖНО В конфигурации указывается ip адрес виртуалной машины 192.168.0.16 для основного интерфейса Gitlab и доменное имя которое будет использовано для доступа к Pages pages.local

ПРИМЕР Установить статическую запись DNS на роутере Mikrotik IP->DNS->Static

Regexp .*\.pages\.local
Type A
Address 192.168.0.16

Применим настройки конфигурации

sudo gitlab-ctl reconfigure

Задаем новый пароль для пользователя root в Gitlab

sudo gitlab-rake "gitlab:password:reset"

В командной строке вводим имя пользователя, пароль и подтверждаем пароль

Enter username: root
Enter password: 
Confirm password:

Установка gitlab-runner

Добавляем репозиторий и устанавливаем пакет

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner

Для каждого проекта в Gitlab при необхдимости нужно создавать свой Runner. Делается это в настройках проекта (Settings->CI/CD->Runners). После создания его необходимио зарегистрировать в системе.

Например

gitlab-runner register --url http://192.168.0.16 --token glrt-t3_Cb1-nS4KrHjxz7zPhMbS

ВАЖНО После регистрации Runner не будет выполнятся в автоматическом режиме

Ручной запуск можно выполнить командой

gitlab-runner run

Для того чтобы Runner запускался автоматически при обновлении проекта существует 2 варианта:

  1. Выполнить запуск команды 

    nohup gitlab-runner run &

    которая запустит процесс от имени пользователя и будет использовать конфигурационный файл /home/<user>/.gitlab-runner/config.toml (подробнее man nohup)

  2. Выполнить запуск systemd сервиса

    sudo systemctl start gitlab-runner

    который будет использовать конфигурационный файл /etc/gitlab-runner/config.toml

Установка Docusaurus

Загружаем установочные скрипты NodeJS

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

Загружаем обновление

source ~/.bashrc

Выполняем установку

nvm install 22

После установки прверяем версию

node -v

Должна быть v22.11.0

Создаем рабочий каталог и выполняем установку Docusaurus

mkdir docusaurus && cd docusaurus
npx create-docusaurus@latest my-site classic
cd my-site

Выполняем команду запуска локального сервера

npm run start -- --host 0.0.0.0

Если все выполнено корректно сервер ответит по адресу http://192.168.0.16:3000

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

Переходим по ссылке для создания пустого проекта: https://192.168.0.16/projects/new#blank_project

Заполняем поля:

  1. Project name - любое имя проекта.
  2. Project slug - имя репозитория (далее в примере используется your-test-site).
  3. Выбрать чекбокс Public.
  4. Убрать чекбокс Initialize repository with a README.
  5. Нажать кнопку Create project.

Клонируем пустой проект

git clone https://192.168.0.16/root/your-test-site.git

Переходим в каталог проекта

cd your-test-site

Указываем локальные реквизиты для работы с проектом

git config --local user.name "Administrator"
git config --local user.email "gitlab_admin_23a561@example.com"

Переключаем ветку

git switch -c main

Копируем файлы ранее установленного Docusaurus

cp -r ~/docusaurus/my-site/* ./

Добавляем все файлы в проект

git add --all

Сохраняем изменения в проекте

git commit -m "add files"

Загружаем проект на Gitlab 

git push --set-upstream origin main

Создание конфигурации CI

Создаем в проекте файл

vi .gitlab-ci.yml

С конфигурацией

image: node:latest

# allow caching for faster deployment
cache:
  paths:
    - node_modules/
    - public/
    - .cache/

pages:
  stage: deploy
  script:
    - yarn install
    - yarn build:gitlab
  artifacts:
      paths:
        - public
  only:
    - main

Редактируем правила сборки Docusaurus

vi package.json

Добаляем после строки "build": "docusaurus build", правило для публикации

"build:gitlab": "docusaurus build --out-dir public",

Редактируем конфигурацию Docusaurus

vi docusaurus.config.js

Указываем параметр baseUrl в соответствии с именем проекта в Gitlab

baseUrl: '/your-test-site/',

ВАЖНО Перед последующими шагами необходимио зарегистрировать Runner для данного проекта.

Для этого переходим в интерфейсе проекта Gitlab Settings->CI/CD->Runners

  1. Нажимаем кнопку New project runner
  2. Отмечаем чекбокс Run untagged jobs
  3. Нажимаем кнопку Create runner

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

gitlab-runner register --url http://192.168.0.16 --token glrt-t3_mPKkd4dHgo8zau8yuyic

Отвечаем на вопросы регистратора

  1. Enter the GitLab instance URL - указать URL Gitlab или можно просто нажать Enter
  2. Enter a name for the runner.- указать имя или можно просто нажать Enter
  3. Enter an executor: - указываем docker
  4. Enter the default Docker image - указываем node:latest

Запускаем runner любым удобным способом (описано выше)

Добавляем все файлы в проект

git add .

Сохраняем изменения в проекте

git commit -m "add CI configs"

Загружаем проект на Gitlab 

git push

После публикации проекта и при запущенном Runner автоматически начнется генерация и публикация проекта Docusaurus

Состояние можно посмотреть в меню проекта Build->Jobs

После окончания сборки и публикации проекта в Pages состояние сборки изменится на Passed

Переходим в меню проекта Deploy->Pages

  1. Снимаем чекбокс Use unique domain
  2. Нажимаем кнопку Save changes
  3. Проверяем что URL проекта доступен

Добавление модуля поиска в проект Docusaurus

Выполняем команду установки в каталогк проекта

npm i docusaurus-lunr-search --save

Редактируем конфигурацию Docusaurus

vi docusaurus.config.js

Добавляем описание модуля поиска перед строкой themeConfig: 

  plugins: [
    require.resolve('docusaurus-lunr-search')
  ],

  themeConfig:

ПРИМЕЧАНИЕ Поиск не работает при локальном запуске, только при публикации на Gitlab Pages

Добавляем все файлы в проект

git add .

Сохраняем изменения в проекте

git commit -m "add search plugin"

Загружаем проект на Gitlab 

git push

ПРИМЕЧАНИЕ Чтобы избежать ошибок при публикации Docusaurus на Gitlab Pages желательно перед загрузкой проекта выполнить сборку и проверку при помощи запуска локального сервера.

Опубликовано: