# BitrixDock: a Docker environment for developing Bitrix CMS

> BitrixDock assembles PHP, Nginx, MySQL or Percona and optional services into a Docker Compose stack for Bitrix CMS developers. Its own documentation puts a warning above everything else: it is built to look at a Bitrix demo, not to run a production site, and the defaults carry development settings such as xdebug.

**bitrixdock/bitrixdock** — BitrixDock - это готовое Docker окружение для Bitrix CMS :dart:

- Repository: https://github.com/bitrixdock/bitrixdock
- Website: https://bitrixdock.github.io/bitrixdock/
- Stars: 621 · Forks: 253
- Language: PHP
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/bitrixdock-bitrixdock

## The repository warns you off using it in production

The first line of substance in the documentation is a warning, and it is worth reading before anything else. This project is meant for looking at a Bitrix demo, not for running a production site, and the documentation points readers to examples of real production sites further down the page.

That framing sets expectations for everything else. BitrixDock starts a Bitrix CMS instance and provides ready made services: PHP, NGINX, MySQL and many others. The stated advantages are that the PHP service is packed into its own image so developers avoid a long compile, that the other services are preconfigured and deploy instantly, and that there is nothing superfluous in the stack.

The conclusion in the documentation is that if everything worked out, the project would be grateful for a star, and errors are collected as issues. The last push was on 2026-09-29, the repository is not archived, and it carries an MIT LICENSE file at the root. The licence covers the environment code, not the Bitrix CMS distribution you run inside it, which is separately licensed and requires a key to download.

## The compose file pins services to fixed container addresses

The architecture is a single `docker-compose.yml` with a small number of services, each built from a directory in the repository. The `php` service builds from `./php/${PHP_VERSION}` and mounts the site path at `/var/www/bitrix` along with a log directory and `/etc/localtime` mounted read-only. The `web_server` service builds from `./${WEB_SERVER_TYPE}`, which selects between nginx and apache, and publishes ports 80 and 443 on the configured interface.

Two details make this more than a plain compose file. First, the services are pinned to static addresses on a `bitrixdock` network: the web server sits at 172.18.0.9, the workspace at 172.18.0.12, and there are `extra_hosts` entries pointing `bitrix.local` at the web server address and at two push server addresses, 172.18.0.10 and 172.18.0.11. Those static addresses exist so Bitrix can be configured with hostnames that resolve the same way from inside and outside the containers.

Second, the ordering is explicit. The `php` service declares `depends_on` the `db` service with the condition `service_healthy`, and the web server depends on `php` with the same condition, so the stack starts in order rather than in parallel with a half ready database. The php service also runs with `no-new-privileges:true` and a tmpfs mounted at `/tmp`.

## Installing with install.sh or by copying the env template

Requirements are Git, Docker and Docker Compose v2. On Linux and macOS the automatic route downloads and runs the installer script:

```shell
curl -fsSL https://raw.githubusercontent.com/bitrixdock/bitrixdock/master/install.sh?$(date +%s) -o install.sh && chmod +x install.sh && sh install.sh
```

The script accepts an install path, defaulting to the current directory:

```shell
sh install.sh ~/projects
```

The manual route is to copy the environment template into place:

```shell
cp -f .env_template .env
```

That `.env` file is where the stack is configured. The template shipped in the repository looks like this:

```dotenv
COMPOSE_PROJECT_NAME=bitrixdock  # Имя проекта. Используется для наименования контейнеров
PHP_VERSION=php83                # Версия php (php56, php71, php73, php74, php80, php81, php82, php83, php84, php85)
PHP_WORKSPACE_VERSION=8.3        # Версия PHP для workspace контейнера
NODE_VERSION=24.21.0             # Версия Node.js для workspace контейнера
WEB_SERVER_TYPE=nginx            # Веб-сервер nginx/apache
DB_SERVER_TYPE=percona           # Сервер базы данных mysql/percona
MYSQL_VERSION=8.4                # Версия MySQL / Percona (8.0, 8.4)
MYSQL_DATABASE=bitrix            # Имя базы данных
MYSQL_USER=bitrix                # Пользователь базы данных
MYSQL_PASSWORD=123               # Пароль для доступа к базе данных
MYSQL_ROOT_PASSWORD=123          # Пароль для пользователя root от базы данных
INTERFACE=0.0.0.0                # На данный интерфейс будут проксироваться порты
SITE_PATH=./www                  # Путь к директории Вашего сайта
```

