Установка GitLab во FreeBSD

Подготовка

В этот раз я решил более традиционно для себя сделать два сетевых адаптера (NAT и виртуальная сеть), но при установке FreeBSD настроил только один. Поэтому начинаем непосредственно в интерфейсе машины (здесь и далее пользователь root, если не оговорено иное):

freebsd-update fetch
freebsd-update install
pkg install bash mc
chsh -s /usr/local/bin/bash root
reboot

Настраиваем второй адаптер:

pciconf -lv | grep -A1 -B3 network
sysrc ifconfig_em1="DHCP"
reboot

Первой командой на всякий случай убедился, что он называется em1.

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

ifconfig
ping -c2 www.freebsd.org

Вроде бы все работает, но по SSH под root не пускает. Редактируем /etc/ssh/sshd_config и перезапускаем сервис:

PermitRootLogin yes

service sshd restart

Можем выходить и подключаться по SSH.

Установка

Пакет

Не мудрствуя лукаво:

pkg install gitlab-ce

Версия GitLab 18.2.1 (между прочим, актуальная на момент эксперимента). Пакет тащит за собой очень подозрительные программы типа wayland, ffmpeg и x265, ну и ожидаемо Redis в виде зависимостей.

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

https://gitlab.com/mfechner/freebsd-gitlab-docu/blob/master/install/18.2-freebsd.md

Из которого следует, что довольно многое нужно установить и сконфигурировать самостоятельно, в том числе веб-сервер, а сама структура конфигурации соответствует варианту компиляции исходников.

Я на всякий случай перезагрузил виртуальную машину, чтобы убедиться, что она хотя бы стартанет после такого. Стартует.

PostgreSQL

Клиент PostgreSQL установился как зависимость, а сервер почему-то нет. Устанавливаем:

pkg install postgresql17-server postgresql17-contrib

Включаем и инициализируем PostgreSQL:

service postgresql enable
service postgresql initdb
service postgresql start

Опять же, инициализация по умолчанию проходит с доверенными локальными подключениями:

initdb: warning: enabling "trust" authentication for local connections
initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.

Параметры почему-то игнорируются. Либо бессовестным образом оставляем все как есть, или таки редактируем пресловутый /var/db/postgres/data17/pg_hba.conf. Я, как вы знаете, бессовестный, поэтому продолжаем.

Здесь, кстати, есть разночтение между руководством для FreeBSD и официальным. В первом из них пользователь БД создается с правами суперпользователя, которые ближе к концу отнимаются. В официальном же ничего такого нет. Еще одно различие – в порядке создания расширений. В официальной они создаются сначала (в базе template1), а во FreeBSD-шной потом. Давайте наверное действовать ближе к официальной инструкции:

psql -d template1 -U postgres

CREATE USER git CREATEDB;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS btree_gist;
CREATE EXTENSION IF NOT EXISTS plpgsql;
CREATE DATABASE gitlabhq_production OWNER git;

Выходим (\q или exit) и пробуем переподключиться:

psql -U git -d gitlabhq_production

Проверим установку расширений:

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'pg_trgm'
AND installed_version IS NOT NULL;

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'btree_gist'
AND installed_version IS NOT NULL;

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'plpgsql'
AND installed_version IS NOT NULL;

Все три запроса должны выдать одинаково успешный результат (t от слова true – истина):

 enabled
---------
 t
(1 row)

Выходим.

Redis

Этот нехороший человек установился как зависимость, но требует настройки в виде добавления прослушивания сокета.

Файл /usr/local/etc/redis.conf:

unixsocket /var/run/redis/redis.sock
unixsocketperm 770

Включаем и запускаем сервис, а также добавляем пользователя git к нему в группу:

service redis enable
service redis start
pw groupmod redis -m git

GitLab

Он внезапно устанавливается в /usr/local/www/gitlab. Туда и предлагается перейти:

cd /usr/local/www/gitlab

Правим основной config/gitlab.yml. Хост пока пропишем в виде IP-адреса виртуалки, например:

    ## Web server settings (note: host is the FQDN, do not include http://)
    host: "192.168.56.143"

Почту предлагаю отключить: email_enabled: false. Также я отключу по умолчанию все «фишки» новых проектов, кроме проблем:

    default_projects_features:
      issues: true
      merge_requests: false
      wiki: false
      snippets: false
      builds: false
      container_registry: false

