Atlassian - BitBucket installation

OS: "Linux Debian 9 (Stretch)", "Linux Ubuntu 18 (Bionic Beaver) LTS".

Задача: запустить в работу web-сервис "Atlassian BitBucket", предназначенный для управления Git-репозиториями.

Заранее отмечу, что сервис хранения репозиториев "BitBucket" сборкой, тестированием и развёртыванием приложений не занимается. Для полуручного "деплоя" можно использовать плагины вроде "External Hooks" и "Adaptavist Script Runner", но это не особо хорошо поддающийся автоматизации путь. Полноценно процедуры CI/CD кода репозиториев "BitBucket" лучше всего наладить посредством дополнительного сервиса вроде "Atlassian Bamboo".

Как вариант можно возложить задачу развёртывания приложения непосредственно на серверы сборки, тестирования и публикации, просто уведомляя их о появлении новых релизов в репозитории хранения посредством так называемых "webhook"-ов - но здесь не об этом.

Для работы "Atlassian BitBucket" требуется следующий минимальный набор приложений:

1. Интерпретатор "Oracle JDK/JRE (Java) v1.8u65+".
2. СУБД "PostgreSQL v9.3.6-10".
3. Интерпретатор "Perl v5.8.8+".
4. Инструментарий "Git v2.4+".

Требования пунктов 1 и 2 мы удовлетворили на этапе предварительной подготовки, описываемой в отдельной публикации.

Сервер приложений "Tomcat" уже встроен в дистрибутив "Atlassian BitBucket" - так что его инсталлировать не нужно (WAR-версия web-приложения отдельно более не поставляются).

Последовательность дальнейших действий такова:

1. Устанавливаем web-приложение "BitBucket" и настраиваем его автозапуск.
2. Настраиваем обработчики для проксирования от "Nginx" к web-приложению.
3. Создаём "базу данных" web-приложения.
4. Производим первичную настройку web-приложения "BitBucket".
5. Опционально разбираемся с резервным копированием.

Установка необходимого "BitBucket" ПО.

Явно устанавливаем нужные "BitBucket" приложения и удостоверяемся в соответствии их версий требованиям совместимости:

# aptitude install git perl
# perl --version
# git --version

Подготовка файловой структуры для web-приложения.

Программные продукты "Atlassian" представляют собой мешанину из Java-классов, C-бинарников, shell-скриптов, разномастных конфигурационных файлов и всевозможных статичных данных, разделению по типам слабо поддающуюся. Директория "/opt" - единственное подходящее для них место:

# mkdir -p /opt/atlassian/bitbucket

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

# mkdir -p /var/atlassian/appdata/bitbucket

Создание пользователей и условий для усечения привилегий приложения.

Создаём группу для приложений "Atlassian" вообще, и пользователя непосредственно для запуска сервиса "BitBucket":

# groupadd --system --force atlassian
# useradd --system --home-dir /opt/atlassian/bitbucket --shell /bin/false --gid atlassian bitbucket

Переводим во владения нового пользователя файловые ресурсы web-сервиса:

# chown root:atlassian /opt/atlassian /var/atlassian /var/atlassian/appdata
# chown -R bitbucket:atlassian /opt/atlassian/bitbucket /var/atlassian/appdata/bitbucket
# chmod -R o-rwx /opt/atlassian /var/atlassian

Развёртывание web-приложения "Atlassian BitBucket".

Идём на сайт разработчиков и, в разделе загрузки, забираем "TAR.GZ Archive" - вариант дистрибутива для ручной установки.

Дистрибутив "BitBucket" коряво упакован с двойным сжатием, и простым "tar -xf" его не раскроешь - приходится использовать конвейер из "GZ -> TAR":

# cd /tmp
# gzip -dc /tmp/atlassian-bitbucket-5.16.0.tar.gz | tar -xzf - -C /tmp/

Дабы не возиться с последующим переопределением прав доступа к развёрнутым из дистрибутива файлам, проще сделать это от имени того пользователя, что будет в дальнейшем запускать web-сервисы:

