# Установка балансировщика HAProxy

## Цель 

Установка балансировщика нагрузки HAProxy для кластерной конфигурации ПринтМенеджеров.

## Предусловия

- Подготовлена база PostgreSQL и NFS-хранилище.
- Получены дистрибутивы Мониторинга, ПринтМенеджера и Балансировщика с файлами контрольных сумм.

## Варианты развёртывания схемы с балансировкой

Возможно два варианта развёртывания схемы балансировки:
- массовое развертывание с помощью скрипта;
- ручное развёртывание.

## Шаги установки Массового развёртывания схемы с балансировкой

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

### Требования для выполнения массового развертывания

#### Подключение по SSH

- Сервер балансировщика должен иметь возможность подключаться к остальным серверам (ПринтМенеджеры и Мониторинг) по протоколу `SSH`.
- Для исключения необходимости ввода паролей, настройте SSH-аутентификацию с использованием ключа:
  - Создайте ключ SSH на сервере балансировщика (если его еще нет):​
    ```
    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
    ```
  - Скопируйте публичный ключ на все удаленные сервера:​
    ```
    ssh-copy-id root@<remote_server_IP>​
    ```

#### Подтверждение доверия SSH-сертификатов

- Перед запуском скрипта подключитесь к каждому серверу вручную из ВМ с балансировщиком:​
  ```
  ssh root@<remote_server_IP>
  ```
- Подтвердите добавление отпечатка сервера в файл доверенных хостов (`~/.ssh/known_hosts`).

#### Права пользователя

- Каждый сервер должен иметь пользователя с правами sudo.
- Для удобства и безопасности рекомендуется:
  - Создать отдельные служебные учетные записи
  - Отключить запрос пароля для команд с использованием `sudo`, добавив в конфигурацию `/etc/sudoers` соответствующую
строку:​
    ```
    <username> ALL=(ALL) NOPASSWD:ALL​​
    ```

#### Проверка конфигурации

Убедитесь, что файл config.ini заполнен корректно:
- Все необходимые секции (`[Balancer]`, `[Monitoring]`, `[PrintManager_1]` и т.д.) присутствуют.
- Значения переменных указаны без ошибок (путь к сертификатам, пароли, адреса и т.д.).
- Если некоторые сервера уже настроены, используйте параметр `SKIP = true` для их пропуска при развёртывании.

### Инструкция по запуску скрипта

1. Перейдите в директорию со скриптом массовой установки:​
   ```
   cd /path/to/script
   ```


2. Запустите скрипт:​
    ```
    sudo ./install_all_offline.sh
    ```

3. Если требуются детализированные логи для диагностики, используйте отладочный режим:​
    ```
    sudo DEBUG=1 ./install_all_offline.sh  
    ```

### Порядок установки

#### Шаг 1. Подготовка базы данных и NFS-хранилища​