The comments in that file are in Russian, as the original documentation is, but the keys are plain environment variables. Note the default database passwords, which are the string 123, and the default interface of 0.0.0.0, which publishes the site on every network interface.

## Compose profiles gate the optional services

Not every service starts by default. The stack defines profiles for the optional pieces: an `admin` profile for Adminer, the web interface for database management, a `push` profile for the Bitrix push server together with Redis, and a `workspace` profile for the development tooling container.

Turning two of them on looks like this:

```shell
docker compose --profile admin --profile push up -d
```

And the workspace on its own:

```shell
docker compose --profile workspace up -d
```

Lifecycle is standard Compose. `docker compose up -d` starts everything, and the documentation tells you to check `docker ps` to confirm the services came up and `netstat -plnt` to see that ports 80, 11211 and 9000 are listening, then open the machine's IP address in a browser. To stop the stack use `docker compose stop`, and to remove it entirely use `docker compose down`.

The `Makefile` in the repository wraps the same operations with shorter targets, including `up`, `down`, `stop`, `build`, `ps`, and console targets such as `console-php`, `console-workspace`, `console-mysql` and `console-mysql-root`. It also carries three targets that download vendor scripts into the site path: `bitrix-setup` fetches bitrixsetup.php, `bitrix-restore` fetches restore.php, and `bitrix-server-test` fetches bitrix_server_test.php.

## The workspace container carries the developer tooling

The workspace service is described as a ready to work container with tools for development and debugging. It is built from the `workspace` directory with build arguments for the Node version and the workspace PHP version, it mounts the site path at `/var/www/bitrix`, and it mounts your SSH directory read-only into two locations. It also runs with a tty and is assigned the static address 172.18.0.12.

Inside, the documentation lists what is available: `php` as a PHP CLI with the needed extensions, `composer` as the PHP package manager, `node`, `npm`, `yarn` and `pnpm` for JavaScript work, `chef`, which is the Bitrix CLI tool, and `git`.

You get a shell in it like this:

```shell
docker compose exec -u www-data workspace zsh
```

Or through the Makefile, which runs the same command as the `console-workspace` target. The same Makefile offers `console-php` and `console-php-root` for the php service, and the two MySQL targets log in as the configured user or as root. Note that the workspace mounts `~/.ssh` into the container, which means anything that can run inside that container can read your private keys, a detail worth keeping in mind on a shared machine.

## Bitrix specific details that will bite you

Three details are specific to Bitrix and to this stack, and each one causes a support question if you do not know it in advance.

The first is the database hostname. In the connection settings you must give the name of the docker compose service, so the database is `db` and not `localhost`. The repository ships an example configuration at `configs/.settings.php` with connections to mysql and memcached. When you restore a backup into the container, the documented command pipes the dump straight in with `cat /var/www/bitrix/backup.sql | docker exec -i mysql /usr/bin/mysql -u root -p123 bitrix`.

The second is the platform quirk. On a Mac you should delete the `/etc/localtime:/etc/localtime/:ro` line from `docker-compose.yml`, which the documentation flags right after the environment copy step. The third is xdebug. Its settings live in `phpXX/php.ini`, and for php73 and php74 the default is to connect to port `9003` on the host that sent the request, falling back to `host.docker.internal` when the connection fails. If you change `php.ini` in the project, you have to add the `--build` flag when running `docker-compose` to force the image to be rebuilt.

