Setting up a development environment for 1C-Bitrix

Setting Up a Development Environment for 1C-Bitrix

Developing Bitrix directly on a production server via FTP is risky — a single file edit can break the live site. A local environment with proper configuration allows developing offline, using a debugger, and testing database schema changes without fear.

Docker Environment for Bitrix

Docker is the most portable option: a single docker-compose.yml file gives all developers an identical environment.

Project structure:

project/
├── docker/
│   ├── php/
│   │   └── Dockerfile
│   ├── nginx/
│   │   └── default.conf
│   └── mysql/
│       └── my.cnf
├── docker-compose.yml
└── www/  ← site code

docker-compose.yml:

version: '3.8'

services:
  nginx:
    image: nginx:1.25-alpine
    ports:
      - "80:80"
    volumes:
      - ./www:/var/www/html
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - php

  php:
    build: ./docker/php
    volumes:
      - ./www:/var/www/html
      - ./docker/php/php.ini:/usr/local/etc/php/php.ini
    environment:
      PHP_IDE_CONFIG: "serverName=bitrix-local"

  mysql:
    image: mysql:8.0
    volumes:
      - mysql_data:/var/lib/mysql
      - ./docker/mysql/my.cnf:/etc/mysql/conf.d/bitrix.cnf
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: bitrix
      MYSQL_USER: bitrix
      MYSQL_PASSWORD: bitrix
    ports:
      - "3306:3306"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  mailpit:
    image: axllent/mailpit
    ports:
      - "8025:8025"
      - "1025:1025"

volumes:
  mysql_data:

Dockerfile for PHP with Bitrix Extensions

docker/php/Dockerfile:

FROM php:8.1-fpm

RUN apt-get update && apt-get install -y \
    libfreetype6-dev \
    libjpeg62-turbo-dev \
    libpng-dev \
    libwebp-dev \
    libzip-dev \
    libxml2-dev \
    libonig-dev \
    libmagickwand-dev \
    && rm -rf /var/lib/apt/lists/*

RUN docker-php-ext-configure gd \
    --with-freetype --with-jpeg --with-webp

RUN docker-php-ext-install \
    gd \
    mysqli \
    pdo_mysql \
    opcache \
    zip \
    soap \
    mbstring \
    bcmath \
    exif \
    intl

RUN pecl install imagick apcu xdebug \
    && docker-php-ext-enable imagick apcu xdebug

WORKDIR /var/www/html

Xdebug Configuration

In docker/php/php.ini for development:

[xdebug]
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM

; Do not enable on production!
[opcache]
opcache.enable = 0  ; Disable OPcache for development (validate_timestamps is slower)

In PHPStorm: Settings → PHP → Servers → add server named bitrix-local, host localhost, configure path mappings: /path/to/project/www → /var/www/html.

Copying Data from Production

To work with real data, you need a database and file copy:

# On production server — database dump
mysqldump -u bitrix -p bitrix_db \
  --single-transaction \
  --skip-lock-tables \
  --compress \
  --quick \
  | gzip > /tmp/bitrix_dump_$(date +%Y%m%d).sql.gz

# Download dump
scp server:/tmp/bitrix_dump_*.sql.gz ./

# Load into local MySQL
gunzip -c bitrix_dump_20240315.sql.gz | docker-compose exec -T mysql mysql -u bitrix -pbitrix bitrix

# Sync upload/ (only needed folders, exclude cache)
rsync -avz --exclude='*/resize_cache/' \
  server:/var/www/bitrix/upload/ \
  ./www/upload/

Configuring dbconn.php for Local Environment

Bitrix doesn't have a built-in .env mechanism, but you can use environment variables via Docker:

// bitrix/php_interface/dbconn.php
<?php
$DBType = "mysql";
$DBHost = getenv('DB_HOST') ?: 'mysql';
$DBLogin = getenv('DB_USER') ?: 'bitrix';
$DBPassword = getenv('DB_PASSWORD') ?: 'bitrix';
$DBName = getenv('DB_NAME') ?: 'bitrix';
$DBDebug = getenv('APP_ENV') === 'local';
$DBPersistent = false;

define("SITE_SERVER_NAME", getenv('SITE_HOST') ?: 'localhost');

Email Sending Configuration in Development

Mailpit (included in docker-compose.yml above) intercepts all outgoing mail. Configure in Bitrix:

// bitrix/php_interface/dbconn.php or init.php
define("BX_SMTP_SERVER", "mailpit");
define("BX_SMTP_PORT", 1025);

Or via Mail module settings in the admin panel — use SMTP, server mailpit:1025.

Mailpit web interface: http://localhost:8025 — all emails go there.

Code Synchronization Between Developers

For a team: Git + .gitignore as described in the deployment article. Most importantly — don't commit bitrix/modules/, upload/, .settings.php, dbconn.php with real passwords.

Hook post-merge to automatically clear cache after git pull:

# .git/hooks/post-merge
#!/bin/bash
docker-compose exec -T php php /var/www/html/deploy/clear_cache.php
echo "Cache cleared after merge"

chmod +x .git/hooks/post-merge