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

Контейнер содержит только runtime: Debian, nginx, PHP-FPM, ionCube и необходимые PHP-модули.

Сам личный кабинет, конфигурация, лицензии и скрипты обновления располагаются в стандартных каталогах MikBill. Благодаря этому используется оригинальный ''stat_update.sh'' без изменений.

Документация разделена на три части:

1. Production-установка из Docker Hub.
2. Нюансы production-эксплуатации.
3. Создание и публикация своего runtime-образа.

---

===== 1. Production-установка из Docker Hub =====

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

На сервере должны быть установлены:

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

Проверка:

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

---

==== 1.2. Runtime-ветки и теги образов ====

Для production нельзя использовать общий образ вида:

<code text>
mikbill/cabinet:latest
</code>

Такой тег не показывает, какая версия PHP находится внутри образа. При переходе кабинета с PHP 7.x на PHP 8.x это может привести к ситуации, когда клиент случайно обновит runtime до несовместимой версии PHP.

Поэтому runtime-образы разделяются по веткам PHP:

<code text>
mikbill/cabinet-7x:latest    # runtime для кабинета на PHP 7.x
mikbill/cabinet-8x:latest    # runtime для кабинета на PHP 8.x, когда ветка будет готова
</code>

Текущая production-ветка:

<code text>
mikbill/cabinet-7x:latest
</code>

Внутри каждой ветки ''latest'' означает последнюю стабильную версию именно этой PHP-ветки. То есть ''cabinet-7x:latest'' никогда не должен внезапно стать PHP 8.x.

Для более строгой фиксации можно использовать версионные теги:

<code text>
mikbill/cabinet-7x:7.4.1
mikbill/cabinet-7x:<short_commit_sha>
</code>

---

==== 1.3. Клонирование docker-проекта ====

Выберите каталог, где будут храниться 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/mbcabinet_docker.git
</code>

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

<code bash>
cd /opt/mikbill/mbcabinet_docker
</code>

Все команды ''docker compose'' нужно выполнять именно из этого каталога, потому что здесь находятся:

<code text>
docker-compose.yml
.env
Dockerfile
docker/
scripts/
</code>

---

==== 1.4. Создание каталогов MikBill ====

Создаем стандартную структуру MikBill на хосте:

<code bash>
sudo mkdir -p /var/www/mikbill
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/stat
sudo mkdir -p /var/mikbill/www_backups
</code>

---

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

=== Free ===

<code bash>
cd /var/mikbill/updates/stat
sudo wget http://free.update.2x.mikbill.pro/stat_update.sh
sudo chmod +x stat_update.sh
</code>

=== Pay ===

<code bash>
cd /var/mikbill/updates/stat
sudo wget http://pay.update.2x.mikbill.pro/stat_update.sh
sudo chmod +x stat_update.sh
</code>

---

==== 1.6. Лицензия PAY ====

Для платной версии необходимо разместить файлы лицензии:

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

---

==== 1.7. Первичная установка личного кабинета ====

Запускаем штатный updater MikBill:

<code bash>
sudo /var/mikbill/updates/stat/stat_update.sh
</code>

После завершения должен появиться каталог:

<code text>
/var/www/mikbill/stat
</code>

---

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

Создать или скопировать файл:

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

В нем должны быть указаны параметры подключения к базе данных MikBill.

Пример:

<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/cabinet/error.log</error_log>
        <debug_log>/var/log/mikbill/cabinet/debug.log</debug_log>
    </parameters>
</config>
</code>

Если база находится на Docker-хосте, в ''stat.xml'' можно использовать:

<code xml>
<host>host.docker.internal</host>
</code>

В ''docker-compose.yml'' уже добавлен параметр:

<code yaml>
extra_hosts:
  - "host.docker.internal:host-gateway"
</code>

---

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

Перейдите в корень проекта с docker-файлами:

<code bash>
cd /opt/mikbill/mbcabinet_docker
</code>

Создайте ''.env'' из примера:

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

По умолчанию в ''.env.example'' указана текущая production-ветка PHP 7.x:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest
</code>

При необходимости можно зафиксировать конкретную версию:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:7.4.1
</code>

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

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

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

<code bash>
docker compose ps
</code>

Посмотрите логи:

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

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

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

---

==== 1.10. Проверка healthcheck ====

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

Ожидаемый ответ:

<code text>
HTTP/1.1 200 OK
</code>

---

===== 2. Нюансы production-эксплуатации =====

==== 2.1. Разделение ответственности ====

Проект разделяет приложение и runtime:

  * личный кабинет обновляется штатным ''stat_update.sh'';
  * Docker runtime обновляется через Docker Registry;
  * кастомная docker-версия updater не используется;
  * стандартные пути MikBill сохраняются;
  * команды ''docker compose'' выполняются из корня проекта, где лежит ''docker-compose.yml''.

---

==== 2.2. Используемые каталоги ====

| Каталог | Назначение |
|---|---|
| ''/opt/mikbill/mbcabinet_docker'' | Репозиторий с docker-файлами |
| ''/var/www/mikbill'' | Код личного кабинета |
| ''/var/www/mikbill/stat'' | Основной каталог личного кабинета |
| ''/var/mikbill/prod/config'' | Конфигурация, включая ''stat.xml'' |
| ''/var/mikbill/license'' | Лицензии PAY-версии |
| ''/var/mikbill/updates/stat'' | Оригинальный updater MikBill |
| ''/var/mikbill/www_backups'' | Резервные копии при обновлении |
| ''/var/log/mikbill'' | Логи MikBill |

---

==== 2.3. Обновление личного кабинета ====

Обновление приложения выполняется только штатным updater MikBill:

<code bash>
sudo /var/mikbill/updates/stat/stat_update.sh
</code>

Контейнер автоматически увидит обновленные файлы, поскольку используются bind mounts:

<code yaml>
/var/www/mikbill:/var/www/mikbill
/var/mikbill:/var/mikbill
/var/log/mikbill:/var/log/mikbill
</code>

Никаких дополнительных docker-команд после обновления кабинета выполнять не требуется.

---

==== 2.4. Обновление Docker runtime в рамках той же PHP-ветки ====

Runtime обновляется отдельно от приложения.

Для текущей ветки PHP 7.x:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest
</code>

Чтобы получить последнюю стабильную версию runtime внутри этой ветки:

<code bash>
cd /opt/mikbill/mbcabinet_docker
docker compose pull
docker compose up -d
</code>

Это обновит только контейнерное окружение. Код кабинета при этом не обновляется.

---

==== 2.5. Переход с PHP 7.x на PHP 8.x ====

Переход между major-ветками PHP нельзя делать простым обновлением ''latest''.

Нельзя заменять:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest
</code>

на:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-8x:latest
</code>

без проверки совместимости самого личного кабинета.

Правильный порядок перехода:

1. Убедиться, что версия личного кабинета поддерживает PHP 8.x.
2. Обновить личный кабинет штатным updater MikBill.
3. Проверить конфигурацию и совместимость модулей.
4. Изменить в ''.env'' runtime-образ:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-8x:latest
</code>

5. Перезапустить контейнер:

<code bash>
cd /opt/mikbill/mbcabinet_docker
docker compose pull
docker compose up -d
</code>

Если у клиента не оплачено обновление кабинета или он остается на ветке кабинета для PHP 7.x, нужно продолжать использовать:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest
</code>

---

==== 2.6. Почему не используется общий latest ====

Общий тег вида:

<code text>
mikbill/cabinet:latest
</code>

опасен для production, потому что со временем он может начать указывать на runtime с другой major-версией PHP.

Пример проблемы:

1. Клиент установил кабинет, совместимый только с PHP 7.x.
2. Позже ''mikbill/cabinet:latest'' был обновлен до PHP 8.x.
3. Клиент выполнил ''docker compose pull && docker compose up -d''.
4. Runtime обновился до PHP 8.x, а приложение осталось старым.
5. Кабинет может перестать работать.

Чтобы этого избежать, используются отдельные runtime-ветки:

<code text>
mikbill/cabinet-7x:latest
mikbill/cabinet-8x:latest
</code>

---

==== 2.7. Проверка после обновлений ====

<code bash>
cd /opt/mikbill/mbcabinet_docker
docker compose ps
docker compose logs --tail=100 cabinet
curl -i http://127.0.0.1/_health
</code>

Также рекомендуется проверить кабинет в браузере:

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

---

===== 3. Создание и публикация своего runtime-образа =====

Этот раздел нужен разработчикам и администраторам, которые собирают runtime-образ и публикуют его в Docker Hub / GitLab Registry.

Обычному пользователю production-инсталляции этот раздел не нужен.

---

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

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

<code bash>
cd /opt/mikbill/mbcabinet_docker
</code>

Соберите и запустите локальный runtime:

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

---

==== 3.2. Именование Docker Hub репозиториев ====

Runtime-образы публикуются в отдельные репозитории по major-веткам PHP:

<code text>
mikbill/cabinet-7x
mikbill/cabinet-8x
</code>

Ветка PHP 7.x:

<code text>
mikbill/cabinet-7x:latest
mikbill/cabinet-7x:7.4.1
mikbill/cabinet-7x:<short_commit_sha>
</code>

Ветка PHP 8.x:

<code text>
mikbill/cabinet-8x:latest
mikbill/cabinet-8x:8.5.0
mikbill/cabinet-8x:<short_commit_sha>
</code>

---

==== 3.3. GitLab CI/CD переменные ====

В GitLab необходимо создать переменные:

| Переменная | Значение |
|---|---|
| ''DOCKERHUB_USERNAME'' | логин Docker Hub, например ''mikbill'' |
| ''DOCKERHUB_TOKEN'' | Docker Hub Access Token |

Рекомендуемые настройки:

| Переменная | Visibility | Protected |
|---|---|---|
| ''DOCKERHUB_USERNAME'' | Visible | Да |
| ''DOCKERHUB_TOKEN'' | Masked | Да |

Пароль от Docker Hub использовать не нужно. Нужно использовать Personal Access Token.

---

==== 3.4. CI/CD: публикация образа ====

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

<code text>
Docker Hub:      mikbill/cabinet-7x
GitLab Registry: $CI_REGISTRY_IMAGE/cabinet-runtime-7x
</code>

Текущая runtime-ветка задается в ''.gitlab-ci.yml'':

<code yaml>
RUNTIME_BRANCH: "7x"
</code>

Для будущей ветки PHP 8.x нужно будет использовать отдельную ветку/репозиторий проекта и изменить:

<code yaml>
RUNTIME_BRANCH: "8x"
</code>

После этого pipeline начнет публиковать образы в:

<code text>
Docker Hub:      mikbill/cabinet-8x
GitLab Registry: $CI_REGISTRY_IMAGE/cabinet-runtime-8x
</code>

---

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

При push в ''main'' публикуются:

<code text>
mikbill/cabinet-7x:latest
mikbill/cabinet-7x:<short_commit_sha>
</code>

Аналогично в GitLab Registry:

<code text>
$CI_REGISTRY_IMAGE/cabinet-runtime-7x:latest
$CI_REGISTRY_IMAGE/cabinet-runtime-7x:<short_commit_sha>
</code>

При push git tag, например:

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

будут опубликованы:

<code text>
mikbill/cabinet-7x:7.4.1
mikbill/cabinet-7x:latest

$CI_REGISTRY_IMAGE/cabinet-runtime-7x:7.4.1
$CI_REGISTRY_IMAGE/cabinet-runtime-7x:latest
</code>

Для PHP 8.x схема будет аналогичной:

<code bash>
git tag v8.5.0
git push origin v8.5.0
</code>

<code text>
mikbill/cabinet-8x:8.5.0
mikbill/cabinet-8x:latest

$CI_REGISTRY_IMAGE/cabinet-runtime-8x:8.5.0
$CI_REGISTRY_IMAGE/cabinet-runtime-8x:latest
</code>

---

==== 3.6. Ручная публикация в Docker Hub ====

При необходимости образ можно собрать и отправить вручную:

<code bash>
docker login

docker build -t mikbill/cabinet-7x:7.4.1 .
docker tag mikbill/cabinet-7x:7.4.1 mikbill/cabinet-7x:latest

docker push mikbill/cabinet-7x:7.4.1
docker push mikbill/cabinet-7x:latest
</code>

---

===== 4. Раздел для корпоративной Wiki =====

==== Установка MikBill Cabinet Docker ====

1. Установить Docker, Docker Compose Plugin и Git.

2. Склонировать репозиторий:

<code bash>
sudo mkdir -p /opt/mikbill
sudo chown "$USER":"$USER" /opt/mikbill
cd /opt/mikbill
git clone <URL_РЕПОЗИТОРИЯ> mbcabinet_docker
cd /opt/mikbill/mbcabinet_docker
</code>

3. Создать каталоги MikBill:

<code bash>
sudo mkdir -p /var/www/mikbill
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/stat
sudo mkdir -p /var/mikbill/www_backups
</code>

4. Скачать оригинальный updater.

Free:

<code bash>
cd /var/mikbill/updates/stat
sudo wget http://free.update.2x.mikbill.pro/stat_update.sh
sudo chmod +x stat_update.sh
</code>

Pay:

<code bash>
cd /var/mikbill/updates/stat
sudo wget http://pay.update.2x.mikbill.pro/stat_update.sh
sudo chmod +x stat_update.sh
</code>

5. Для PAY-версии положить лицензии:

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

6. Выполнить первичную установку:

<code bash>
sudo /var/mikbill/updates/stat/stat_update.sh
</code>

7. Создать или скопировать конфиг:

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

8. Вернуться в корень docker-проекта:

<code bash>
cd /opt/mikbill/mbcabinet_docker
</code>

9. Создать ''.env'':

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

10. Проверить, что в ''.env'' указана нужная runtime-ветка:

<code env>
CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest
</code>

11. Запустить контейнер:

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

12. Проверить:

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

13. Открыть кабинет:

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

14. Для обновления кабинета использовать только штатный updater:

<code bash>
sudo /var/mikbill/updates/stat/stat_update.sh
</code>

15. Для обновления Docker runtime внутри текущей PHP-ветки:

<code bash>
cd /opt/mikbill/mbcabinet_docker
docker compose pull
docker compose up -d
</code>