Информацию об использовании продукта тоже отключаем (но потом еще и в админ-панели нужно будет все поотключать):

initial_gitlab_product_usage_data: false

Как мы уже видели, Pages для развертывания в конечном итоге требуют Docker, с которым во FreeBSD все сложно. Например, иногда можно намутить виртуальную машину Arch Linux. К счастью, по умолчанию эти самые страницы выключены. Туда же отправляется и реестр контейнеров, потому что – что?

You must deploy a registry using the image corresponding to the version of GitLab you are installing (for example: registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab)

Да уж. В принципе gitlab.yml весьма здоровый файл, но остальные настройки по умолчанию на первый взгляд годятся.

В config/puma.rb наверное обнуляем минимальное количество потоков и отключаем кластерный режим:

threads 0, 16
workers 0

Прометея отключать не надо, поскольку он и не устанавливается, а конкуренция у второстепенного персонажа и так вроде низкая – 5, если верить config/sidekiq.yml.

В файле config/database.yml, в секции production (или по желанию вообще везде), убираем пароли.

Настраиваем git (хотя, если честно, ничего такого в официальной инструкции я не нашел). Раз у соответсвующего пользователя есть оболочка, мне кажется проще перейти в него, чем каждый раз вызывать su -l.

su git

git config --global core.autocrlf input
git config --global gc.auto 0
git config --global repack.writeBitmaps true
git config --global receive.advertisePushOptions true
git config --global core.fsync objects,derived-metadata,reference

Где:

• core.autocrlf input – автоматическое приведение переносов строк к стилю unix (LF) при коммитах;
• gc.auto 0 – отключение автоматической сборки мусора (этим по идее занимается GitLab);
• repack.writeBitmaps true – включает индексацию pack-файлов;
• receive.advertisePushOptions true – включает оповещение клиента о поддержке дополнительных параметров отправки (push);
• core.fsync objects,derived-metadata,reference – параметры сброса данных на диск (fsync), вроде как снижает риск повреждения репозиториев при сбоях сервера.

Создаем директории, репозиториям также назначаем права 2770:

mkdir -p /usr/local/git/.ssh
mkdir -p /usr/local/git/repositories
chmod 2770 /usr/local/git/repositories
exit

Соответственно вернулись в root. Меняем владельца некоей директории для возможности создания загадочной ссылки в процессе установки:

chown git /usr/local/share/gitlab-shell

И вот, наконец, добрались до установки GitLab. Находясь в /usr/local/www/gitlab под root (опять же не совсем понятно, почему нельзя переключиться, впрочем туда-сюда переключаться наверное в данном случае нерационально):

su -l git -c "cd /usr/local/www/gitlab && rake gitlab:setup RAILS_ENV=production"