And the production warning: when you move to production, delete the xdebug line from the corresponding `php/phpXX/Dockerfile`, because the mere presence of xdebug lowers the performance of Bitrix and it should only be used for development.

## MIT terms, no releases, and how it differs from the Bitrix virtual machine

The repository is MIT licensed, with the licence file at the root. The Bitrix CMS distribution you run inside it is not covered by that, and the `download.sh` script in the repository takes an edition and a licence key, for example `./download.sh business S12-NA-PMNBEUFJG1JH32C1`. The editions listed are `business`, `small_business`, `standard`, `start`, `bitrix24`, `bitrix24_enterprise` and `bitrix24_shop`. Those keys come from the vendor, not from this project.

There are no GitHub releases, so there is no tagged version to pin and no changelog attached to a tag. The last push was on 2026-09-29, and the repository is not archived. Practically, that means you track the default branch, which is `master`, and you pin your own environment by copying `.env` and the compose file into your own repository.

The documentation also compares BitrixDock with the virtual machine from the Bitrix developers, which solves the same problem of providing a ready environment. The stated difference is convenience: with the virtual machine you start it and get a mini hosting for the project, and when a new project appears you copy a clean virtual machine and the BitrixDock folder. The documentation also notes the vendor machine runs Apache while BitrixDock runs Nginx, which it says is faster and uses less memory. For a real production layout, the documentation points at a separate repository, bitrixdock/production-single-node.

## Conclusion

BitrixDock suits a developer or agency team that needs a repeatable Bitrix CMS stack on a laptop, wants Nginx and Percona instead of the vendor virtual machine, and is comfortable editing `.env` and `docker-compose.yml`. It does not suit a production deployment as shipped, because the documentation itself says so and the defaults include xdebug and loose database passwords. Before adopting it, change `MYSQL_PASSWORD` and `MYSQL_ROOT_PASSWORD` in `.env`, point the site at the `db` service name rather than localhost, and read the demo warning at the top of the repository documentation before you plan anything around it.

## FAQ

### Is BitrixDock suitable for production?

Not as shipped. The documentation puts a warning at the top saying the project is for viewing a Bitrix demo and not for running a production site. It also tells you to remove the xdebug line from `php/phpXX/Dockerfile` for production use, and the default database passwords in `.env` are the string 123.

### How do I install BitrixDock on Linux or macOS?

The automatic route downloads and runs install.sh from the repository. The manual route is to copy `.env_template` to `.env` and then start the stack with `docker compose up -d`. Git, Docker and Docker Compose v2 are the stated requirements.

### Which database and web server does BitrixDock use by default?

The defaults in `.env` are Nginx as the web server and Percona as the database server, with MySQL version 8.4, PHP 8.3 and database name, user and password all set to bitrix or 123. Both the web server type and the database server type are configurable through the same file.

### How do I enable the optional services such as Adminer or Redis?

They sit behind Compose profiles. Run `docker compose --profile admin --profile push up -d` to start Adminer and the push server with Redis, and `docker compose --profile workspace up -d` for the development tooling container.

### How do I restore a database backup into the BitrixDock container?

The documentation pipes the dump directly into the mysql container with `cat /var/www/bitrix/backup.sql | docker exec -i mysql /usr/bin/mysql -u root -p123 bitrix`. Note that the site must connect to the `db` service name rather than localhost, with an example in `configs/.settings.php`.

## Sources

- [bitrixdock/bitrixdock on GitHub](https://github.com/bitrixdock/bitrixdock)
- [Issues](https://github.com/bitrixdock/bitrixdock/issues)
- [License: MIT](https://github.com/bitrixdock/bitrixdock/blob/master/LICENSE)
- [Project website](https://bitrixdock.github.io/bitrixdock/)
- [README](https://github.com/bitrixdock/bitrixdock/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bitrixdock-bitrixdock