directus-auto-sync

Автоматизированный Docker-образ Directus со встроенной синхронизацией схемы и коллекций через directus-sync. Проект демонстрирует интеграцию плагина directus-sync с автоматическим применением дампа при старте контейнера, позволяя синхронизировать конфигурацию Directus между средами разработки без потери ключевых настроек и без вмешательства в данные базы данных.

Возможности

• двухэтапная сборка Docker: установка расширений на первом этапе, финальный образ на базе directus/directus:11.14.0;
• автоматический bootstrap, запуск seed-скриптов и применение дампа directus-sync при старте контейнера;
• seed-скрипты на Knex для заполнения directus_collections, directus_fields и directus_relations из snapshot-файла с топологической сортировкой коллекций;
• pull/push снапшотов и коллекций между локальной средой разработки и удалённым экземпляром Directus;
• конфигурация directus-sync с наследованием: базовые, локальные и remote-настройки через отдельные config-файлы;
• сохранение идентификаторов коллекций при синхронизации (preserveIds: all);
• поддержка S3-совместимого хранилища для загружаемых файлов;
• PostgreSQL 16 в качестве базы данных;
• отказоустойчивый запуск: graceful degradation при отсутствии дампа синхронизации.

Стек и архитектура

Directus 11.14, Node.js 20, Docker, Docker Compose, PostgreSQL 16, pnpm, Knex, directus-sync v3.

Архитектура — двухэтапная Docker-сборка с entrypoint-автоматизацией. На первом этапе устанавливается npm-пакет directus-extension-sync как расширение Directus. На втором этапе собирается финальный образ на базе официального directus/directus, в который копируются расширение, seed-скрипты и дамп синхронизации. Точка входа — entrypoint.sh, выполняющая bootstrap, запуск, seed и push. Конфигурация синхронизации разделена на три файла с наследованием: базовый, локальный и удалённый.

Поток данных при старте

flowchart TD
    A[entrypoint.sh] --> B[1. Bootstrap Directus]
    B --> C[2. Запуск Directus через pm2]
    C --> D[3. Ожидание healthcheck]
    D --> E{4. Есть ли snapshot.json?}
    E -->|да| F[Seed: прямые записи в directus_collections/fields/relations]
    E -->|нет| G[Пропуск seed]
    F --> H[5. directus-sync push --no-snapshot]
    G --> H
    H --> I[6. Сервер работает]

Loading

Рабочий процесс синхронизации

sequenceDiagram
    participant Dev as Среда разработки (локальная)
    participant Git as Репозиторий
    participant Prod as Production (Docker)

    Dev->>Dev: directus-sync pull
    Dev->>Git: коммит dump-файлов
    Git->>Prod: сборка образа с дампом
    Prod->>Prod: entrypoint: seed + push
    Note over Prod: Схема применена автоматически

Loading

Переменные окружения

Скопируйте .env.example в .env и заполните значения. Файл .env исключён из Git через .gitignore.

Переменная	Назначение	По умолчанию
PORT	порт Directus	8055
LOG_LEVEL	уровень логирования	info
NODE_ENV	окружение Node.js	production
SECRET	JWT-секрет Directus	(обязательно)
PUBLIC_URL	публичный URL экземпляра	http://localhost:8055
ROOT_REDIRECT	перенаправление с корня	./admin
ADMIN_EMAIL	email администратора	admin@example.com
ADMIN_PASSWORD	пароль администратора	(обязательно)
ADMIN_TOKEN	статический токен администратора, используется для directus-sync push	(опционально)
MIGRATIONS_PATH	путь к миграциям	./migrations
EXTENSIONS_PATH	путь к расширениям	./extensions
STORAGE_LOCATIONS	тип хранилища файлов	local
STORAGE_S3_DRIVER	S3-драйвер	s3
STORAGE_S3_REGION	регион S3	auto
STORAGE_S3_ENDPOINT	endpoint S3	(опционально)
STORAGE_S3_KEY	S3 access key	(опционально)
STORAGE_S3_SECRET	S3 secret key	(опционально)
STORAGE_S3_FORCE_PATH_STYLE	path-style для S3	true
STORAGE_S3_BUCKET	имя S3 bucket	(опционально)
STORAGE_S3_ROOT	корневой путь в S3 bucket	(опционально)
DB_CLIENT	клиент БД	pg
DB_HOST	хост БД	db
DB_PORT	порт БД	5432
DB_DATABASE	имя БД	directus
DB_USER	пользователь БД	postgres
DB_PASSWORD	пароль БД	postgres
EMAIL_VERIFY_SETUP	проверка email-настроек	true
EMAIL_TRANSPORT	транспорт email	smtp
EMAIL_SMTP_HOST	SMTP-хост	(опционально)
EMAIL_SMTP_PORT	SMTP-порт	465
EMAIL_SMTP_USER	SMTP-пользователь	(опционально)
EMAIL_SMTP_PASSWORD	SMTP-пароль	(опционально)
EMAIL_FROM	адрес отправителя	no-reply@example.com

