Урок 1. Разворачиваем стенд и знакомимся с проектом

Команда начинает работу над сайтом мероприятий на Bitrix Framework. Первая задача — поднять рабочее окружение, где можно писать и проверять код. Вторая — договориться, где этот код будет лежать.

Вторая задача важнее, чем кажется. Продукт регулярно обновляется, и обновления перезаписывают системные файлы. Если положить свой код не туда, следующее обновление его сотрет. Поэтому мы не только установим продукт, но и разберемся, какие папки ваши, а какие принадлежат системе.

Поднимаем окружение в Docker

Для стенда используем официальное контейнерное окружение env-docker. В нем уже настроены PHP, веб-сервер nginx, базы данных MySQL и PostgreSQL, cron и другие сервисы, которые нужны продукту. Собирать окружение вручную не придется.

Перед началом установите Docker Desktop для Windows или macOS либо Docker Engine для Linux.

1. Склонируйте репозиторий окружения в папку проекта:

   git clone https://github.com/bitrix-tools/env-docker.git
   cd env-docker

2. Задайте пароли баз данных в файлах .env_mysql и .env_postgresql, а секретный ключ Push-сервера — в файле .env_push. Команды для генерации паролей и ключа есть в README репозитория.
3. Запустите контейнеры:

   docker compose up -d

4. Проверьте, что контейнеры запустились:

   docker compose ps

   В колонке SERVICE должны быть php, nginx, mysql и другие, в колонке STATUS — Up.

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

Продукт устанавливают скриптом bitrixsetup.php. Скрипт скачивает дистрибутив выбранной редакции и запускает мастер установки.

1. Войдите в консоль контейнера php под пользователем bitrix:

   docker compose exec --user=bitrix php sh

   Пользователь bitrix важен. Под ним работает PHP, и файлы сайта должны принадлежать ему. Если создать файлы под root, сайт не сможет их изменить.

2. Перейдите в корневую папку сайта и скачайте скрипт:

   cd /opt/www/
   wget https://www.1c-bitrix.ru/download/scripts/bitrixsetup.php

3. Откройте в браузере http://<адрес>:8588/bitrixsetup.php, где <адрес> — IP-адрес или домен вашего стенда.
4. Выберите продукт 1С-Битрикс: Управление сайтом и редакцию Бизнес. В ней есть все модули, которые понадобятся в курсе.
5. Дождитесь загрузки. Запустится мастер установки.

В мастере пройдите шаги по порядку:

1. Примите лицензионное соглашение.
2. На шаге регистрации заполните поля, чтобы получить пробную версию.
3. Посмотрите результаты проверки системы. Красным выделены параметры, которые нужно исправить. В окружении env-docker их быть не должно.
4. Заполните параметры базы данных MySQL:

   Поле	Значение
   Сервер	mysql — имя контейнера с базой данных
   Пользователь базы данных	Существующий, логин root
   Пароль	Значение MYSQL_ROOT_PASSWORD из файла .env_mysql
   База данных	Новая, имя sitemanager
   Параметры администратора базы данных -> Логин	root
   Параметры администратора базы данных -> Пароль	Тот же пароль из .env_mysql

   В форме два пользователя. Под пользователем базы данных сайт будет постоянно подключаться к базе — его логин и пароль мастер запишет в настройки сайта. Под администратором базы данных мастер один раз создает базу. В MySQL окружения env-docker есть только пользователь root, поэтому в обоих блоках один логин и один пароль.

5. Дождитесь, пока мастер создаст таблицы и скопирует файлы.
6. Создайте учетную запись администратора. Логин и пароль понадобятся на протяжении всего курса.
7. На шаге выбора решения откажитесь от готового решения. Курс строит сайт с нуля, и демоданные интернет-магазина или корпоративного сайта будут только мешать. Закройте мастер и удалите файл index.php из корня сайта. Это файл установщика: пока он есть, главная страница сайта снова открывает мастер установки.

После установки откройте http://<адрес>:8588/bitrix/admin/ и войдите под администратором. Если открылся административный раздел, продукт установлен.

Выбираем, как работать с файлами сайта

В окружении env-docker файлы сайта лежат не в папке на вашем компьютере, а в томе Docker внутри контейнера php. Поэтому редактор на компьютере их не видит. Работать с ними можно двумя способами. Выберите любой — на ход курса выбор не влияет.

Без дополнительных программ: редактор в административном разделе

В продукте есть встроенный файловый менеджер с редактором кода. Он работает в браузере и создает файлы от имени того же пользователя, что и сайт.

1. Откройте Контент > Структура сайта > Файлы и папки.
2. Перейдите в нужную папку. Новые папки и файлы создают кнопками на панели над списком.
3. Чтобы изменить PHP-файл, откройте меню действий у файла и выберите Редактировать как PHP. Это действие доступно пользователям с правом редактировать PHP-код, у администратора оно есть.

Консольные команды запускайте внутри контейнера php, как при установке продукта:

docker compose exec --user=bitrix php sh

С расширением: VS Code и Dev Containers

Если вы привыкли к IDE, VS Code можно подключить прямо к контейнеру. Тогда файлы сайта открываются как обычная папка проекта, а встроенный терминал работает внутри контейнера.

1. Установите в VS Code расширение Dev Containers от Microsoft.
2. Откройте палитру команд и выполните Dev Containers: Attach to Running Container....
3. Выберите контейнер с PHP. В окружении env-docker он называется dev_php.
4. В новом окне откройте папку /opt/www.

При первом подключении VS Code скачивает и устанавливает в контейнер свой сервер. Это занимает несколько минут. Затем расширения для PHP, например для подсветки и автодополнения, ставятся уже внутри контейнера. VS Code работает в контейнере от имени пользователя bitrix, поэтому созданные файлы сайт сможет изменить.

Так же к контейнеру подключаются и другие IDE, например PhpStorm. Как их настроить, смотрите в документации IDE.

Разбираемся в структуре папок

Откройте корневую папку сайта. В контейнере php это /opt/www/. В корне сайта три главные папки. Две из них создает установка, а /local/ вы создаете сами:

Публичные страницы сайта лежат в корне рядом с этими папками. Например, раздел /events/ — это папка /events/ с файлом index.php. Страницы мы начнем создавать в уроке 2.

Главное правило: свой код — в /local

Обновления продукта перезаписывают файлы в /bitrix/. Поэтому ядро не меняют, даже если нужная правка выглядит маленькой. Изменения в ядре теряются при первом обновлении, а сайт с измененным ядром лишается права на техническую поддержку.

Под запретом прежде всего:

• /bitrix/modules/ — модули продукта
• /bitrix/components/bitrix/ — системные компоненты
• /bitrix/js/ — JavaScript продукта
• /bitrix/routes/ — системные маршруты

Весь свой код кладите в /local/. Система не трогает эту папку при обновлениях. В ней повторяется часть структуры /bitrix/:

/local/
├── components/      // свои компоненты
├── modules/         // свои модули
├── templates/       // шаблоны сайта и шаблоны компонентов
├── php_interface/   // файл init.php и служебные файлы
└── routes/          // маршруты

Если файл с тем же путем есть и в /local/, и в /bitrix/, система берет версию из /local/. Так можно переопределить, например, шаблон компонента, не трогая системный. Копировать файлы ядра в /local/ целиком не стоит: дубли усложняют поддержку, и вы перестаете получать исправления из обновлений.

Включаем показ ошибок

По умолчанию продукт не показывает подробности ошибок в браузере. Для рабочего сайта это правильно: стек вызовов и пути к файлам не должны видеть посетители. Но при разработке без этих подробностей не обойтись.

Настройки ядра хранятся в файле /bitrix/.settings.php. Это PHP-файл, который возвращает массив секций. Мастер установки уже создал его и записал в него, например, подключение к базе данных — секцию connections.

Перед правкой сохраните копию файла: ошибка в синтаксисе .settings.php останавливает весь сайт.

За ошибки отвечает секция exception_handling. Найдите ее и установите параметр debug в true:

'exception_handling' => [
    'value' => [
        'debug' => true,
        // остальные параметры секции не меняйте
    ],
    'readonly' => false,
],

Параметр readonly у каждой секции запрещает или разрешает менять ее из кода во время работы. Для connections он равен true: параметры базы данных нельзя подменить на лету.

Проверяем результат

Стенд готов к курсу, если административный раздел открывается под администратором, а в корне сайта есть папка /local/.

Продукт сам проверяет окружение. Откройте Настройки > Инструменты > Проверка системы и запустите полное тестирование. Зеленым отмечены параметры, которые соответствуют требованиям, красным — те, что нужно исправить. На свежем стенде часть тестов может быть красной:

• Отправка почты — почта в окружении не настроена. Как подключить почтовый сервер, описано в README env-docker
• Работа с сокетами — сайт открыт через localhost. Откройте его по IP-адресу или домену и повторите проверку
• Структура базы данных — на свежей установке тест может найти расхождения структуры таблиц и показать ссылку Исправить. Нажмите ее: продукт исправит то, что можно исправить автоматически. Оставшиеся расхождения прохождению курса не мешают

Остальные обязательные параметры должны быть зелеными. Рекомендуемые параметры влияют на отдельные возможности продукта, но сайт работает и без них. Замечание у теста Выполнение агентов на cron на стенде тоже не мешает: агенты выполняются при открытии страниц, подробнее — в уроке 13.

Если что-то пошло не так, сверьтесь с таблицей:

Если нужно больше информации

• Установка окружения — все варианты окружения, включая виртуальную машину BitrixVM
• Установка дистрибутива — шаги мастера и быстрая установка через .settings.php
• Структура директорий — полный список системных папок и файлов
• Как правильно и безопасно кастомизировать коробочные продукты — правила кастомизации и инструменты
• Конфигурация ядра — все секции .settings.php