MikBill Cabinet Docker [MikBiLL]

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
Это полная версия инструкции. Инструкцию по быстрой установке смотри 
[[docker:cabinet_quickstart|здесь]]

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