
### СУБД-КС "K"
###
### Copyright (c) 2024, ООО Кейсистемс
###
### Версия 14.13


  Описание           : Платформа для развертывания, управления и удаления экземпляра СУБД-КС 14.13,
                       реализованного в виде контейнера для работы в средах с поддержкой контейнеризации
                       Docker или Podman.

  Цель использования : Минимизировать издержки, связанные с разворачиванием и настройкой.

  Требует для работы : Docker-CE (Docker, Inc. лицензия Apache 2.0) или Podman (лицензия Apache 2.0), платформа linux/amd64.

  Характеристики     : Позволяет устанавливать один экземпляр СУБД-КС по указанному порту.
                       Диапазона используемых портов: 5432-5444.


I. Команды по созданию, удалению и просмотру состояния

 Внимание! Для выполнения нижеперечисленных операций и команд необходимы права суперпользователя.

 Важно !!! Перед началом установки необходимо спланировать с какими параметрами будет выполняться
           развертывание инстанса. Особое внимание следует уделить таким параметрам, как порт и
           локаль СУБД. В СУБД-КС "K" при разворачивании экземпляра СУБД-КС по умолчанию параметр порт принимает
           значение "5434", а параметр локали "ru_RU.utf8".


 1. Создание инстанса по умолчанию выполняется через запуск скрипта:
    $ ./install.sh

    Внимание: Для получения информации о параметрах по умолчанию, необходимо выполнить:
              $ ./install.sh --help

              параметры              по умолчанию   описание
              -------------------    ------------   ------------------------------------------------------
              -p  | --port           5434           порт СУБД

              -pwd| --password       1              пароль, который присваивается суперпользователям СУБД dbo и postgres

              -l  | --locale         ru_RU.utf8     локаль для инициализации кластера СУБД

              -shm| --shm_size       256MB          размер shared memory при создании контейнера

              -cs | --contsoft       docker         ПО контейнеризации (docker или podman)


   При разворачивании инстанса создается:
     - Файл инициализации по указанному порту    : /opt/dks-pgsqlks-14.13/sh/dks_init_var_<порт>.sh
     - Каталог данных инстанса СУБД по пути      : /var/lib/pgsqlks-14.13_<порт>
     - Каталог прикладных библиотек              : /opt/pgsqlks-14.13/lib/kslib/<порт>
     - Каталог утилит                            : /opt/pgsqlks-14.13/utility/<порт>
     - Сервис systemd                            : pgsqlks-14.13_<порт>.service,
                                                   для автоматического запуска контейнера с инстансом СУБД
                                                   после перезагрузки хоста
     - Специальный пользователь ks-postgres      : ID пользователя postgres внутри контейнера приравнивается к ID пользователя
                                                   ks-postgres на хосте.


   Примечание! Если в момент запуска разворачивания, каталог с данными /var/lib/pgsqlks-14.13_<порт> уже существует,
               то он просто монтируется "как есть", а не пересоздается.


 2. Просмотр процессов и состояния экземпляра СУБД-КС в контейнере выполняется через запуск скрипта с указание порта как параметра:
     # ./info.sh -p <порт>
     Если параметр не указан, то выводится общая информация по всем существующим экземплярам.

 3. Остановка контейнера с экземпляром СУБД-КС.
    $ systemctl stop pgsqlks-14.13_<порт>.service

 4. Запуск контейнера с экземпляром СУБД-КС.
    $ systemctl start pgsqlks-14.13_<порт>.service

 5. Удаление экземпляра СУБД-КС, установленного по умолчанию (порт 5434), выполняется через команду:
    $ ./uninstall.sh
    для удаления экземпляра, установленного по другому порту, отличного от 5434, необходимо выполнить:
    $ ./uninstall.sh -p 5432

    ВАЖНО!
    Примечание: При удалении инстанса СУБД, каталог с данными /var/lib/pgsqlks-14.13_<порт> НЕ УДАЛЯЕТСЯ!


