MikBill Cabinet Docker

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

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

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

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

—

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

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

Проверка:

docker --version
docker compose version
git --version

—

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

mikbill/cabinet:latest

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

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

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

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

mikbill/cabinet-7x:latest

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

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

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

—

Выберите каталог, где будут храниться docker-файлы проекта.

Например:

sudo mkdir -p /opt/mikbill
sudo chown "$USER":"$USER" /opt/mikbill
cd /opt/mikbill

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

git clone https://github.com/mikbill/mbcabinet_docker.git

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

cd /opt/mikbill/mbcabinet_docker

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

docker-compose.yml
.env
Dockerfile
docker/
scripts/

—

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

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

—

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

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

—

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

/var/mikbill/license/client.key
/var/mikbill/license/serv.crt

—

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

sudo /var/mikbill/updates/stat/stat_update.sh

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

/var/www/mikbill/stat

—

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

/var/mikbill/prod/config/stat.xml

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

Пример:

<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>

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

<host>host.docker.internal</host>

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

extra_hosts:
  - "host.docker.internal:host-gateway"

—

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

cd /opt/mikbill/mbcabinet_docker

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

cp .env.example .env

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

CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest

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

CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:7.4.1

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

docker compose pull
docker compose up -d

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

docker compose ps

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

docker compose logs -f

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

http://IP_СЕРВЕРА/

—

curl -i http://127.0.0.1/_health

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

HTTP/1.1 200 OK

—

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

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

—

—

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

sudo /var/mikbill/updates/stat/stat_update.sh

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

/var/www/mikbill:/var/www/mikbill
/var/mikbill:/var/mikbill
/var/log/mikbill:/var/log/mikbill

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

—

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

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

CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest

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

cd /opt/mikbill/mbcabinet_docker
docker compose pull
docker compose up -d

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

—

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

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

CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest

на:

CABINET_RUNTIME_IMAGE=mikbill/cabinet-8x:latest

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

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

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

CABINET_RUNTIME_IMAGE=mikbill/cabinet-8x:latest

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

cd /opt/mikbill/mbcabinet_docker
docker compose pull
docker compose up -d

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

CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest

—

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

mikbill/cabinet:latest

опасен для 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-ветки:

mikbill/cabinet-7x:latest
mikbill/cabinet-8x:latest

—

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

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

http://IP_СЕРВЕРА/

—

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

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

—

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

cd /opt/mikbill/mbcabinet_docker

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

docker compose -f docker-compose.build.yml build
docker compose -f docker-compose.build.yml up -d

—

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

mikbill/cabinet-7x
mikbill/cabinet-8x

Ветка PHP 7.x:

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

Ветка PHP 8.x:

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

—

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

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

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

—

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

Docker Hub:      mikbill/cabinet-7x
GitLab Registry: $CI_REGISTRY_IMAGE/cabinet-runtime-7x

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

RUNTIME_BRANCH: "7x"

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

RUNTIME_BRANCH: "8x"

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

Docker Hub:      mikbill/cabinet-8x
GitLab Registry: $CI_REGISTRY_IMAGE/cabinet-runtime-8x

—

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

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

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

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

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

git tag v7.4.1
git push origin v7.4.1

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

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

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

git tag v8.5.0
git push origin v8.5.0

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

—

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

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

—

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

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

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

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

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

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

Free:

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

Pay:

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

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

/var/mikbill/license/client.key
/var/mikbill/license/serv.crt

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

sudo /var/mikbill/updates/stat/stat_update.sh

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

/var/mikbill/prod/config/stat.xml

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

cd /opt/mikbill/mbcabinet_docker

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

cp .env.example .env

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

CABINET_RUNTIME_IMAGE=mikbill/cabinet-7x:latest

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

docker compose pull
docker compose up -d

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

docker compose ps
curl -i http://127.0.0.1/_health

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

http://IP_СЕРВЕРА/

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

sudo /var/mikbill/updates/stat/stat_update.sh

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

cd /opt/mikbill/mbcabinet_docker
docker compose pull
docker compose up -d