architect/_archive/2025-11-26-cleanup/templates/solution/drupal11-commerce-pim/README.md

Drupal 11 + Commerce 3.0 PIM - Template

Версия: 1.0.0
Дата: 2025-11-14
Статус: Production Ready


📋 Оглавление

  1. Описание
  2. Стек технологий
  3. Системные требования
  4. Быстрый старт
  5. Установка с нуля
  6. Восстановление из backup
  7. Настройка Nginx
  8. Управление
  9. Backup и восстановление
  10. Troubleshooting

📖 Описание

Готовый шаблон для развёртывания PIM (Product Information Management) системы на базе Drupal 11 и Drupal Commerce 3.0.

Включает:
- ✅ Drupal 11.2.8 (последняя стабильная)
- ✅ Drupal Commerce 3.0.x-dev (совместим с Drupal 11)
- ✅ PostgreSQL 16 (требование Drupal 11)
- ✅ PHP 8.3 (требование Drupal 11)
- ✅ Docker & Docker Compose
- ✅ Nginx reverse proxy configuration
- ✅ SSL сертификаты Let's Encrypt
- ✅ Автоматические скрипты развёртывания


🛠️ Стек технологий

Backend

Database

Web Server

Containerization

Модули Drupal Commerce


💻 Системные требования

Сервер

Ресурсы

Сеть


🚀 Быстрый старт

1. Клонирование шаблона

# Создать директорию проекта
mkdir ~/my-pim-project
cd ~/my-pim-project

# Скопировать файлы шаблона
cp -r /opt/claude-workspace/templates/solution/drupal11-commerce-pim/structure/* .

2. Настройка параметров

# Отредактировать docker-compose.yml (при необходимости)
nano docker-compose.yml

# Изменить:
# - Порт (по умолчанию 8801)
# - Пароль PostgreSQL (POSTGRES_PASSWORD)

3. Запуск развёртывания

# Сделать скрипт исполняемым
chmod +x scripts/deploy.sh

# Запустить развёртывание
./scripts/deploy.sh your-domain.com YourAdminPassword123!

# Время установки: ~10-15 минут

4. Настройка DNS и SSL

# Настроить DNS A запись:
# your-domain.com → IP вашего сервера

# Настроить Nginx
sudo cp nginx/site.conf.template /etc/nginx/sites-available/your-domain.com
sudo nano /etc/nginx/sites-available/your-domain.com
# Заменить YOUR_DOMAIN и YOUR_PORT

sudo ln -s /etc/nginx/sites-available/your-domain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Получить SSL сертификат
sudo certbot --nginx -d your-domain.com

5. Готово! 🎉

Откройте браузер: https://your-domain.com

Вход в админку:
- URL: https://your-domain.com/user/login
- Логин: admin
- Пароль: тот что указали в deploy.sh


🔧 Установка с нуля

Шаг 1: Подготовка сервера

# Установка Docker (если не установлен)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Установка Docker Compose
sudo apt update
sudo apt install -y docker-compose-plugin

# Установка Nginx и Certbot
sudo apt install -y nginx certbot python3-certbot-nginx

Шаг 2: Копирование шаблона

mkdir ~/my-pim-project
cd ~/my-pim-project
cp -r /opt/claude-workspace/templates/solution/drupal11-commerce-pim/structure/* .

Шаг 3: Кастомизация

# Изменить пароли в docker-compose.yml
nano docker-compose.yml

# Изменить:
# - POSTGRES_PASSWORD
# - Порт контейнера (если нужен не 8801)

Шаг 4: Развёртывание

chmod +x scripts/deploy.sh
./scripts/deploy.sh your-domain.com YourStrongPassword123!

Шаг 5: Nginx и SSL

# Скопировать и настроить конфигурацию Nginx
sudo cp nginx/site.conf.template /etc/nginx/sites-available/your-domain.com
sudo nano /etc/nginx/sites-available/your-domain.com

# Заменить:
# - YOUR_DOMAIN на ваш домен
# - YOUR_PORT на порт контейнера (8801)

# Активировать конфигурацию
sudo ln -s /etc/nginx/sites-available/your-domain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Получить SSL сертификат
sudo certbot --nginx -d your-domain.com

# Проверить автопродление
sudo certbot renew --dry-run

🔄 Восстановление из backup

Если у вас есть backup базы данных и файлов:

# Скопировать файлы backup
cp your-backup.sql backups/
cp your-files.tar.gz backups/

# Запустить скрипт восстановления
chmod +x scripts/restore.sh
./scripts/restore.sh backups/your-backup.sql backups/your-files.tar.gz

Скрипт автоматически:
1. Создаст backup текущей БД (на всякий случай)
2. Очистит текущую БД
3. Восстановит данные из backup
4. Восстановит файлы (если указаны)
5. Установит правильные права доступа
6. Очистит кэш Drupal
7. Перезапустит контейнеры


🌐 Настройка Nginx

Шаблон конфигурации

Файл: nginx/site.conf.template

Параметры для замены:
- YOUR_DOMAIN → ваш домен
- YOUR_PORT → порт контейнера (8801)

Ручная настройка

# HTTP → HTTPS redirect
server {
    listen 80;
    server_name your-domain.com;
    location / {
        return 301 https://$server_name$request_uri;
    }
}

# HTTPS
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:8801;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
    }
}

🎛️ Управление

Контейнеры

# Статус контейнеров
docker compose ps

# Просмотр логов
docker compose logs -f pim-drupal
docker compose logs -f pim-db

# Перезапуск
docker compose restart

# Остановка
docker compose stop

# Запуск
docker compose up -d

# Полная пересборка
docker compose down
docker compose build --no-cache
docker compose up -d

Drupal Shell

# Войти в контейнер
docker exec -it pim-drupal bash

# Внутри контейнера:
cd /var/www/html

# Проверить статус Drupal
vendor/bin/drush status

# Очистить кэш
vendor/bin/drush cr

# Список модулей
vendor/bin/drush pm:list

# Включить модуль
vendor/bin/drush en module_name -y

# Обновить БД
vendor/bin/drush updb -y

PostgreSQL

# Войти в PostgreSQL
docker exec -it pim-db psql -U drupal_pim -d drupal_pim

# SQL команды:
\dt                  -- Список таблиц
\du                  -- Список пользователей
SELECT version();    -- Версия PostgreSQL
\q                   -- Выход

Composer

# Войти в контейнер
docker exec -it pim-drupal bash

cd /var/www/html

# Установить модуль
composer require drupal/module_name

# Обновить зависимости
composer update

# Показать зависимости
composer show

💾 Backup и восстановление

Создание backup

Backup базы данных

# Полный dump БД
docker exec pim-db pg_dump -U drupal_pim drupal_pim > backups/backup-$(date +%Y%m%d).sql

# С сжатием
docker exec pim-db pg_dump -U drupal_pim drupal_pim | gzip > backups/backup-$(date +%Y%m%d).sql.gz

Backup файлов

# Backup всех файлов Drupal
tar -czf backups/files-$(date +%Y%m%d).tar.gz \
  web/sites/default/files \
  docker-compose.yml \
  Dockerfile \
  web/composer.json \
  web/composer.lock

Автоматический backup (cron)

# Создать скрипт backup
cat > /usr/local/bin/drupal-backup.sh <<'EOF'
#!/bin/bash
cd ~/my-pim-project
docker exec pim-db pg_dump -U drupal_pim drupal_pim | gzip > backups/auto-backup-$(date +%Y%m%d-%H%M).sql.gz
find backups/ -name "auto-backup-*.sql.gz" -mtime +7 -delete
EOF

chmod +x /usr/local/bin/drupal-backup.sh

# Добавить в crontab (backup каждый день в 3:00)
crontab -e
# Добавить строку:
0 3 * * * /usr/local/bin/drupal-backup.sh

Восстановление backup

С помощью скрипта

./scripts/restore.sh backups/backup.sql backups/files.tar.gz

Вручную

# Восстановить БД
cat backups/backup.sql | docker exec -i pim-db psql -U drupal_pim drupal_pim

# Или из gzip
gunzip < backups/backup.sql.gz | docker exec -i pim-db psql -U drupal_pim drupal_pim

# Восстановить файлы
tar -xzf backups/files.tar.gz -C .

# Установить права
docker exec pim-drupal bash -c "chown -R www-data:www-data /var/www/html"
docker exec pim-drupal bash -c "chmod -R 777 /var/www/html/web/sites/default/files"

# Очистить кэш
docker exec pim-drupal bash -c "cd /var/www/html && vendor/bin/drush cr"

🔧 Troubleshooting

Контейнеры не запускаются

# Проверить логи
docker compose logs

# Проверить порты
sudo netstat -tlnp | grep 8801
sudo netstat -tlnp | grep 5432

# Остановить и пересоздать
docker compose down
docker compose up -d

Ошибка подключения к БД

# Проверить что PostgreSQL запущен
docker exec pim-db pg_isready -U drupal_pim

# Проверить сеть между контейнерами
docker network inspect pim-network

# Перезапустить БД
docker compose restart pim-db

Ошибки прав доступа

# Установить правильные права
docker exec pim-drupal bash -c "
chown -R www-data:www-data /var/www/html
chmod -R 755 /var/www/html
chmod -R 777 /var/www/html/web/sites/default/files
"

Белый экран (WSOD)

# Включить отображение ошибок
docker exec pim-drupal bash -c "cd /var/www/html && vendor/bin/drush config:set system.logging error_level verbose -y"

# Очистить кэш
docker exec pim-drupal bash -c "cd /var/www/html && vendor/bin/drush cr"

# Проверить логи PHP
docker compose logs pim-drupal

# Проверить логи Nginx
sudo tail -f /var/log/nginx/your-domain-error.log

Commerce модуль не устанавливается

# Проверить minimum-stability в composer.json
docker exec pim-drupal bash -c "cd /var/www/html && composer config minimum-stability"

# Должно быть: RC

# Установить правильную версию Commerce
docker exec pim-drupal bash -c "cd /var/www/html && \
  composer config minimum-stability RC && \
  composer require 'drupal/commerce:3.0.x-dev@dev' 'drupal/inline_entity_form:^3.0@RC' --no-interaction"

PostgreSQL: версия 15 вместо 16

# Остановить контейнеры
docker compose down

# Удалить старые данные PostgreSQL
rm -rf data/postgres/*

# Убедиться что в docker-compose.yml указан postgres:16-alpine
grep "image: postgres" docker-compose.yml
# Должно быть: image: postgres:16-alpine

# Запустить снова
docker compose up -d

📚 Полезные ссылки


📝 Изменения и версии

v1.0.0 (2025-11-14)


🤝 Поддержка

При возникновении проблем:
1. Проверьте секцию Troubleshooting
2. Проверьте логи контейнеров
3. Проверьте template.yaml для известных проблем


Создано: 2025-11-14
Автор: Claude Code
Лицензия: GPL-2.0-or-later (как у Drupal)