Bitrix Docker Template

Docker-шаблон для локальной разработки PHP-проектов на базе 1С-Битрикс.

Стек: Nginx 1.29 · PHP-FPM 8.1–8.4 · MySQL 8.0–8.4 · Sphinx 2.2.11 · memcached 1.6

Требования

Docker + Docker Compose v2
make
wget (нужен для команд make setup / make restore)

Быстрый старт

git clone git@github.com:MiXaLiN17/bitrix-docker-template.git myproject.loc
cd myproject.loc
./create.sh

Скрипт интерактивно запросит:

Параметр	По умолчанию
Имя проекта	имя директории до первой точки
HTTP-порт	первый свободный в диапазоне 81–500
Версия PHP	8.4
Версия MySQL	8.4
Ставить ли Sphinx	нет
Ставить ли memcached	нет

После ответов create.sh автоматически создаст .env, соберёт Docker-образы и запустит контейнеры. Затем удалит себя — повторный запуск не требуется.

Проект будет доступен по адресу http://localhost:<порт>.

Управление проектом

make help   # показать все доступные команды

Запуск и остановка

Команда	Описание
`make build`	Собрать Docker-образы
`make up`	Запустить контейнеры
`make down`	Остановить контейнеры
`make restart`	Перезапустить контейнеры
`make rebuild`	Пересобрать и перезапустить
`make clean`	Удалить контейнеры, сети и volumes

Логи

Команда	Описание
`make logs`	Логи всех контейнеров
`make logs-web`	Логи Nginx
`make logs-app`	Логи PHP-FPM
`make logs-db`	Логи MySQL
`make logs-sphinx`	Логи Sphinx
`make logs-memcached`	Логи memcached
`make ps`	Статус контейнеров

Ошибки PHP пишутся не в make logs-app (там только лог самого FPM), а в файл ${APP_LOG_DIR}/error.log на хосте — по умолчанию ./logs/app/error.log. На страницу они не выводятся (display_errors = Off), в логе же включено всё, кроме E_DEPRECATED: предупреждения часто и есть настоящая причина падения, которое в самом коде выглядит как невнятный TypeError строкой ниже.

Shell

Команда	Описание
`make shell`	Shell в контейнер Nginx
`make shell-app`	Shell в контейнер PHP
`make shell-db`	Shell в контейнер MySQL
`make shell-sphinx`	Shell в контейнер Sphinx

Composer

make composer-install
make composer-update
make composer-require PACKAGE=vendor/package
make composer-remove  PACKAGE=vendor/package

База данных

Команда	Описание
`make mysql`	Подключиться к MySQL (root)
`make db-connect`	Подключиться к MySQL (пользователь из .env)
`make db-reset`	Пересоздать volume БД (все данные будут удалены!)

Версия MySQL

Задаётся при установке или переменной MYSQL_VERSION в .env. Один и тот же my.cnf проверен на всех пяти версиях — конфиг для них не различается.

Версия	Статус
`8.4`	LTS, рекомендуется Битриксом, поддержка до 2032 — значение по умолчанию
`8.3` / `8.2` / `8.1`	Innovation-релизы, сняты с поддержки; нужны, только чтобы повторить конфигурацию старого прода
`8.0`	LTS, минимальная версия для Битрикса

Битрикс требует минимум MySQL 8.0, рекомендованная версия — 8.4 и выше.

Менять версию на уже установленном проекте нельзя: каталог данных MySQL несовместим между версиями, особенно при откате назад. Смена версии требует make db-reset (данные удаляются) либо дампа и повторного импорта.

Sphinx

Команда	Описание
`make sphinx-enable`	Включить и запустить Sphinx
`make sphinx-disable`	Отключить Sphinx (индекс в volume сохранится)
`make sphinx-cli`	Консоль SphinxQL
`make sphinx-status`	Индексы, число документов и статистика демона
`make sphinx-truncate`	Очистить индекс (после нужна переиндексация в админке)

memcached