Теоретически можно было бы заодно указать пароль root (GitLab'а) в переменной окружения GITLAB_ROOT_PASSWORD, но мы легких путей не ищем и историю команд не компрометируем!

Итак, в начале будут выданы предупреждения о генерации различных секретов, соответственно в дальнейшем надо будет отдельно сохранить config/secrets.yml. На вопрос создания таблиц отвечаем yes, и тут возникает подозрение, что мы зря сами делали базу, поскольку установщик ее вроде как сносит и создает заново. Н-да. Что касается пароля:

Administrator account created:

login:    root
password: You'll be prompted to create one on your first visit.

Допустим. Возвращаем владельца gitlab-shell:

chown root /usr/local/share/gitlab-shell

Проверяем состояние приложения:

su -l git -c "cd /usr/local/www/gitlab && rake gitlab:env:info RAILS_ENV=production"

Вообще-то Gitaly не запущен, но в соответствии с инструкцией по FreeBSD это на данный момент нормально, равно как и неизвестная версия Go.

Следующий этап – компиляция ресурсов – весьма требователен к памяти, что вообще говоря сводит на нет весь эксперимент с FreeBSD, поскольку произвольным образом менять объем оперативной памяти на VDS/VPS как правило нельзя (точнее можно увеличивать, но уменьшать практически никогда). Итак, вышел и выключил виртуальную машину, поставил ей 11 (!) гигабайт ОЗУ (нужно где-то минимум 8), а заодно и процессорное ядро подкинул.

Кстати можно очистить кэш пакетов, освободится примерно гигабайт дискового пространства:

pkg clean -a

Итак, возвращаемся обратно, и я предлагаю все же переключиться в git:

cd /usr/local/www/gitlab
su git

yarn config set python /usr/local/bin/python3.11
yarn install --production --pure-lockfile
RAILS_ENV=production NODE_ENV=production USE_DB=false SKIP_STORAGE_VALIDATION=true bundle exec rake gitlab:assets:compile
exit

На всякие ошибки и предупреждения в процессе работы второй команды также предлагается не обращать внимания. Для выполнения третьей команды как раз и нужна вся оперативка, что есть. Пробовал подкидывать своп, но завершения работы так и не дождался. Она и с достаточным количеством ОЗУ работает довольно долго, и в какой-то момент кажется, что ничего не происходит – наберитесь терпения. Соответственно после завершения этапа вернул настройки виртуалки обратно.

Наконец включаем и запускаем основной сервис:

service gitlab enable
service gitlab start

Выводятся предупреждения, связанные с отключением кластерного режима кошатины, но так вроде в основном запускается благополучно. Дважды, как пишут в документации , проверяем состояние:

su -l git -c "cd /usr/local/www/gitlab && rake gitlab:check RAILS_ENV=production"

Понятно, что сервиса Systemd у нас нет, а еще у меня вроде как он сам исправил доступ к файлу авторизованных ключей.

Веб-сервер

Это будет, конечно же, Nginx Caddy. Как говорится, не в первый раз замужем, так что:

pkg install caddy security/portacl-rc
sysrc portacl_users+=www
sysrc portacl_user_www_tcp="http"
service portacl enable
service portacl start
sysrc caddy_user=www caddy_group=www
service caddy enable

HTTPS на виртуальной машине, очевидно, ни к чему. Правим /usr/local/etc/caddy/Caddyfile – заменяем localhost на такую штуку:

http:// {
    root * /usr/local/www/gitlab/public

    # прокси для прокси
    reverse_proxy unix//usr/local/www/gitlab/tmp/sockets/gitlab-workhorse.socket

    # кастомная обработка ошибок
    handle_errors {
        @custom_err file /{err.status_code}.html
        handle @custom_err {
            rewrite * {file_match.relative}
            file_server
        }
        respond "{err.status_code} {err.status_text}"
    }
}

Запускаем:

service caddy start

И идем проверять, в моем случае на http://192.168.56.143/. Внезапно заработало:

И даже установщик не соврал. Так что устанавливаем пароль (и e-mail при желании) и наслаждаемся результатом.

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

На самом деле, долго наслаждаться не получится, поскольку FreeBSD начинает убивать процессы из-за нехватки памяти. Хотя должен отметить, что вебсокет, в отличие от Traefik без двигателя модели X, работает (пока работает).

Контекст такой, что при 2 гигабайтах ОЗУ установщик создал раздел подкачки на 820 мегабайт. А поскольку место ограничено очень (надо было гигов на 20 диск создавать), скорее всего лучше именно добавить диск к виртуальной машине, а не создавать файл.

Теоретически можно почистить кэш yarn, но при обновлении он очевидно заново наберется. Кстати кэш гитлаба наверное тоже можно того…

su git

cd /usr/local/www/gitlab
yarn cache clean --all
bundle exec rake cache:clear RAILS_ENV=production
exit

Выключаем виртуальную машину, добавляем к ней диск (хотя бы на 1 гигабайт) и включаем заново. Диск в моем случае называется /dev/ada1 (проверить geom disk list). В /etc/fstab добавляем:

/dev/ada1       none            swap    sw      0       0

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

Резервное копирование

Честно говоря, я опасался, что это будет какой-то сложный процесс, но нет – есть команда, аналогичная gitlab-backup create:

su -l git -c "cd /usr/local/www/gitlab && rake gitlab:backup:create RAILS_ENV=production"

Правда возникает вопрос, а где, собственно, архив? Странным образом он нашелся в /usr/local/www/gitlab/tmp/backups. Ну ладно… Хотя вообще-то директория архивов настраивается в gitlab.yml.

Сообщение о gitlab.rb и gitlab-secrets.json, очевидно, «хвост» от стандартной установки, нам же нужно сохранить или всю директорию config, или лишь несколько файлов из нее:

• database.yml
• gitlab.yml
• puma.rb
• secrets.yml

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

На всякий случай, симметричная команда восстановления делается на остановленном GitLab:

su -l git -c "cd /usr/local/www/gitlab && rake gitlab:backup:restore RAILS_ENV=production"