Запуск через Docker

Требования: Docker Engine и Docker Compose v2.

cp .env.example .env
# заполните SECRET, ADMIN_EMAIL и ADMIN_PASSWORD
docker compose --env-file .env up --build

Compose поднимает PostgreSQL 16 и Directus в одной сети с проверкой готовности БД перед стартом админки. При старте выполняется bootstrap, seed из snapshot и directus-sync push. Админ-панель доступна по адресу http://localhost:8055/admin.

Остановка сервисов:

docker compose down

Локальная разработка

pnpm install

После настройки локального экземпляра Directus можно выполнять pull/push синхронизации:

# Получить текущую схему и коллекции из локального Directus
pnpm sync:local:pull

# Применить локальные изменения к локальному Directus
pnpm sync:local:push

# Получить схему и коллекции из удалённого Directus
pnpm sync:remote:pull

# Применить локальные изменения к удалённому Directus
pnpm sync:remote:push

# Запустить только seed-скрипты
pnpm seed:start

Для работы локальных команд необходим запущенный экземпляр Directus и переменная окружения ADMIN_TOKEN, заданная в .env или в окружении.

Рабочий процесс синхронизации

Проект автоматизирует синхронизацию конфигурации Directus между средами с помощью directus-sync:

1. Разработка: разработчик настраивает коллекции, поля, роли и права доступа в локальном Directus.
2. Pull: выполняется pnpm sync:local:pull — текущая схема и коллекции сохраняются в directus-sync-dump/.
3. Фиксация: dump-файлы коммитятся в репозиторий.
4. Сборка: Docker-образ включает дамп внутрь контейнера.
5. Развёртывание: при старте контейнера entrypoint автоматически применяет seed и выполняет directus-sync push, восстанавливая конфигурацию на целевом экземпляре.

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

Конфигурация directus-sync

Настройки разделены на три файла в extensions/directus-sync/:

• directus-sync.config.base.cjs — базовые параметры (путь дампа, сохранение ID, сортировка JSON);
• directus-sync.config.local.cjs — локальный экземпляр, URL http://0.0.0.0:8055 и токен из ADMIN_TOKEN;
• directus-sync.config.remote.cjs — удалённый экземпляр, URL из PUBLIC_URL и токен из ADMIN_TOKEN.

Файлы используют механизм extends для наследования базовых настроек.

Структура проекта

tree -L 3

Основные пути:

Dockerfile                # двухэтапная сборка образа
entrypoint.sh             # точка входа: bootstrap, seed, sync push
docker-compose.base.yml   # базовый сервис Directus с общими настройками
docker-compose.yml        # полный стек: PostgreSQL + Directus
package.json              # зависимости и скрипты синхронизации
seeds/main.cjs            # запуск seed-скриптов через Knex
seeds/directus-sync.seed.cjs  # заполнение таблиц из snapshot.json
extensions/directus-sync/     # конфигурационные файлы directus-sync
directus-sync-dump/       # дамп схемы и коллекций (генерируется через pull)
migrations/               # кастомные миграции Directus
uploads/                  # загружаемые файлы (монтируются как volume)