Команда	Описание
`make memcached-enable`	Включить и запустить memcached
`make memcached-disable`	Отключить memcached (кеш будет потерян)
`make memcached-stats`	Объём кеша, попадания, промахи, вытеснения
`make memcached-flush`	Очистить весь кеш

Полнотекстовый поиск Sphinx

Sphinx — опциональный сервис, по умолчанию выключен. create.sh спрашивает про него при установке, включить или выключить позже можно в любой момент:

make sphinx-enable    # соберёт образ и поднимет контейнер
make sphinx-disable   # удалит контейнер, индекс в volume останется

Технически это профиль Docker Compose: переменная COMPOSE_PROFILES в .env. Пока она пустая, make up и make build вообще не видят сервис — образ не собирается и место не занимает.

Используется Sphinx 2.2.11 — та же версия, что поставляется в BitrixVM. Поддержка Sphinx появилась в 1С-Битрикс с версии 14.0.0, поддерживаются версии от 2.1.1 до 3.x, при этом ветка 3.x работает только с модулем «Поиск» 25.0.0 и выше. Версия 2.2.11 совместима со всеми актуальными редакциями и не требует проверки версии модуля, поэтому выбрана по умолчанию.

Начиная со Sphinx 2.2.2 поддерживается только UTF-8 — на сайтах в windows-1251 поиск работать не будет (Битрикс с версии 24.0.0 в любом случае работает только в UTF-8).

Образ собран на ubuntu:24.04, потому что sphinxsearch 2.2.11 остался в репозиториях только у Ubuntu (из Debian пакет выпилен, в Alpine его нет). Готовый образ весит 117 МБ — для сравнения, mysql:8.4 в этом же стеке весит 790 МБ. Сборка — это один apt-get install без компиляции, около 30 секунд. Пакет собран под amd64 и arm64, так что образ работает и на Apple Silicon.

Настройка в админке Битрикса

Настройки → Настройки продукта → Настройки модулей → Поиск, вкладка Морфология:

Параметр	Значение
Полнотекстовый поиск с помощью	`Sphinx`
Строка подключения для управления индексом (протокол MySql)	`sphinx:9306`
Идентификатор индекса	`bitrix`

После сохранения Битрикс предложит выполнить полную переиндексацию модуля «Поиск» — её нужно выполнить, индекс наполняет сам Битрикс через SphinxQL.

Подключение идёт по протоколу MySQL через расширение mysqli — оно уже установлено в контейнере app, дополнительные PHP-расширения не нужны.

Конфигурация

Файл .docker/sphinx/conf/sphinx.conf. Схема RT-индекса (поля title / body и атрибуты module_id, item_id, site, right и т.д.) задана ядром Битрикса — менять её нельзя. Настраивать можно морфологию, min_prefix_len и лимиты памяти.

Индекс и бинлог лежат в volume ${COMPOSE_PROJECT_NAME}-sphinx и переживают пересоздание контейнера. Порт наружу не пробрасывается: контейнер app ходит в sphinx:9306 внутри сети docker. Если нужен доступ с хоста — раскомментируйте секцию ports у сервиса sphinx в docker-compose.yml.

Обновление шаблона на проекте, где Sphinx уже работал

Раньше контейнер Sphinx работал от root и создавал файлы индекса с владельцем root:root. Теперь демон запускается от непривилегированного пользователя с UID/GID хоста, поэтому старые файлы ему недоступны и контейнер после обновления не поднимется:

WARNING: index 'bitrix': preload: failed to open /var/lib/sphinxsearch/data/bitrix.lock: Permission denied; NOT SERVING
FATAL: no valid indexes to serve

Лечится сменой владельца файлов в volume — индекс при этом сохраняется, переиндексация не нужна:

make sphinx-disable
docker run --rm -u 0:0 -v $(grep '^COMPOSE_PROJECT_NAME=' .env | cut -d= -f2)-sphinx:/data \
    alpine chown -R $(id -u):$(id -g) /data
make sphinx-enable

Если индекс не жалко, можно просто пересоздать volume — тогда после запуска понадобится полная переиндексация из админки (Настройки → Поиск → Переиндексация):

