OctoberCMS с eCommerce-архитектурой и базой данных
PostgreSQL. Среда запускается на Laravel Homestead,
Vagrant, Parallels, Apache,
PHP 8.2 и PostgreSQL 18.3 через Docker.
Подход подходит для ситуации, когда production-база работает на современной версии PostgreSQL,
а локальная Homestead-среда должна максимально повторять production-окружение.
1. Общая архитектура локальной среды
Используется следующая схема:
Mac / host machine
↓
Vagrant + Parallels
↓
Homestead Ubuntu VM
↓
Apache + PHP 8.2 + OctoberCMS
↓
PostgreSQL 18.3 в Docker-контейнереHomestead используется как основная виртуальная машина для PHP, Apache и проекта.
PostgreSQL запускается отдельно в Docker-контейнере внутри Homestead, чтобы локальная версия
PostgreSQL совпадала с production.
Если production использует PostgreSQL 18.x, локально лучше поднять такую же версию через Docker.
2. Пример структуры папок на host machine
/Users/username/Projects/Homestead
/Users/username/Projects/octobercms-project
/Users/username/Projects/html
/Users/username/Projects/PostgreSQL/october-postgres18Внутри Homestead эти папки будут доступны так:
/home/vagrant/octobercms-project
/home/vagrant/html
/home/vagrant/postgresql3. Пример Homestead.yaml
---
ip: "192.168.11.11"
memory: 2048
cpus: 2
provider: parallels
box: laravel/homestead
version: "14.0.2"
name: october-dev
authorize: ~/.ssh/id_rsa.pub
keys:
- ~/.ssh/id_rsa
folders:
- map: /Users/username/Projects/octobercms-project
to: /home/vagrant/octobercms-project
- map: /Users/username/Projects/html
to: /home/vagrant/html
- map: /Users/username/Projects/PostgreSQL/october-postgres18
to: /home/vagrant/postgresql
sites:
- map: october.local
to: /home/vagrant/octobercms-project
php: "8.2"
type: "apache"
wildcard: "yes"
use_wildcard: "yes"
databases:
- homestead
- session
- laravel
features:
- mysql: true
- mariadb: false
- postgresql: true
- ohmyzsh: true
- docker: true
- webdriver: true
services:
- enabled:
- "mysql"
- "postgresql"laravel/homestead,а не
laravel/homestead-arm.4. Запуск Homestead
cd /Users/username/Projects/Homestead
vagrant up --provider=parallelsЕсли менялся Homestead.yaml:
vagrant reload --provisionВойти в виртуальную машину:
vagrant ssh5. Настройка hosts на host machine
На Mac нужно добавить локальный домен:
sudo nano /etc/hostsДобавить:
192.168.11.11 october.localПроверить:
ping october.local6. Если provision падает из-за Ondrej PHP PPA
Иногда при provision может появиться ошибка:
Repository 'https://ppa.launchpadcontent.net/ondrej/php/ubuntu jammy InRelease'
changed its 'Label' valueФикс внутри Homestead:
sudo apt update --allow-releaseinfo-changeПосле этого снова запустить provision с host machine:
cd /Users/username/Projects/Homestead
vagrant reload --provision7. Настройка PHP 8.2
Внутри Homestead:
sudo apt update --allow-releaseinfo-change
sudo apt updateУстановить PHP 8.2 и нужные модули:
sudo apt install -y \
php8.2 \
php8.2-cli \
php8.2-fpm \
php8.2-common \
php8.2-mysql \
php8.2-pgsql \
php8.2-xml \
php8.2-curl \
php8.2-mbstring \
php8.2-zip \
php8.2-gd \
php8.2-intl \
php8.2-bcmath \
php8.2-soap \
php8.2-readline \
php8.2-sqlite3Сделать PHP 8.2 дефолтной версией в консоли:
sudo update-alternatives --set php /usr/bin/php8.2
php -vПереключить Apache/FPM на PHP 8.2:
sudo a2dismod php8.3 || true
sudo a2dismod php8.1 || true
sudo a2dismod php8.0 || true
sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.2-fpm || true
sudo systemctl restart php8.2-fpm
sudo systemctl restart apache28. Composer и зависимости проекта
Внутри проекта:
cd /home/vagrant/octobercms-project
composer installcomposer install, а не composer update.Команда
composer update может изменить версии пакетов, удалить плагиныили поменять
composer.lock.Если случайно был выполнен composer update и удалились файлы плагина:
git restore composer.lock plugins/vendor/plugin-name
composer installПроверить статус Git:
git status9. PostgreSQL 18.3 через Docker внутри Homestead
Если production использует PostgreSQL 18.x, локальную базу лучше поднять на такой же версии.
Для этого используется Docker-контейнер postgres:18.3.
9.1. Создать live-папку для PostgreSQL внутри Homestead
sudo mkdir -p /var/lib/pg18-october
sudo chown -R 999:999 /var/lib/pg18-octoberPostgreSQL требует строгие Linux permissions. На shared folder могут возникать ошибки
вида
Permission denied.9.2. Запустить PostgreSQL 18.3 контейнер
docker run --name pg18-october \
-e POSTGRES_DB=october_ecommerce \
-e POSTGRES_USER=october_user \
-e POSTGRES_PASSWORD='local_database_password' \
-p 5433:5432 \
-v /var/lib/pg18-october:/var/lib/postgresql \
-d postgres:18.3Проверить контейнер:
docker ps
docker logs pg18-octoberВ логах должно быть:
database system is ready to accept connections9.3. Автозапуск контейнера
docker update --restart unless-stopped pg18-octoberПроверить:
docker inspect pg18-october --format '{{.HostConfig.RestartPolicy.Name}}'Ожидаемый результат:
unless-stopped9.4. Подключение к PostgreSQL
psql -h 127.0.0.1 -p 5433 -U october_user -d october_ecommerceПроверить версию PostgreSQL:
SHOW server_version;10. .env для локальной разработки
APP_NAME="October eCommerce"
APP_ENV=local
APP_DEBUG=true
APP_URL=https://october.local
APP_LOCALE=en
CMS_ASSET_MINIFY=true
BACKEND_URI=backend
BACKEND_TURBO_ROUTER=false
CMS_ROUTE_CACHE=false
CMS_ASSET_CACHE=false
CMS_SAFE_MODE=false
LINK_POLICY=detect
DEFAULT_FILE_MASK=775
DEFAULT_FOLDER_MASK=775
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5433
DB_DATABASE=october_ecommerce
DB_USERNAME=october_user
DB_PASSWORD='local_database_password'
LOG_CHANNEL=single
BROADCAST_DRIVER=log
CACHE_DRIVER=file
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120
SESSION_SECURE_COOKIE=true
SESSION_DOMAIN=
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
MAIL_MAILER=log
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS=no-reply@example.local
MAIL_FROM_NAME="${APP_NAME}"
RECAPTCHA_V3_SITE_KEY_FRONTEND=your_recaptcha_site_key
RECAPTCHA_V3_SECRET_KEY_BACKEND=your_recaptcha_secret_key
RECAPTCHA_V3_MIN_SCORE=0.3
RECAPTCHA_V3_ENABLED=trueЕсли приложение использует reCAPTCHA, secure cookies или HTTPS-only логику,
локальную среду нужно поднимать на HTTPS.
11. HTTPS для локального домена
Для backend login, secure cookies, session и reCAPTCHA локальный сайт лучше запускать на HTTPS.
11.1. Включить Apache-модули
sudo a2enmod ssl
sudo a2enmod rewrite
sudo a2enmod headers
sudo a2enmod proxy_fcgi
sudo a2enmod setenvif
sudo systemctl restart apache211.2. Создать self-signed сертификат
sudo mkdir -p /etc/apache2/ssl
sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
-keyout /etc/apache2/ssl/october.local.key \
-out /etc/apache2/ssl/october.local.crt \
-subj "/C=US/ST=Local/L=Local/O=OctoberCMS/OU=Dev/CN=october.local"11.3. Создать SSL VirtualHost
Файл:
/etc/apache2/sites-available/october.local-ssl.confКонфиг:
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerName october.local
ServerAlias www.october.local
DocumentRoot /home/vagrant/octobercms-project
<Directory /home/vagrant/octobercms-project>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
SSLEngine on
SSLCertificateFile /etc/apache2/ssl/october.local.crt
SSLCertificateKeyFile /etc/apache2/ssl/october.local.key
<FilesMatch ".+\.ph(ar|p|tml)$">
SetHandler "proxy:unix:/var/run/php/php8.2-fpm.sock|fcgi://localhost"
</FilesMatch>
ErrorLog ${APACHE_LOG_DIR}/october.local-ssl-error.log
CustomLog ${APACHE_LOG_DIR}/october.local-ssl-access.log combined
</VirtualHost>
</IfModule>11.4. Включить SSL-сайт
sudo a2ensite october.local-ssl.conf
sudo apache2ctl configtest
sudo systemctl reload apache2Если configtest показывает Syntax OK, конфиг принят.
11.5. Проверить HTTPS
curl -k -I https://october.localОткрывать в браузере:
https://october.local
https://october.local/backendБраузер может показать предупреждение о self-signed сертификате.
Для локальной разработки это нормально.
12. Дамп production PostgreSQL базы
Пример команды для создания дампа production PostgreSQL базы:
PGSSLMODE=require pg_dump \
-h production-postgresql-host.example.com \
-p 5432 \
-U production_user \
-d production_database \
-F c \
-f latest_rds.dumpФайл latest_rds.dump можно положить на host machine:
/Users/username/Projects/PostgreSQL/october-postgres18/latest_rds.dumpВнутри Homestead этот файл будет виден как:
/home/vagrant/postgresql/latest_rds.dump13. Restore dump через PostgreSQL 18 Docker
pg_restore в Homestead старее,может появиться ошибка:
pg_restore: error: unsupported version in file headerВ этом случае restore нужно выполнять через Docker image postgres:18.3.
13.1. Пересоздать локальную базу
PGPASSWORD='local_database_password' dropdb \
-h 127.0.0.1 \
-p 5433 \
-U october_user \
--if-exists \
october_ecommerce
PGPASSWORD='local_database_password' createdb \
-h 127.0.0.1 \
-p 5433 \
-U october_user \
october_ecommerce13.2. Восстановить dump
docker run --rm --network host \
-e PGPASSWORD='local_database_password' \
-v /home/vagrant/postgresql:/backup \
postgres:18.3 \
pg_restore \
-h 127.0.0.1 \
-p 5433 \
-U october_user \
-d october_ecommerce \
/backup/latest_rds.dump13.3. Проверить таблицы
psql -h 127.0.0.1 -p 5433 -U october_user -d october_ecommerce -c "\dt"В базе должны появиться таблицы OctoberCMS, например:
backend_users
system_plugin_versions
cms_theme_templates
system_settings
...14. Очистка кэшей OctoberCMS / Laravel
После изменения .env, восстановления базы, изменения PHP или Composer:
cd /home/vagrant/octobercms-project
php artisan optimize:clear
php artisan cache:clear
php artisan config:clear
php artisan view:clear
rm -rf storage/framework/sessions/*
sudo systemctl restart apache215. Проверка Apache
Проверить активные virtual hosts:
sudo apache2ctl -SДолжен быть локальный домен на HTTPS:
*:443 october.localПроверить статус Apache:
sudo systemctl status apache2Если Apache не запущен:
sudo systemctl start apache2Чтобы Apache запускался автоматически:
sudo systemctl enable apache216. Если открывается дефолтная страница Apache
Это означает, что не применился virtual host или provision оборвался.
На host machine:
cd /Users/username/Projects/Homestead
vagrant reload --provisionВнутри Homestead:
sudo apache2ctl -SЕсли нужно отключить дефолтный сайт:
sudo a2dissite 000-default.conf
sudo systemctl reload apache217. Если backend не пускает в админку
Проверить в .env:
APP_URL=https://october.local
BACKEND_URI=backend
SESSION_SECURE_COOKIE=true
RECAPTCHA_V3_ENABLED=trueПосле правки:
php artisan optimize:clear
php artisan config:clear
php artisan cache:clear
php artisan view:clear
rm -rf storage/framework/sessions/*
sudo systemctl restart apache2Открывать backend по HTTPS:
https://october.local/backendпричина может быть в HTTP/HTTPS, secure cookies, session или reCAPTCHA.
В такой архитектуре локальный backend нужно проверять именно через HTTPS.
18. Если ошибка: backend_users does not exist
Это значит, что приложение подключилось к PostgreSQL, но база пустая
или dump не восстановился.
Проверка:
psql -h 127.0.0.1 -p 5433 -U october_user -d october_ecommerce -c "\dt"Если таблиц нет, нужно восстановить production dump через Docker PostgreSQL 18.
19. Если ошибка: partial not found
Пример ошибки:
The partial 'site/example-partial' is not found.Это проблема темы OctoberCMS, а не Apache, PHP или PostgreSQL.
Проверить файл partial:
ls -la /home/vagrant/octobercms-project/themes/your-theme/partials/site/Если нужного .htm файла нет, его нужно вернуть в тему
или убрать вызов partial из layout/page.
20. Что происходит после vagrant destroy
vagrant destroy уничтожается вся виртуальная машина.Пропадают Docker-контейнеры, crontab, системные настройки и live database files
внутри Homestead.
Пропадёт:
/var/lib/pg18-october
Docker containers
Docker images
crontab
systemd-настройки внутри VMОстанется только то, что лежит в shared folders на host machine:
/Users/username/Projects/PostgreSQL/october-postgres18Поэтому после vagrant destroy нужно заново поднять PostgreSQL Docker-контейнер
и восстановить базу из latest_rds.dump, если требуется.
21. Быстрый чек-лист после запуска Homestead
cd /Users/username/Projects/Homestead
vagrant up
vagrant sshВнутри Homestead:
docker ps
sudo systemctl status apache2
php -v
psql -h 127.0.0.1 -p 5433 -U october_user -d october_ecommerce -c "SHOW server_version;"
curl -k -I https://october.localОткрыть в браузере:
https://october.local
https://october.local/backend22. Главные выводы
- Для Mac ARM можно использовать
laravel/homesteadversion14.0.2. - Provider для Apple Silicon:
parallels. - PHP проекта:
8.2. - PostgreSQL лучше поднимать той же major-версии, что и production.
- PostgreSQL 18.3 удобно запускать через Docker внутри Homestead.
- OctoberCMS подключается к PostgreSQL через
127.0.0.1:5433. - Для restore dump от PostgreSQL 18 нужно использовать
postgres:18.3Docker image. - Локальный сайт должен работать на
https://october.local. - Для полноценной разработки не отключать reCAPTCHA и secure-функции, а правильно поднять HTTPS.
composer installбезопаснее для восстановления проекта, чемcomposer update.- После
vagrant destroyвсё внутри VM пропадает, кроме shared folders на host machine.