Подготовка описана в разделах:
- [Установка PostgreSQL для кластера](https://wiki.printum.io/books/3-ustanovka/page/ustanovka-postgresql-dlia-klastera)
- [Установка NFS-хранилища](https://wiki.printum.io/books/3-ustanovka/page/ustanovka-nfs-xranilishha)

#### Шаг 2. Получение сертификатов

Если используются собственные SSL-сертификаты:
- Сгенерируйте или получите их у авторизованного центра сертификации (CA).
- Убедитесь, что пути к сертификатам (`SSL_CERT` и `SSL_KEY`) корректно указаны в конфигурационном файле.
- Если сертификаты корневого центра сертификации требуются, укажите путь к ним в `SSL_CERT_CA`.

#### Шаг 3. Запуск установки

##### Скопируйте дистрибутивы на сервер балансировщика

Скопируйте на сервер балансировщика дистрибутивы Мониторинга, ПринтМенеджера и Балансировщика вместе с файлами контрольных сумм:
- `printmanager-X1.Y1.Z1.tar.gz`
- `printmanager-X1.Y1.Z1.tar.gz.sha512`
- `printum-X2.Y2.Z2.tar.gz`
- `printum-X2.Y2.Z2.tar.gz.sha512`
- `printum-balancer-X3.Y3.Z3.tar.gz`
- `printum-balancer-X3.Y3.Z3.tar.gz.sha512`

##### Проверьте контрольные суммы

```
sha512sum -c <имя_файла>.sha512
```

##### Распакуйте архив балансировщика

```
tar xzvf printum-balancer-X3.Y3.Z3.tar.gz
cd printum-balancer-X3.Y3.Z3
```

##### Создайте файл конфигурации

```
cp config_example.ini config.ini
```

##### Отредактируйте файл config.ini

Внесите необходимые значения для каждой секции, указывая необходимые значения и опираясь на раздел "Описание конфигурационного файла".

Сохраните файл `config.ini`. Этот файл понадобится для будущих обновлений

##### Выполните установку

Используйте скрипт `install_all_offline.sh` с правами администратора:​
```
sudo ./install_all_offline.sh
```

Если при этом появляется ошибка `Permission denied`, сделайте файл исполняемым и повторите запуск:
```
chmod +x install_all_offline.sh
sudo ./install_all_offline.sh
```

##### Ожидайте завершения процесса установки

В случае необходимости введите пароль для подключения по SSH и копирования файлов с использованием SCP.

##### Проверьте корректность установки

Используйте раздел [Проверка корректности установки кластера](https://wiki.printum.io/books/3-ustanovka/page/proverka-korrektnosti-ustanovki-klastera).

## Описание конфигурационного файла

Конфигурационный файл config.ini используется для автоматического развёртывания и обновления системы. Он должен содержать обязательные секции, которые обозначаются квадратными скобками: `[General]`.

Каждая секция содержит параметры в формате `КОНСТАНТА = ЗНАЧЕНИЕ`. Между константой и её значением должен быть знак равенства, обрамлённый пробелами.
> **Пример**: `PM_HTTP_PORT = 8010`

Если константа не требует значения, её можно удалить, закомментировать или оставить пустой (с пробелом после знака равно).
> **Пример**: `SSL_CERT_CA =`

Файл должен включать не менее шести секций:
- `[General]`
- `[Balancer]`
- `[Monitoring]`
- `[PrintManager_1]`
- `[PrintManager_2]`
- `[PrintManager_N]`

#### Секция [General]

Секция `[General]` содержит общие параметры для всех серверов. Ниже приведён перечень доступных констант:
- `MON_DIST_PATH` — полный путь до дистрибутива мониторинга.
- `PM_DIST_PATH` — полный путь до дистрибутива PrintManager.
- `PM_HTTP_PORT` — порт для подключения к админке PrintManager по протоколу HTTP.
- `PM_HTTPS_PORT` — порт для подключения к админке PrintManager по протоколу HTTPS.
- `SSL_CERT_CA` — полный путь до корневого сертификата (CA certificate).
- `DATABASE_URL` — настройки для подключения к базе данных PrintManager PostgreSQL в формате URL:
    ```
    DATABASE_URL=postgres://<POSTGRES_LOGIN>:<POSTGRES_PASSWORD>@<DB_HOST>:<PORT>/<BASE_NAME>
    ```
    или со схемой базы данных:
    ```
    DATABASE_URL=postgres://<POSTGRES_LOGIN>:<POSTGRES_PASSWORD>@<DB_HOST>:<PORT>/<BASE_NAME>?currentSchema=<POSTGRES_SCHEMA>
    ```
  - `<POSTGRES_LOGIN>` — логин пользователя с необходимыми разрешениями (запись, удаление, чтение, обновление).
  - `<POSTGRES_PASSWORD>` — пароль пользователя.
  - `<DB_HOST>` — адрес сервера базы данных или балансировщика кластера.
  - `<PORT>` — порт для подключения к базе.
  - `<BASE_NAME>` — имя базы данных.
  - `<POSTGRES_SCHEMA>` — схема базы данных (опционально).
  - `<DATABASE_TABLESPACE>` — табличное пространство (указать, если не используется значение по умолчанию).​
- `NFS_ADDR` — IP-адрес или доменное имя для подключения к серверу NFS.
- `NFS_PATH` — полный путь к директории на сервере NFS.
- `NFS_TLS` (опционально) — укажите `1` или `true`, чтобы использовать шифрованное соединение с NFS. Если шифрование не используется, укажите `0` или `false`, либо удалите переменную.
- `NFS_STUNNEL_PORT` (опционально) — порт, указанный для Stunnel. Должен совпадать с портом в конфигурационном файле Stunnel. По умолчанию используется 20490.

#### Секция [Balancer]

Секция `[Balancer]` содержит параметры, необходимые для настройки сервера балансировки.

Доступные параметры:
- `EXT_HOSTNAME` — IP-адрес или hostname сервера балансировки.
- `SSL_CERT` — полный путь до сертификата.
- `SSL_KEY` — полный путь до закрытого ключа сертификата.
- `SKIP` (опционально) — флаг, указывающий, нужно ли пропустить установку или обновление на указанном сервере.
  - Если указано `false` (по умолчанию), установка выполняется.
  - Если указано `true`, выполнение команд на данном сервере будет пропущено.
- `STATS_USER` — логин пользователя для авторизации в панели администратора балансировщика.
- `STATS_PASSWORD` — пароль пользователя для доступа к странице статистики.

#### Секция [Monitoring]

Секция `[Monitoring]` содержит параметры для сервера, выделенного под систему мониторинга.

Доступные параметры:
- `MON_HOSTNAME` — IP-адрес или hostname сервера мониторинга.
- `USER` — пользователь с правами sudo или суперпользователь `root`.
- `PASSWORD` — пароль пользователя, указанного в параметре `USER`.
- `SSL_CERT` — полный путь до сертификата.
- `SSL_KEY` — полный путь до закрытого ключа сертификата.
- `SKIP` (опционально) — флаг, указывающий, нужно ли пропустить установку или обновление на данном сервере.
  - Если указано `false` (по умолчанию), установка выполняется.
  - Если указано `true`, выполнение команд на данном сервере будет пропущено. Пропустить (`SKIP = True`) можно в том случае, если нужно обновить только балансировщик и/или ПМы.

#### Секции [PrintManager_1], [PrintManager_2], ..., [PrintManager_N]

Секции `[PrintManager_X]` (где `X` — номер сервера) содержат настройки для подключения к соответствующим серверам с ПринтМенеджером.

Доступные параметры:
- `PM_HOSTNAME` — IP-адрес или hostname сервера ПринтМенеджера.
- `USER` — пользователь с правами sudo или суперпользователь `root`.
- `PASSWORD` — пароль пользователя, указанного в параметре `USER`.
- `SSL_CERT` — полный путь до сертификата.
- `SSL_KEY` — полный путь до закрытого ключа сертификата.
- `SKIP` (опционально) — флаг, указывающий, нужно ли пропустить установку или обновление на данном сервере.
  - Если указано `false` (по умолчанию), установка выполняется.
  - Если указано `true`, выполнение команд на данном сервере будет пропущено. Пропустить (`SKIP = True`) можно в том случае, если нужно обновить балансировщик и/или Мониторинг.

#### Шаги для добавления сервера

1. В секции `[Monitoring]` укажите параметр `SKIP = true`, чтобы предотвратить повторную установку мониторинга.
2. Для добавления 5 и более серверов с ПринтМенеджером добавьте в файл конфигурации необходимое количество секций, используя следующий шаблон:​
    ```​
    [PrintManager_ID]
    PM_HOSTNAME =
    USER =
    PASSWORD =
    SSL_CERT =
    SSL_KEY =
    ```
    где `ID` — порядковый номер сервера. Убедитесь, что номера серверов идут последовательно, без пропусков (например, [PrintManager_1], [PrintManager_2], [PrintManager_3] и т.д.).
3. Запустите скрипт массовой установки повторно. После выполнения скрипта в терминале отобразятся ссылки для доступа к админке новых серверов.
4. Проверьте корректность работы системы по [чек-листу](https://wiki.printum.io/books/3-ustanovka/page/proverka-korrektnosti-ustanovki-klastera).

## Шаги установки схемы балансировщика в ручном режиме

### Шаг 1. Скопируйте дистрибутивы на сервер балансировщика

Скопируйте на сервер балансировщика дистрибутивы Мониторинга, ПринтМенеджера и Балансировщика вместе с файлами контрольных сумм:
- `printmanager-X1.Y1.Z1.tar.gz`
- `printmanager-X1.Y1.Z1.tar.gz.sha512`
- `printum-X2.Y2.Z2.tar.gz`
- `printum-X2.Y2.Z2.tar.gz.sha512`
- `printum-balancer-X3.Y3.Z3.tar.gz`
- `printum-balancer-X3.Y3.Z3.tar.gz.sha512`

### Шаг 2. Проверьте контрольные суммы

```
sha512sum -c <имя_файла>.sha512
```

### Шаг 3. Распакуйте архив балансировщика

```
tar xzvf printum-balancer-X3.Y3.Z3.tar.gz
cd printum-balancer-X3.Y3.Z3
```

### Шаг 4. Настройте переменные окружения

Введите следующие команды для настройки (оставайтесь в этом же терминале до завершения установки):
```
export NFS_ADDR=<NFS_ADDR>
export NFS_PATH=<NFS_FOLDER_PATH>
export DATABASE_URL=postgres://<POSTGRES_LOGIN>:<POSTGRES_PASSWORD>@<DB_HOST>:<PORT>/<BASE_NAME>
```
Если требуется указать схему базы данных:
```
export DATABASE_URL=postgres://<POSTGRES_LOGIN>:<POSTGRES_PASSWORD>@<DB_HOST>:<PORT>/<BASE_NAME>?currentSchema=<POSTGRES_SCHEMA>
```
Если база использует нестандартное табличное пространство: 
```
export DATABASE_TABLESPACE=<DATABASE_TABLESPACE>
```

где:
- `<POSTGRES_LOGIN>` — логин пользователя с необходимыми разрешениями (запись, удаление, чтение, обновление).
- `POSTGRES_PASSWORD>` — пароль пользователя POSTGRES_LOGIN.
- `<DB_HOST>` — реальный адрес базы или балансировщика кластера баз.
- `<PORT>` — порт для подключения к базе.
- `<BASE_NAME>` — Имя базы.
- `<POSTGRES_SCHEMA>` — схема базы данных, указывать, если не используется схема public.
- `<DATABASE_TABLESPACE>` — Табличное пространство.
- `<NFS_ADDR>` — IP-адрес или доменное имя NFS сервера.
- `<NFS_FOLDER_PATH>` — путь директории NFS сервера.

Если вы настроили NFS через туннель stunnel, то обязательно укажите:
```
export NFS_TLS=true
```
Если порт stunnel отличается от 20490, то укажите еще порт:​
```​
export NFS_STUNNEL_PORT=<NFS_STUNNEL_PORT>
```
где:
- `NFS_STUNNEL_PORT` - порт для stunnel

Также вы можете указать логин и пароль для страницы HAProxy:
```
export STATS_USER=<STATS_USER>
export STATS_PASSWORD=<STATS_PASSWORD>
```
Если пароль и логин не указан, то будет установлен логин `admin` и пароль `admin`. Логин и пароль записаны в файле `/opt/printum_balancer/.env`.



### Шаг 5. Запустите установку

С автоматическими сертификатами:
```
sudo -E ./install.sh -balancer <BALANCER_ADR> -pm <PM_1> -pm <PM_2> -pm <PM_3>
```
С собственными сертификатами:
```
export SSL_CERT=<client.crt>
export SSL_KEY=<client.key>
export SSL_CERT_CA=<ca.crt>
sudo -E ./install.sh -balancer <BALANCER_ADR> -pm <PM_1> -pm <PM_2> -pm <PM_3>
```
где:
- `<BALANCER_ADR>` — IP адрес или доменное имя балансировщика.
- `<PM_1>` — IP адрес или доменное имя первого ПринтМенеджер.
- `<PM_2>`, `<PM_3>` , … — IP адрес или имя остальных ПринтМенеджеров.


## Ожидаемый результат

Если установка прошла без ошибок, то в консоли будет выведено сообщение об успехе и http-адрес для доступа к панели HAProxy:
```
Статус HAProxy доступен по адресу: https://BALANCER_ADR:7000/
```

Во время установки балансировщика будут автоматически записаны настройки для балансировщика и ПМов. Архивы находятся в директории `/opt/printum_balancer/certificates`.

## Как проверить установку

Откройте страницу по адресу `https://BALANCER_ADR:7000/`.

Вы увидите несколько групп строк, группы отделяются заголовками бордового цвета. Каждая группа обозначает часть системы и её статус. После установки всех ПМов строки станут зелеными.

## Следующие шаги

- [Установка первого ПринтМенеджера в кластере](https://wiki.printum.io/books/3-ustanovka/page/ustanovka-pervogo-printmenedzera-v-klastere)
- [Добавление серверов ПринтМенеджера в кластер](https://wiki.printum.io/books/3-ustanovka/page/dobavlenie-serverov-printmenedzera-v-klaster)

## Типовые ошибки

| Ошибка | Причина | Решение |
| ------ | ------- | ------- |
| Страница состояния балансировщика (HAProxy) и ПринтМенеджеров загружается с ошибкой. | Отсутствует или некорректен FQDN (hostname) в DNS для ВМ в составе конфигурации. | Проверить наличие и корректность FQDN (hostname) в DNS для всех ВМ в составе отказоустойчивой конфигурации. |

---

## Связанные страницы

- [Подготовка к установке кластера Active-Active](https://wiki.printum.io/books/3-ustanovka/page/podgotovka-k-ustanovke-klastera-active-active)
- [Установка PostgreSQL для кластера](https://wiki.printum.io/books/3-ustanovka/page/ustanovka-postgresql-dlia-klastera)
- [Установка NFS-хранилища](https://wiki.printum.io/books/3-ustanovka/page/ustanovka-nfs-xranilishha)
- [Установка первого ПринтМенеджера в кластере](https://wiki.printum.io/books/3-ustanovka/page/ustanovka-pervogo-printmenedzera-v-klastere)
- [Проверка корректности установки кластера](https://wiki.printum.io/books/3-ustanovka/page/proverka-korrektnosti-ustanovki-klastera)