====== MikBill Cabinet API Docker ======

Docker runtime для запуска MikBill Cabinet API.

Образ содержит только окружение:

  * Debian Bullseye slim
  * nginx
  * PHP-FPM 7.4
  * ionCube Loader
  * необходимые PHP-модули

Код Cabinet API, конфигурация, лицензии и скрипты обновления располагаются на хосте в стандартных каталогах MikBill. Это позволяет использовать оригинальный ''cabinetapi_update.sh'' без изменений.

----

===== Используемые образы =====

Для PHP 7.4 используется отдельная runtime-ветка:

<code>
mikbill/cabinetapi-runtime-7:latest
mikbill/cabinetapi-runtime-7:7.4.0
</code>

Общего образа вида:

<code>
mikbill/cabinetapi:latest
</code>

не используется, чтобы не смешивать разные PHP-ветки.

При появлении PHP 8 будет использоваться отдельный образ:

<code>
mikbill/cabinetapi-runtime-8:latest
</code>

----

====== 1. Production установка ======

===== Требования =====

  * Docker Engine
  * Docker Compose Plugin
  * Git
  * Доступ к серверам обновлений MikBill: ''*.update.2x.mikbill.pro''

Проверка:

<code bash>
docker --version
docker compose version
git --version
</code>

----

===== Клонирование репозитория =====

Выберите каталог для docker-файлов проекта:

<code bash>
sudo mkdir -p /opt/mikbill
sudo chown "$USER":"$USER" /opt/mikbill
cd /opt/mikbill
</code>

Склонируйте репозиторий:

<code bash>
git clone https://github.com/mikbill/mbcabapi_docker.git
cd /opt/mikbill/mbcabapi_docker
</code>

Создайте ''.env'':

<code bash>
cp .env.example .env
</code>

По умолчанию используется:

<code>
CABINETAPI_RUNTIME_IMAGE=mikbill/cabinetapi-runtime-7:latest
HTTP_PORT=80
</code>

----

===== Создание стандартных каталогов MikBill =====

<code bash>
sudo mkdir -p /var/www/cabinetapi
sudo mkdir -p /var/mikbill
sudo mkdir -p /var/log/mikbill

sudo mkdir -p /var/mikbill/prod/config
sudo mkdir -p /var/mikbill/license
sudo mkdir -p /var/mikbill/updates/cabinetapi
sudo mkdir -p /var/mikbill/www_backups
sudo mkdir -p /var/log/mikbill/cabinetapi
</code>

----

===== Настройка stat.xml =====

Создайте файл:

<code>
/var/mikbill/prod/config/stat.xml
</code>

Пример:

<code xml>
<config>
    <parameters>
        <mysql>
            <host>MySQL_IP_ADDRESS</host>
            <username>MySQL_USER</username>
            <password>MySQL_PASSWORD</password>
            <dbname>mikbill</dbname>
        </mysql>
        <mbdebug>false</mbdebug>
        <timezone>Europe/Kiev</timezone>
        <partialUTF8>false</partialUTF8>
        <error_log>/var/log/mikbill/cabinetapi/error.log</error_log>
        <debug_log>/var/log/mikbill/cabinetapi/debug.log</debug_log>
    </parameters>
</config>
</code>

----

===== Загрузка оригинального updater =====

Для установки официального updater можно использовать helper из репозитория:

<code bash>
cd /opt/mikbill/mbcabapi_docker
sudo ./scripts/install_official_update_script.sh
</code>

Или скачать вручную:

<code bash>
sudo mkdir -p /var/mikbill/updates/cabinetapi
cd /var/mikbill/updates/cabinetapi
sudo wget http://free.update.2x.mikbill.pro/cabinetapi_update.sh
sudo chmod +x cabinetapi_update.sh
</code>

----

===== Первичная установка Cabinet API =====

=== Free версия ===

<code bash>
cd /var/mikbill/updates/cabinetapi
sudo ./cabinetapi_update.sh
</code>

=== Pay версия ===

Поместите файлы лицензии:

<code>
/var/mikbill/license/client.key
/var/mikbill/license/serv.crt
</code>

Убедитесь, что IP сервера прописан в лицензии на стороне MikBill.

Выполните принудительное обновление:

<code bash>
cd /var/mikbill/updates/cabinetapi
sudo ./cabinetapi_update.sh -f
</code>

После установки должен появиться файл:

<code>
/var/www/cabinetapi/index.php
</code>

Проверка:

<code bash>
sudo ls -la /var/www/cabinetapi/index.php
</code>

----

===== Запуск контейнера =====

<code bash>
cd /opt/mikbill/mbcabapi_docker

docker compose pull
docker compose up -d
</code>

Проверить состояние:

<code bash>
docker compose ps
</code>

После запуска API должен быть доступен по адресу:

<code>
http://IP_СЕРВЕРА/
</code>

----

====== 2. Production эксплуатация ======

===== Проверка состояния =====

<code bash>
docker compose ps
docker compose logs --tail=100
</code>

Непрерывный просмотр логов контейнера:

<code bash>
docker compose logs -f
</code>

Проверка healthcheck:

<code bash>
curl -i http://127.0.0.1/_health
</code>

----

===== Логи Cabinet API =====

Логи располагаются на хосте:

<code>
/var/log/mikbill/cabinetapi/
</code>

Примеры:

<code bash>
sudo tail -100 /var/log/mikbill/cabinetapi/error.log
sudo tail -100 /var/log/mikbill/cabinetapi/debug.log
</code>

----

===== Обновление Cabinet API =====

Docker-образ при обновлении Cabinet API менять не требуется.

Используется штатный updater:

<code bash>
cd /var/mikbill/updates/cabinetapi
sudo ./cabinetapi_update.sh
</code>

Для принудительного обновления:

<code bash>
cd /var/mikbill/updates/cabinetapi
sudo ./cabinetapi_update.sh -f
</code>

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

<code bash>
cd /opt/mikbill/mbcabapi_docker
docker compose restart
</code>

----

===== Обновление runtime =====

Runtime — это Docker-образ с nginx, PHP-FPM, ionCube и PHP-модулями.

Для обновления runtime:

<code bash>
cd /opt/mikbill/mbcabapi_docker

docker compose pull
docker compose up -d
</code>

Код Cabinet API при этом не изменяется.

----

===== Смена runtime-ветки 7 → 8 =====

Когда появится PHP 8 runtime, достаточно поменять образ в ''.env'':

<code>
CABINETAPI_RUNTIME_IMAGE=mikbill/cabinetapi-runtime-8:latest
</code>

Затем выполнить:

<code bash>
docker compose pull
docker compose up -d
</code>

----

===== Перезапуск без обновления =====

<code bash>
docker compose restart
</code>

или

<code bash>
docker compose down
docker compose up -d
</code>

----

====== 3. Разработка runtime ======

Этот раздел нужен только для разработки Docker-окружения. Клиентам локальная сборка образа не требуется.

===== Локальная сборка =====

<code bash>
cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.build.yml build
</code>

Запуск локально собранного runtime:

<code bash>
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d
</code>

Логи:

<code bash>
docker compose logs -f
</code>

----

===== GitLab CI/CD =====

Pipeline собирает runtime-образ и публикует его:

  * в Docker Hub;
  * в GitLab Container Registry.

Основные переменные:

<code yaml>
RUNTIME_MAJOR: "7"
DOCKERHUB_IMAGE: mikbill/cabinetapi-runtime-${RUNTIME_MAJOR}
GITLAB_IMAGE: $CI_REGISTRY_IMAGE/cabinetapi-runtime-${RUNTIME_MAJOR}
</code>

Для PHP 7 публикуется:

<code>
mikbill/cabinetapi-runtime-7:latest
mikbill/cabinetapi-runtime-7:7.4.0
</code>

При появлении PHP 8 в соответствующей ветке проекта меняется:

<code yaml>
RUNTIME_MAJOR: "8"
</code>

После этого pipeline будет публиковать:

<code>
mikbill/cabinetapi-runtime-8:latest
</code>

----

===== Теги образов =====

Для релизов рекомендуется использовать git tags:

<code bash>
git tag v7.4.0
git push origin v7.4.0
</code>

Тег ''v7.4.0'' будет опубликован как Docker tag:

<code>
mikbill/cabinetapi-runtime-7:7.4.0
</code>

Также для текущей runtime-ветки обновляется:

<code>
mikbill/cabinetapi-runtime-7:latest
</code>

----

===== Проверка runtime-образа =====

Pipeline после публикации проверяет:

<code bash>
php -v
php -m | grep -i ioncube
</code>

Это подтверждает, что PHP и ionCube корректно работают внутри опубликованного образа.