# sudo -u bitbucket cp -rn /tmp/atlassian-bitbucket-5.16.0/* /opt/atlassian/bitbucket/ && rm -r /tmp/atlassian-bitbucket-5.16.0

Конфигурирование первого этапа запуска Tomcat-инстанса "BitBucket" разработчиками такового предлагается осуществлять правкой стартовых Bash-скриптов, что безусловно варварство. Учитывая то, что все настройки сводятся к определению переменных окружения, указывающих на месторасположение JRE/JDK и директории данных web-приложения, я предпочитаю сделать это без вмешательства в файлы дистрибутивного набора приложения, простейшей подстановкой переменных перед запуском приложения.

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

# cd /opt/atlassian/bitbucket/
# sudo -u bitbucket -s JRE_HOME="/usr/lib/jdk/default" BITBUCKET_HOME="/var/atlassian/appdata/bitbucket" ./bin/start-bitbucket.sh

Starting Atlassian Bitbucket as the current user
....
Starting bundled Elasticsearch
....
Starting Bitbucket webapp at http://localhost:7990
The Bitbucket webapp has been started.

Проверяем, прослушивает ли web-приложение типовой для него сетевой порт:

# netstat -apn | grep 7990

tcp ... 0.0.0.0:7990 0.0.0.0:* LISTEN 10569/java

Опциональные настройки компонентов web-приложения.

Как можно было заметить из вывода пробного запуска web-приложения в разделе выше, вместе с ним стартует сервис полнотекстового поиска "Elasticsearch", с недавних пор поставляемый в дистрибутиве "Atlassian BitBucket", уже полностью с ним интегрированный.

Настройки по умолчанию подразумевают запуск "Elasticsearch" только для локальных нужд, но некоторые нюансы конфигурации могут открыть сервис и для запросов извне. Я считаю полезным явно ограничить сетевые взаимодействия поискового сервиса IP-адресом интерфейса "локальной петли":

# vi /var/atlassian/appdata/bitbucket/shared/search/elasticsearch.yml

....
network.host: "127.0.0.1"
http.host: "127.0.0.1"
....

Оптимизация работы приложения с дисковой подсистемой.

Для Java-приложений "Atlassian" активно создающих и уничтожающих временные файлы, выгодно вынести эту работу в максимально скоростную файловую систему, смонтированную в область памяти ОЗУ. Проще всего это сделать, подстроившись под предопределённые настройками "BitBucket" директорию "${BITBUCKET_HOME}/tmp":

# mkdir -p /var/atlassian/appdata/bitbucket/tmp

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

# chown -R bitbucket:atlassian /var/atlassian/appdata/bitbucket/tmp
# chmod -R go-rwx /var/atlassian/appdata/bitbucket/tmp

Добавляем в системный перечень монтируемых файловых систем нашу:

# vi /etc/fstab

....
# Tuning the location of Atlassian applications temporary files
tmpfs /var/atlassian/appdata/bitbucket/tmp tmpfs rw,nosuid,nodev,size=2G,uid=bitbucket,gid=atlassian,mode=0750 0 0
....

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

# mount /var/atlassian/appdata/bitbucket/tmp

Я бы выделял под такого рода файловые системы до 10% от объёма ОЗУ (они не заблокируют всё заявленное место - блоки памяти будут выбираться по мере появления необходимости).

Настраиваем автозагрузку сервиса посредством "Systemd".

Создаём файл описания нового сервиса "Atlassian BitBucket":

# vi /etc/systemd/system/bitbucket.service

[Unit]
Description=Atlassian BitBucket Service
After=network.target

[Service]
Type=forking
User=bitbucket
Group=atlassian

# Указываем на месторасположение JRE/JDK и директории пользовательских данных
Environment=JRE_HOME=/usr/lib/jdk/default
Environment=BITBUCKET_HOME=/var/atlassian/appdata/bitbucket