make sphinx-disable
docker volume rm $(grep '^COMPOSE_PROJECT_NAME=' .env | cut -d= -f2)-sphinx
make sphinx-enable

Новых установок это не касается: volume создаётся сразу с правильным владельцем.

Кеш memcached

memcached — опциональный сервис, по умолчанию выключен, как и Sphinx:

make memcached-enable    # поднимет контейнер
make memcached-disable   # удалит контейнер

Нужен, когда bitrix/.settings.php переехал с прода вместе с настройкой кеша. Без сервера кеша Битрикс падает ещё до первого запроса к нему:

[Bitrix\Main\NotSupportedException] memcache extension is not loaded. (150)
/bitrix/modules/main/lib/data/configurator/memcacheconnectionconfigurator.php:20

Расширения PHP memcache и memcached установлены в образе всегда — на этом сообщении сайт не остановится независимо от того, поднят контейнер или нет. memcache и memcached — два разных расширения, а не версии одного, и Битриксу они дают разные движки кеша: CacheEngineMemcache (подключение через MemcacheConnection) и CacheEngineMemcached (через MemcachedConnection).

Настройка в Битриксе

Начиная с версии 18.5.200 — той же, в которой появилась поддержка Redis, — type в .settings.php задаётся массивом с классом движка и именем расширения. Старая короткая запись ('type' => 'memcache') ядром по-прежнему понимается, но в новых конфигурациях лучше использовать актуальный формат:

'cache' => [
    'value' => [
        'type' => [
            'class_name' => '\\Bitrix\\Main\\Data\\CacheEngineMemcache',
            'extension' => 'memcache',
        ],
        'memcache' => [
            'host' => 'memcached',
            'port' => '11211',
        ],
        'sid' => $_SERVER['DOCUMENT_ROOT'] . '#01',
    ],
    'readonly' => false,
],

Ключ с параметрами подключения (memcache) должен совпадать со значением extension: ядро ищет host/port именно в $cacheConfig[$extension]. Для расширения memcached это соответственно 'class_name' => '\\Bitrix\\Main\\Data\\CacheEngineMemcached', 'extension' => 'memcached' и секция 'memcached' => [...].

У нового формата есть побочный плюс: по ключу extension ядро проверяет расширение до создания движка (Bitrix\Main\Data\Cache::createCacheEngine()) и, если его нет, откатывается на CacheEngineNone с предупреждением Cache engine is not found в логе. Старая короткая запись такой проверки не делает и роняет сайт фатальным NotSupportedException.

host — это имя сервиса из docker-compose.yml, то есть memcached. Приехавший с прода 127.0.0.1 указывает на сам контейнер с PHP, где сервера кеша нет.

Если сервер кеша на локальной машине не нужен, замените движок на файловый — Битрикс будет складывать кеш в bitrix/cache, и контейнер не понадобится:

'type' => [
    'class_name' => '\\Bitrix\\Main\\Data\\CacheEngineFiles',
],

Конфигурация

Потолок памяти под кеш задаётся переменной MEMCACHED_MEMORY в .env (по умолчанию 256 МБ). При исчерпании лимита memcached вытесняет старые записи, а не отдаёт ошибку, поэтому значение влияет на процент попаданий — его видно в make memcached-stats (get_hits / get_misses / evictions).

Volume у сервиса нет: кеш по определению одноразовый, после перезапуска контейнера он просто пуст. Порт наружу не пробрасывается — в memcached нет аутентификации, доступ есть только у контейнеров внутри сети docker.

Переменные окружения

Файл .env создаётся из .env.example скриптом create.sh. Основные переменные:

Переменная	Описание
`COMPOSE_PROJECT_NAME`	Префикс имён контейнеров
`COMPOSE_PROFILES`	Опциональные сервисы через запятую: пусто, `sphinx`, `memcached`
`PHP_VERSION`	Версия PHP (8.1 / 8.2 / 8.3 / 8.4)
`MYSQL_VERSION`	Версия MySQL (8.0 / 8.1 / 8.2 / 8.3 / 8.4)
`MEMCACHED_VERSION`	Версия образа memcached
`MEMCACHED_MEMORY`	Потолок памяти memcached под кеш, МБ
`HOST_MACHINE_UNSECURE_HOST_PORT`	Внешний HTTP-порт
`MYSQL_DATABASE`	Имя базы данных
`MYSQL_USER`	Пользователь MySQL
`MYSQL_PASSWORD`	Пароль пользователя MySQL
`MYSQL_ROOT_PASSWORD`	Пароль root MySQL
`APP_LOG_DIR`	Путь к логам PHP на хосте
`WEB_SERVER_LOG_DIR`	Путь к логам Nginx на хосте
`MYSQL_LOG_DIR`	Путь к логам MySQL на хосте
`SPHINX_LOG_DIR`	Путь к логам Sphinx на хосте
`UID` / `GID`	ID пользователя хоста, под которым работают процессы в контейнерах

Пользователи в контейнерах и права на файлы

create.sh подставляет в .env ваши UID и GID, и сервисы работают именно под ними. Благодаря этому файлы в src/ и logs/, созданные из контейнеров, принадлежат вам — их можно править и удалять без sudo, а PHP пишет в каталог сайта без возни с правами.

Сервис	Процесс	От кого работает
`webserver`	`nginx` (мастер и воркеры)	пользователь `nginx` с `UID`/`GID` хоста
`app`	воркеры `php-fpm`	пользователь `www-data` с `UID`/`GID` хоста
`app`	мастер `php-fpm`	`root` — штатная схема php-fpm, логи пишут воркеры
`sphinx`	`searchd`	пользователь `sphinxsearch` с `UID`/`GID` хоста
`db`	`mysqld`	пользователь `mysql` из официального образа

Nginx работает без root целиком, включая мастер-процесс. Обычно для этого приходится переносить сервис на порт 8080, но здесь бинарнику выдана capability cap_net_bind_service — она входит в набор Docker по умолчанию, поэтому контейнер по-прежнему слушает штатный порт 80 и наружу ничего не меняется. Побочный эффект в том, что nginx не может писать pid-файл в /run, поэтому тот перенесён в /var/run/nginx/, а директива user из nginx.conf убрана — непривилегированный мастер её игнорирует.

UID/GID передаются как аргументы сборки, а не через окружение контейнера. Если поменять их в .env на уже собранном проекте, образы нужно пересобрать — иначе изменения не подхватятся:

make rebuild

Установка и восстановление Битрикс

Новая установка

make setup

Скачивает bitrixsetup.php в ./src/. Открыть в браузере: http://localhost:<порт>/bitrixsetup.php.

Восстановление из резервной копии

make restore

Скачивает restore.php в ./src/. Открыть в браузере: http://localhost:<порт>/restore.php.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.docker		.docker
src		src
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
create.sh		create.sh
docker-compose.yml		docker-compose.yml

Navigation Menu

Repository files navigation

Bitrix Docker Template

Требования

Быстрый старт

Управление проектом

Запуск и остановка

Логи

Shell

Composer

База данных

Версия MySQL

Sphinx

memcached

Полнотекстовый поиск Sphinx

Настройка в админке Битрикса

Конфигурация

Обновление шаблона на проекте, где Sphinx уже работал

Кеш memcached

Настройка в Битриксе

Конфигурация

Переменные окружения

Пользователи в контейнерах и права на файлы

Установка и восстановление Битрикс

Новая установка

Восстановление из резервной копии

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Bitrix Docker Template

Требования

Быстрый старт

Управление проектом

Запуск и остановка

Логи

Shell

Composer

База данных

Версия MySQL

Sphinx

memcached

Полнотекстовый поиск Sphinx

Настройка в админке Битрикса

Конфигурация

Обновление шаблона на проекте, где Sphinx уже работал

Кеш memcached

Настройка в Битриксе

Конфигурация

Переменные окружения

Пользователи в контейнерах и права на файлы

Установка и восстановление Битрикс

Новая установка

Восстановление из резервной копии

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages