Разворачивание локальной среды разработки OctoberCMS eCommerce на Homestead с PostgreSQL

Разворачивание локальной среды разработки OctoberCMS eCommerce на Homestead с PostgreSQL
Эта памятка описывает пошаговое разворачивание локальной среды разработки для проекта на
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.

Важно: встроенная версия PostgreSQL в Homestead может отличаться от 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/postgresql

3. Пример 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"
Для Mac Apple Silicon используется обычный box laravel/homestead,
а не laravel/homestead-arm.

4. Запуск Homestead

cd /Users/username/Projects/Homestead
vagrant up --provider=parallels

Если менялся Homestead.yaml:

vagrant reload --provision

Войти в виртуальную машину:

vagrant ssh

5. Настройка hosts на host machine

На Mac нужно добавить локальный домен:

sudo nano /etc/hosts

Добавить:

192.168.11.11 october.local

Проверить:

ping october.local

6. Если 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 --provision

7. Настройка 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 apache2

8. Composer и зависимости проекта

Внутри проекта:

cd /home/vagrant/octobercms-project
composer install
Важно: для восстановления проекта чаще всего нужно использовать
composer install, а не composer update.
Команда composer update может изменить версии пакетов, удалить плагины
или поменять composer.lock.

Если случайно был выполнен composer update и удалились файлы плагина:

git restore composer.lock plugins/vendor/plugin-name
composer install

Проверить статус Git:

git status

9. 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-october
Live-файлы PostgreSQL не рекомендуется хранить прямо в shared folder между Mac и Homestead.
PostgreSQL требует строгие 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 connections

9.3. Автозапуск контейнера

docker update --restart unless-stopped pg18-october

Проверить:

docker inspect pg18-october --format '{{.HostConfig.RestartPolicy.Name}}'

Ожидаемый результат:

unless-stopped

9.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
Для полноценной локальной разработки не нужно отключать production-функции.
Если приложение использует 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 apache2

11.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.dump

13. Restore dump через PostgreSQL 18 Docker

Если дамп создан PostgreSQL 18, а системный 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_ecommerce

13.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.dump

13.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 apache2

15. Проверка Apache

Проверить активные virtual hosts:

sudo apache2ctl -S

Должен быть локальный домен на HTTPS:

*:443 october.local

Проверить статус Apache:

sudo systemctl status apache2

Если Apache не запущен:

sudo systemctl start apache2

Чтобы Apache запускался автоматически:

sudo systemctl enable apache2

16. Если открывается дефолтная страница 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 apache2

17. Если 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
Если backend login просто обновляет страницу и не входит в панель,
причина может быть в 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/backend

22. Главные выводы

  • Для Mac ARM можно использовать laravel/homestead version 14.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.3 Docker image.
  • Локальный сайт должен работать на https://october.local.
  • Для полноценной разработки не отключать reCAPTCHA и secure-функции, а правильно поднять HTTPS.
  • composer install безопаснее для восстановления проекта, чем composer update.
  • После vagrant destroy всё внутри VM пропадает, кроме shared folders на host machine.
Рассказать друзьям:
  • Добавить ВКонтакте заметку об этой странице
  • Мой Мир
  • Facebook
  • Twitter
  • LiveJournal
  • В закладки Google
  • Blogger
  • RSS
  • Блог Li.ру
  • Одноклассники
  • LinkedIn

Написать ответ

Этот сайт использует Akismet для борьбы со спамом. Узнайте, как обрабатываются ваши данные комментариев.