# Выдаём Java-приложению потребный объём ОЗУ
Environment=JVM_MINIMUM_MEMORY=4g
Environment=JVM_MAXIMUM_MEMORY=10g

# Расширяем ограничение на количество одновременно открытых файлов минимум до 4096 (по умолчанию 1024)
LimitNOFILE=8192

# Ограничиваем доступ посторонним к создаваемым сервисом файлам
UMask=0027

# Задаём команды запуска и останова web-приложения
ExecStart=/opt/atlassian/bitbucket/bin/start-bitbucket.sh
ExecStop=/opt/atlassian/bitbucket/bin/stop-bitbucket.sh
ExecReload=/opt/atlassian/bitbucket/bin/stop-bitbucket.sh && sleep 60 && /opt/atlassian/bitbucket/bin/bitbucket-jira.sh

[Install]
WantedBy=multi-user.target

Даём "Systemd" указание перечитать конфигурационные файлы и активируем сервис:

# systemctl daemon-reload
# systemctl enable bitbucket

Уже сейчас сервис можно запускать (попутно проверив его статус):

# service bitbucket start
# service bitbucket stop
# service bitbucket status

bitbucket.service - Atlassian BitBucket Service
Loaded: loaded (/etc/systemd/system/bitbucket.service; enabled; vendor preset: enabled)
Active: active (running) ...
....
start-bitbucket.sh[13370]: Starting Bitbucket webapp at http://localhost:7990
....
systemd[1]: Started Atlassian BitBucket Service.

Настройка связки фронтального web-сервера с инстансом "Tomcat".

Конфигурация принимающего подключения пользователей web-сервера "Nginx" проста и сводится к описанию параметров проксирования всех запросов нижележащему инстансу "Tomcat".

Создаём конфигурационный файл описания сайта web-сервиса:

# vi /etc/nginx/sites-available/bitbucket.example.net

# Блок перехвата обращений посредством открытого HTTP и перенаправления таковых на HTTPS
server {
  listen 80;
  server_name bitbucket.example.net;
  access_log off; error_log off;
  rewrite ^(.+)$ https://bitbucket.example.net$1 permanent;
}

# Блок описания web-сервиса приёма, терминирования SSL/TLS запросов и проксирования их нижележащему Tomcat
server {
  listen       443 ssl http2;
  server_name  bitbucket.example.net;

  access_log  /var/log/nginx/bitbucket.example.net_access.log;
  error_log   /var/log/nginx/bitbucket.example.net_error.log;

  # Явно указываем обслуживать здесь только SSL/TLS подключения
  ssl on;

  # Описываем параметры установления соединений SSL/TLS
  ssl_certificate      /etc/nginx/ssl/wildcard-example.net.crt;
  ssl_certificate_key  /etc/nginx/ssl/wildcard-example.net.key.decrypt;
  ssl_protocols  SSLv2 SSLv3 TLSv1 TLSv1.1 TLSv1.2;
  ssl_ciphers    HIGH:!aNULL:!MD5;
  ssl_prefer_server_ciphers  on;

  # Отправляем все запросы на обработку в Tomcat
  location / {
    proxy_pass http://localhost:7990;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Server $host;
    proxy_connect_timeout  240;
    proxy_send_timeout     240;
    proxy_read_timeout     240;
  }
}

Активируем для "Nginx" новую конфигурацию, проверяем её и запускаем в работу:

# ln -s /etc/nginx/sites-available/bitbucket.example.net /etc/nginx/sites-enabled/bitbucket.example.net
# nginx -t
# /etc/init.d/nginx reload

Адаптация встроенного "Tomcat" для работы в спарке с "Nginx".

Начиная с "BitBucket Server v5" контейнеризатор Java-приложений "Apache Tomcat" полностью встраивается в дистрибутив приложения "BitBucket" и запускается таковым, а не отдельно конфигурируемой сущностью, как ранее. Вследствие глубокой интеграции настройки "Tomcat" полностью вынесены в контекст конфигурации "BitBucket", посредством которых и производится вывод web-сервиса за выставленный перед ним "прокси":

