Сервер технической документации

Целью этой заметки является описание варианта системы публикации технической документации в формате Markdown на едином сайте, разными авторами и с поддержкой контроля версий разрабатываемых материалов. Также приводятся базовые правила для работы с системой.

Веб-сервером в данном случае являтется Apache, в качестве системы контроля версий используется Git, а для автоматизации создания сайта - MkDocs Material.

Описание дается для сервера на базе ОС Debian GNU/Linux версии 12.9. Использовалась конфигурация сервера "по-умолчанию" - учитывайте это при конкретной реализации, т.к. могут быть затронуты такие аспекты настройки сервера как: пакетная фильтрация трафика (если она у вас настроена), конфигурация SSH (если конфигурация SSH отличается от стандартной), конфигурация Apache (если вы уже каким-то образом настроили веб-сервер).

Предполагается, что клиентской системой также является Debian GNU/Linux. Для других операционных систем внесите соответствующие необходимые (и я надеюсь, незначительные) изменения самостоятельно.

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

На сервере и клиенте установите необходимые пакеты:

apt install git install-info mc

На сервере дополнительно необходимо установить веб-сервер и MkDocs:

apt install apache2 mkdocs-material

На сервере и клиенте должен быть создан пользователь:

useradd -m USERNAME
passwd USERNAME

Для удобства и в качестве дополнительной меры безопасности рекомендуется выполнять аутентификацию клиента на сервере при помощи ключа клиента (при генерации ключа настоятельно рекомендуется также задать парольную фразу, а доступ к файлам ключа должен быть максимально ограничен):

ssh-keygen -t ed25519
eval `ssh-agent -s`
ssh-add
ssh-copy-id -p 22 USERNAME@SERVER_ADDRESS

В клиентской системе от имени пользователя должна быть выполнена настройка параметров, необходимых для фиксации изменений в репозиториях:

git config --global user.email "USERNAME@MAILSERVER"
git config --global user.name "USERNAME"

На сервере создайте директорию для размещения сайта созданного пользователя:

mkdir /var/www/USERNAME
chown USERNAME:USERNAME /var/www/USERNAME

Добавьте в файл /etc/apache2/sites-available/000-default.conf конфигурацию сайта пользователя:

<VirtualHost *:80>

...

Alias /USERNAME /var/www/USERNAME
<Directory /var/www/USERNAME>
AllowOverride All
</Directory>

...

</VirtualHost>

Перезапустите веб-сервер:

systemctl restart apache2

Так как клиентские и серверные файлы хуков не синхронизируются, т.е. не передаются командами git push или git clone, в качестве варианта можно создать файлы пользовательских хуков в какой-то отдельной директории в директории рабочей копии, а в .git/hooks сделать символические ссылки на эти файлы:

cd ~/REPO_NAME
mkdir hooks
nano hooks/post-receive
chmod +x hooks/post-receive
ln -s ../../hooks/post-receive .git/hooks/

Но так могут работать только хуки в клиентской системе. Хуки, например, post-receive, выполняющиеся после загрузки на сервер, не будут выполнены, т.к. в директории .git на сервере не будет ссылок на них. Серверные хуки рекомендуется создавать на сервере.

Создайте файл хука /home/USERNAME/REPO_NAME/.git/post-receive на сервере:

#!/bin/bash
cd ~
mkdir -p ~/temp/clone
mkdir -p ~/temp/site
git clone REPO_NAME ~/temp/clone
rm -rf ~/temp/clone/.git
rm -rf ~/temp/clone/hooks
mkdocs new ~/temp/site
cp -rf ~/temp/clone/* ~/temp/site/docs
cd ~/temp/site
mkdocs build -d /var/www/USERNAME
cd ~
rm -rf ~/temp

Работа с репозиториями

Если нужно создать репозиторий пользователя на сервере, выполните:

mkdir -p /home/USERNAME/REPO_NAME
cd /home/USERNAME/REPO_NAME
git init --bare
chown -R USERNAME:USERNAME /home/USERNAME/REPO_NAME

Если нужно создать репозиторий в клиентской системе от имени пользователя, а затем разместить созданный репозиторий на сервере (то есть доступ к репозиторию будет осуществляться удаленно), выполните:

mkdir -p ~/REPO_NAME
cd ~/REPO_NAME
git init --bare
scp -r ~/REPO_NAME USERNAME@SERVER_ADDRESS:~
cd ..
rm -rf ~/REPO_NAME

После этого, работу с репозиторием следует начинать выполнив предварительно клонирование с сервера.

Почему bare?

Обратите внимание, что в описанном выше случае необходимо создавать т.н. bare (пустой) репозиторий, который сначала следует загрузить на сервер, а затем выполнить клонирование в клиентскую систему. Если сильно упростить объяснение причин такой необходимости, то это нужно для репозиториев, доступ к которым будет осуществляться удаленно. Для локальных репозиториев, которые должны быть доступны только в рамках одной системы, это не требуется.

Чтобы выполнить клонирование репозитория с сервера в клиентскую систему, в клиентской системе от имени пользователя, выполните:

git clone USERNAME@SERVER_ADDRESS:~/REPO_NAME

Чтобы внести изменения в репозиторий, например, создав файл README в клиентской системе от имени пользователя, выполните:

cd ~/REPO_NAME
touch README
git add .
git commit -m "File README added"
git push