II. Состав и структура.

 1. Образы и контейнеры в докере.

      Для каждого созданного инстанса СУБД-КС "K" по порту в используемом ПО контейнеризации разворачивается:
    Образ контейнера - pgsqlks-14.13_<порт>
    Контейнер        - pgsqlks-14.13_<порт>


 2. Структура прикладных каталогов для обеспечения работы экземпляров СУБД-КС, развернутых в контейнерах.

      Для обеспечения работы экземпляра СУБД-КС развернутого(ых) в контейнере(ах)
    на хосте дополнительно создается общий, смонтируемый в соотвествующий контейнер по порту,
    каталог для хранения разделяемых библиотек и вспомогательных модулей, а таккже соответствующие
    каталоги утилит.

    /opt/pgsqlks-14.13
          |- /lib
               |- /kslib
                     |- /<порт 1>
                          |- libxpks.so                - разделяемая библиотека расширенных функций
                          |- pg_dump                   - модуль резервного копирования
                          |- pg_restore                - модуль восстановления резервной копии
                     ................... 
                     |- /<порт N>
                          |- libxpks.so                - разделяемая библиотека расширенных функций
                          |- pg_dump                   - модуль резервного копирования
                          |- pg_restore                - модуль восстановления резервной копии


          |- /utility
               |- /<порт 1>
                     |- bash.sh                        - утилита для выполнения bash команд в контейнере pgsqlks-14.13_<порт 1>
                     |- psql.sh                        - утилита для выполнения SQL команд экземпляра СУБД в контейнере pgsqlks-14.13_<порт 1>
                     |- psr_repmgrd.sh                 - утилита настройки потоковой репликации
                     ....
                     |- sr_uninstall.sh                - утилита настройки потоковой репликации

               ...........
               |- /<порт N>
                     |- bash.sh                        - утилита для выполнения bash команд в контейнере pgsqlks-14.13_<порт N>
                     |- psql.sh                        - утилита для выполнения SQL команд экземпляра СУБД в контейнере pgsqlks-14.13_<порт N>
                     |- psr_repmgrd.sh                 - утилита настройки потоковой репликации
                     ....
                     |- sr_uninstall.sh                - утилита настройки потоковой репликации


  3. Структура каталога данных

    /var/lib/pgsqlks-14.13_<порт 1>
          |- /.ssh                                     - каталог для настройки и хранения конфигурации доступа по ssh в контейнер pgsqlks-14.13_<порт 1>
          |- /backups                                  - каталог для размещения резервных копий баз данных СУБД в контейнере pgsqlks-14.13_<порт 1>
          |- /data                                     - стандартный каталог данных СУБД в контейнере pgsqlks-14.13_<порт 1>
          |- /sr_ctl                                   - каталог утилит настройки и работы потоковой репликации
               |-/sql                                  - каталог с sql скриптами
          |- /ssl                                      - каталог для размещения сертификатов в контейнере pgsqlks-14.13_<порт 1>
               |-/certs

   /var/lib/pgsqlks-14.13_<порт N>
          |- /.ssh                                     - каталог для настройки и хранения конфигурации доступа по ssh в контейнер pgsqlks-14.13_<порт N>
          |- /backups                                  - каталог для размещения резервных копий баз данных СУБД в контейнере pgsqlks-14.13_<порт N>
          |- /data                                     - стандартный каталог данных СУБД в контейнере pgsqlks-14.13_<порт N>
          |- /sr_ctl                                   - каталог утилит настройки и работы потоковой репликации
               |-/sql                                  - каталог с sql скриптами
          |- /ssl                                      - каталог для размещения сертификатов в контейнере pgsqlks-14.13_<порт N>
               |-/certs


III. Неполадки и их устранение

     1. Ошибка            : could not resize shared memory segment "/PostgreSQL.1585716443

        Причина           : Default /dev/shm size for containers is xxMB
                            If the shared memory is exhausted you will encounter
                            ERROR: could not resize shared memory segment . . . : No space left on device.


        Возможное решение : Переопределить параметр "ShmSize"/"shmSize" для текущего контейнера в файле конфигурации
                            /var/lib/docker/containers/.../hostconfig.json   - для ПО контейнеризации Docker
                            /var/lib/containers/storage/libpod/bolt_state.db - для ПО контейнеризации Podman
                            (Для Podman исправление необходимо вносить непосредственно через API или boltbrowser - CLI Browser
                             для BoltDB файлов -> https://github.com/br0xen/boltbrowser)


                            При редактировании значения параметра, будьте внимательны, т.к при нарушении формата json
                            контейнер может не запуститься. Значение параметра указывается в байтах.
                            256 МБ = 256*1024*1024 = 268435456
                            512 МБ = 512*1024*1024 = 536870912

        Например          : Для развернутого инстанса СУБД pgsqlks-14.13 по порту 5438, контейнер
                            которого создан с параметром -shm=256MB, необходимо увеличить этот параметр
                            до 512MB. Для этого необходимо последовательно выполнить следующие действия:

                            1) Идентифицировать экземпляр, получив список запущенных контейнеров
                              $ docker ps -a

                                CONTAINER ID   IMAGE               COMMAND                  CREATED          STATUS                       PORTS     NAMES
                                b5d30b26ad09   pgsqlks-14.13_5438   "/bin/bash"              26 minutes ago   Exited (137) 9 minutes ago             pgsqlks-14.13_5438


                            2) Остановить СУБД-КС
                               $ systemctl stop pgsqlks-14.13_5438

                            3) Остановить ПО контейнеризации, например Docker
                               $ systemctl stop docker.service

                            4) Отредактировать файл конфигурации /var/lib/docker/containers/b5d30b26ad09.../hostconfig.json
                               (каталог нужного контейнера начинается с <CONTAINER ID>)

                                Найти и заменить значение "ShmSize":268435456  на "ShmSize":536870912

                            5) Запустить ПО контейнеризации, например Docker
                               $ systemctl stop docker.service

                            3) Запустить СУБД-КС
                               $ systemctl start pgsqlks-14.13_5438


     2. Ошибка            : при разворачивании контейнера не выполняются команды оболочки /bin/bash (ПО контейнеризации podman)


        Например          : STEP 3: RUN  mkdir -p /var/lib/pgsqlks-14.13_5438
                            error running container: error creating container for [/bin/sh -c mkdir -p /var/lib/pgsqlks-14.13_5438]:
                            time="2022-04-07T11:32:13+03:00" level=error msg="container_linux.go:367: exit status 1
                            Error: error building at STEP "RUN ls -la /etc": error while running runtime: exit status 1

        Возможное решение : Установить на OCI crun:  apt-get install crun (yum install crun)