# vi /var/atlassian/appdata/bitbucket/shared/bitbucket.properties

....
# Move built-in Tomcat behind Nginx
server.address=127.0.0.1
server.port=7990
server.secure=true
server.scheme=https
server.proxy-port=443
server.proxy-name=bitbucket.example.net

# Disable analytics collects and sends it to Atlassian
analytics.aws.enabled=false
....

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

# service bitbucket restart

Удостоверимся, что перевод web-сервиса на работу только через "локальную петлю" состоялся успешно:

# netstat -apn | grep 7990

tcp ... 127.0.0.1:7990 0.0.0.0:* LISTEN 14734/java

Создание БД для web-приложения.

От имени суперпользователя СУБД "PostgreSQL" создаём выделенного для web-приложения пользователя и соответствующую "баз данных":

# su -l postgres
$ psql

Обращаю внимание на то, что при создании БД в "PostgreSQL" я всегда выбираю порядок сортировки "C"-подобный, как самый простой и не ломающийся от разнобоя между версиями кодовых таблиц (даже "одинаковые" UTF-8 от системы к системе различаются, как выясняется на практике).

В таблице выше заметны пустые поля параметра "Access privileges" - это потому, что в нашем случае создания БД для web-приложения единственный пользователь БД объявлен её владельцем и в дополнительных разрешениях не нуждается. Если потребуется дать доступ к БД иному пользователю, на то есть соответствующая SQL-команда, исполняемая в консоли "psql":

postgres=# GRANT ALL PRIVILEGES ON DATABASE bitbucketdb TO bitbucketdbuser;

Если потребуется сменить пароль пользователя, то делаем это там же, в консоли утилиты "psql":

postgres=# ALTER USER bitbucketdbuser WITH ENCRYPTED PASSWORD 'bitbucketdbuserPassword';

Сразу проверяем возможность соединения от имени созданного для инстанса "Atlassian BitBucket" пользователя с сервером БД, явно подключаясь на целевой TCP-порт:

# sudo -u bitbucket psql -h localhost -p 5432 -U bitbucketdb -W -d bitbucketdb

Первичная настройка web-приложения "Atlassian BitBucket".

После того, как все этапы предварительной подготовки окружения для web-приложения успешно пройдены, пришло время конфигурирования такового, производимого через web-интерфейс по адресу вроде "https://bitbucket.example.net/setup" посредством "мастера настройки". Там всё очевидно и практически не требует пояснений.

В самом начале, на странице "Bitbucket setup -> Welcome" потребуется указать тип "базы данных" для хранения настроек, и параметры подключения к ней. После успешной настройки подключения к БД соответствующие параметры попадут в конфигурационный файл "/var/atlassian/appdata/bitbucket/shared/bitbucket.properties", где могут быть изменены вручную при необходимости.

Ближе к концу установки, на странице "Bitbucket setup -> Licensing and settings" запрашивается лицензионный ключ, привязанный к созданному для этого конкретного несущего сервера "SERVER-ID". Лицензионный ключ генерируется на сайте разработчиков, на странице "My Atlassian -> New Evaluation License -> Product: BitBucket", и для доступа к этому функционалу там нужно иметь аккаунт. Само собой, лицензия может быть куплена, но на тестовый период в один месяц таковую можно запросить бесплатно.

Финальным действием на странице "Bitbucket setup -> Administrator account setup" web-инсталлятора мы заводим локального суперпользователя сайта.

Для аутентификации вначале проще ограничиться встроенной базой пользователей, но в дальнейшем на странице "Administration -> User Directories" можно воспользоваться дополнительными внешними сервисами аутентификации, вроде "Microsoft Active Directory", LDAP и "Atlassian Crowd" (подключение к таковым будет рассмотрено отдельно).

Уже после запуска web-сервиса в рабочем режиме наверняка потребуется настроить подсистему отправки электронной почты, на странице "Administration -> Mail server configuration" - там всё просто, достаточно лишь указать заранее заготовленный почтовый "релей".