В случае наличия нескольких архивов нужная отсечка указывается через переменную BACKUP.

Это, конечно, правда, но не вся – например когда я переносил Лабу с Oracle Linux в Docker, все было куда сложнее. Но у нас и без этого статья получается довольно большой, так что позволю себе не вдаваться в детали.

Обновление

Обновлять все это дело тоже крайне нетривиально, к тому же надо обязательно учитывать нюансы обновления с конкретной версии на конкретную. Например можно проанализировать документ обновления с 18.1 до 18.2: https://gitlab.com/mfechner/freebsd-gitlab-docu/-/blob/master/update/18.1-18.2-freebsd.md

Предлагается сначала снять архив (см. выше), а потом остановить сервис.

service gitlab stop

Далее – обновить пакеты:

pkg upgrade -Fy
pkg upgrade gitlab-ce
pkg autoremove
pkg upgrade
pkg autoremove

На мой взгляд, немного переусложнено, но сначала просто запрашиваем список обновленных пакетов (и возможных конфликтов), отдельно обновляем gitlab-ce, а потом уже все остальное с удалением всякого ненужного.

Следующий шаг – сравнение многочисленных конфигурационных файлов и внесение изменений при необходимости. Как ни странно, git diff работает (хотя вроде это не репозиторий). Цитирую инструкцию:

cd /usr/local/www/gitlab

git diff config/gitlab.yml.sample config/gitlab.yml
git diff config/database.yml.sample config/database.yml
# normally no modification should be required here
git diff /usr/local/share/gitaly/config.toml.sample /usr/local/share/gitaly/config.toml
git diff public/robots.txt.sample public/robots.txt
# you maybe would like to adapt the number of workers
git diff config/puma.rb.sample config/puma.rb
# gitlab-shell
git diff /usr/local/share/gitlab-shell/config.yml.sample /usr/local/share/gitlab-shell/config.yml

Pages в данном случае не нужны.

Затем частично повторяем этапы установки, включая пресловутую компиляцию ресурсов, и между делом применяем миграции. В инструкции предлагается проверить расширения PostgreSQL. Я думаю с ними все и так будет хорошо, так что пропущу.

su git

git config --global --unset core.fsyncObjectFiles
git config --global core.fsync objects,derived-metadata,reference
rm Gemfile.lock
rake db:migrate RAILS_ENV=production
yarn config set python /usr/local/bin/python3.11
yarn install --production --pure-lockfile
RAILS_ENV=production NODE_ENV=production USE_DB=false SKIP_STORAGE_VALIDATION=true bundle exec rake gitlab:assets:compile
rake cache:clear RAILS_ENV=production
exit

Примечание от 06.09.2025. Добавил важный этап – удаление файла Gemfile.lock, без этого rake будет безуспешно пытаться найти устаревшие версии компонентов Ruby и просить их установить.

Нашу мега-конфигурацию Caddy вряд ли потребуется менять, так что запускаем GitLab:

service gitlab start

И для очистки совести делаем проверки, допустим без переключения пользователя:

su -l git -c "cd /usr/local/www/gitlab && rake gitlab:env:info RAILS_ENV=production"
su -l git -c "cd /usr/local/www/gitlab && rake gitlab:check RAILS_ENV=production"

Да уж, это тебе не контейнер пересоздать.

Заключение

Как и ожидалось, все работает довольно быстро. Жаль, что не было такого на VPS с двумя гигабайтами. С другой стороны, все портит компиляция ресурсов, которой нужно 8 гигабайт ОЗУ. При этом уже на четырех песик замечательно себя чувствует в Docker под Debian. И, конечно же, отмечу крайне сложный процесс установки и обновления по сравнению с менеджерами пакетов в Linux или тем же грузчиком.

Несмотря на некоторое разочарование, не могу не отдать должное труду Маттиаса Фехнера (Matthias Fechner, надеюсь правильно фамилию русифицировал). Хорошо, что есть еще энтузиасты, поддерживающие FreeBSD, иначе пришлось бы компилировать не только ресурсы, но и весь зоопарк (Workhorse, Puma и прочие персонажи) с неизвестным результатом. А может быть и самой фряхи не было бы уже.

И все же реальность такова, что я вынужден закончить наш сегодняшний тест-драйв цитатой из документации, это заголовок первого же раздела про компиляцию GitLab из исходников:

Consider the Linux package installation.