Создание и тестирование Git-репозитория.

Создать проект, внутри него Git-репозиторий посредством web-интерфейса "BitBucket" настолько просто, что даже подсказку толком не сформулируешь. В общем, считаем, что проект "project" и внутри него репозиторий "site" уже заведены.

Загрузим в репозиторий что-нибудь:

$ cd ./site.example.net
$ git init
$ git add --all
$ git commit -m "Initial Commit"
$ git remote add origin https://bitbucket.example.net/scm/project/site.git
$ git push -u origin master

Username for 'https://bitbucket.example.net': git-user
Password for 'https://git-user@bitbucket.example.net':
Counting objects: 1492, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (1452/1452), done.
Writing objects: 100% (1492/1492), 128.28 MiB | 24.80 MiB/s, done.
Total 1492 (delta 295), reused 0 (delta 0)
remote: Resolving deltas: 100% (295/295), done.
To https://bitbucket.example.net/scm/project/site.git
* [new branch] master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.

Теперь в web-интерфейсе "BitBucket" можно пройти к репозиторию и побродить по веткам такового.

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

$ cd ./clone-site.example.net
$ git clone https://bitbucket.example.net/scm/project/site.git

Cloning into 'site'...
Username for 'https://bitbucket.example.net': git-user
Password for 'https://git-user@bitbucket.example.net':
warning: You appear to have cloned an empty repository.

Подключение к Git-репозиториям через SSH.

В "Atlassian BitBucket" встроен OpenSSH-сервер, по умолчанию принимающий подключения на порту TCP:7999 и обслуживающий только запросы Git-команд. Включение и параметры доступа просто настраиваются на странице "Administration -> Server settings -> SSH access".

Это может быть неочевидно, но в "BitBucket" доступ к репозиториям посредством SSH разрешён только с аутентификацией по "ключам" (SSH publickey). То есть, до обращения к Git-репозиторию в настройках аккаунта на странице "Account -> SSH keys" необходимо добавить соответствующий пользовательский "публичный ключ".

Пробуем клонировать себе тестовый репозиторий, используя в качестве транспортной среды SSH-туннель:

$ git clone ssh://git-user@bitbucket.example.net:7999/project/site.git

Cloning into 'site'...
remote: Counting objects: 1492, done.
remote: Compressing objects: 100% (1157/1157), done.
remote: Total 1492 (delta 295), reused 1492 (delta 295)
Receiving objects: 100% (1492/1492), 128.28 MiB | 34.21 MiB/s, done.
Resolving deltas: 100% (295/295), done.

О резервном копировании и восстановлении "Atlassian BitBucket".

Необходимо забирать следующее:

1. /etc - общесистемные настройки, в том числе и автозапуска "BitBucket";
2. /opt/atlassian/bitbucket - директория приложения (не обязательно, но быстрее восстановиться);
3. /var/atlassian/appdata/bitbucket - настройки и данные приложения;
4. /var/atlassian/appdata/bitbucket/shared/data/repositories - Git-репозитории как таковые;
5. Полный бинарный дамп БД.

Смело можно исключить некоторые временные ресурсы:

/var/atlassian/appdata/bitbucket/export
/var/atlassian/appdata/bitbucket/plugins
/var/atlassian/appdata/bitbucket/shared/data/db*
/var/atlassian/appdata/bitbucket/tmp

Русификация интерфейса web-приложения.

Перевод web-интерфейса "Atlassian BitBucket" на русский язык далеко не полный, но пользователи иногда хотят.

Идём на страницу загрузки пакетов локализации и скачиваем что-то вроде "bitbucket-language-pack-ru_RU-*.jar".

Применение элементарно - на странице "Administration -> Manage apps" загружаем JAR-архив как новое приложение.

BitBucket installation ( Установка и настройка web-сервиса "Atlassian BitBucket", предназначенного для хранения и управления Git-репозиториями. )

Заметки и комментарии к публикации: