Как установить и настроить Directus на VPS

MAATRIX

Если у вас уже есть рабочая база данных — интернет-магазин, CRM, внутренний сервис — и нужна админка с REST/GraphQL API поверх неё без переноса данных в очередную «свою» систему, обычный headless CMS тут не подойдёт: он захочет управлять схемой сам. Directus решает именно эту задачу — он подключается к вашей существующей SQL-базе, читает её структуру и превращает таблицы в управляемые коллекции, не трогая то, что там уже лежит. Ниже — как поднять его на VPS с нуля через Docker Compose, подключить к готовой базе и вывести в продакшен с SSL.

Что такое Directus и чем он отличается от Strapi или Ghost

Directus — это не CMS в классическом понимании, а слой (Data Platform) поверх реляционной базы. Он поддерживает PostgreSQL, MySQL/MariaDB, SQLite, MS SQL, OracleDB и CockroachDB. Разница с тем же Strapi принципиальная: Strapi создаёт и владеет своей схемой — вы описываете content-типы в его терминах, и данные живут «внутри» Strapi. Directus, наоборот, интроспектирует базу: подключился — увидел существующие таблицы — предложил превратить их в коллекции прямо как есть, с их реальными именами столбцов и связями.

Практически это значит:

• Если у вас уже есть база с таблицами products, orders, customers — Directus не требует ре-импорта, он просто «увидит» эти таблицы и построит вокруг них админку и API.
• Directus добавляет рядом свои системные таблицы (directus_users, directus_roles, directus_permissions, directus_collections и так далее) — они хранят метаданные о том, как показывать ваши данные, но не переписывают ваши таблицы.
• Если база пустая — можно спроектировать схему прямо в UI Directus, и он создаст таблицы сам.
• Из коробки — REST и GraphQL API, ролевая модель доступа на уровне полей, файловое хранилище (локально или S3-совместимое), вебхуки, real-time через WebSocket.

Отсюда и типовые сценарии: headless-бэкенд для существующего SQL-проекта, админка для legacy-базы без разработчика фронтенда, единая точка API для мобильного приложения и сайта, которые ходят в одну базу.

Требования к серверу и подготовка VPS

Directus — приложение на Node.js, но для продакшена его почти всегда разворачивают в Docker, поэтому Node.js локально можно не ставить вовсе. Минимальные и рекомендуемые параметры:

Для теста хватит 2 ГБ, но под реальную нагрузку с загрузкой файлов и несколькими редакторами закладывайте от 4 ГБ — Node.js под нагрузкой съедает память рывками, и Directus не исключение.

Подготовка сервера — стандартная. Обновите систему, поставьте Docker и Compose-плагин:

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
apt install -y docker-compose-plugin
docker --version
docker compose version

Заведите отдельного пользователя без root (или используйте существующего) и добавьте его в группу docker, чтобы не работать под root постоянно:

usermod -aG docker deploy

Установка Directus через Docker Compose

Создайте директорию проекта и структуру для персистентных данных:

mkdir -p /opt/directus/{database,uploads,extensions}
cd /opt/directus

Сгенерируйте секретные ключи — они понадобятся в .env:

openssl rand -hex 32   # для KEY
openssl rand -hex 32   # для SECRET

Файл .env:

KEY=вставьте_первый_hex
SECRET=вставьте_второй_hex

DB_CLIENT=pg
DB_HOST=database
DB_PORT=5432
DB_DATABASE=directus
DB_USER=directus
DB_PASSWORD=замените_на_свой_пароль

ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=замените_на_свой_пароль

PUBLIC_URL=https://directus.example.com
CORS_ENABLED=true
CORS_ORIGIN=true

WEBSOCKETS_ENABLED=true

docker-compose.yml:

services:
  database:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - ./database:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: directus
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: directus
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U directus"]
      interval: 5s
      timeout: 5s
      retries: 5

  directus:
    image: directus/directus:11
    restart: unless-stopped
    ports:
      - "127.0.0.1:8055:8055"
    volumes:
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
    env_file:
      - .env
    depends_on:
      database:
        condition: service_healthy

Порт 8055 привязан только к 127.0.0.1 — наружу его открывать не нужно, доступ будет через Nginx с SSL (см. ниже). Если хотите подключиться к базе, которая уже развёрнута отдельно (в том числе на другом сервере), просто уберите сервис database из compose-файла и укажите в .env реальные DB_HOST, DB_PORT и данные существующей базы — про такую установку PostgreSQL на VPS отдельно.

Запуск:

docker compose up -d
docker compose logs -f directus

При первом старте Directus сам применит миграции для своих системных таблиц и создаст администратора с логином и паролем из .env. Дождитесь строки о том, что сервер слушает на 8055.

Первый вход и базовая настройка

Пока порт закрыт снаружи, зайдите через SSH-туннель, чтобы проверить, что всё поднялось:

ssh -L 8055:localhost:8055 deploy@ваш_сервер

Откройте http://localhost:8055 в браузере, войдите под ADMIN_EMAIL/ADMIN_PASSWORD из .env. Сразу после входа стоит:

1. Зайти в Settings → Project Settings и задать название проекта, публичный URL (должен совпадать с PUBLIC_URL).
2. Настроить почтовый транспорт (EMAIL_TRANSPORT=smtp и соответствующие EMAIL_SMTP_* переменные) — без него не будут работать приглашения пользователей и восстановление пароля.
3. Создать отдельную роль для «обычных» редакторов с ограниченными правами — работать под Administrator в повседневных задачах не стоит.
4. Если файлы будут расти — подключить S3-совместимое хранилище вместо локального диска: переменные STORAGE_LOCATIONS, STORAGE_S3_*. Это особенно актуально, если параллельно поднят MinIO — можно сразу указать его как storage-бэкенд.

Подключение к существующей базе без миграции данных

Это тот сценарий, ради которого чаще всего и берут Directus. Если у вас уже есть база с данными — например, для интернет-магазина или внутреннего учёта — порядок такой:

1. В .env укажите параметры существующей базы (DB_HOST, DB_DATABASE, DB_USER, DB_PASSWORD) — той самой, где уже лежат ваши таблицы.
2. Запустите Directus как обычно. При первом старте он добавит в эту базу свои системные таблицы с префиксом directus_ — ваши таблицы он не трогает и не переименовывает.
3. Зайдите в Settings → Data Model. Вы увидите список всех таблиц базы, включая те, что Directus ещё не «знает». Нажмите на нужную таблицу и включите её как коллекцию.
4. Directus прочитает реальные столбцы и типы данных и предложит интерфейсы для каждого поля (текст, число, дата, связь по внешнему ключу и т.д.) — их можно донастроить, но сами данные при этом не меняются и не переносятся.
5. Внешние ключи в существующей схеме Directus по возможности распознаёт как связи (Many-to-One, One-to-Many) автоматически; если распознавание не сработало — связь можно задать вручную через Data Model → Relationships, это тоже не требует изменения структуры таблиц.

Важный нюанс: чтобы полноценно работали системные механизмы Directus (soft delete, статусы черновик/опубликовано, сортировка через drag-and-drop), таблице желательно иметь primary key и, по возможности, служебные поля вроде status или sort — если их нет, Directus предложит добавить недостающие столбцы через UI, но это уже осознанное решение, а не обязательное условие для подключения таблицы. Читать и редактировать данные можно и без них.

Если база большая и на проде — сначала протестируйте подключение на копии (дамп + восстановление на тестовом сервере), а уже потом переключайте .env на боевую базу.

Nginx как reverse proxy и SSL

Наружу Directus лучше не светить напрямую — используйте Nginx перед ним, как и для реверс-прокси на других приложениях. Конфиг /etc/nginx/sites-available/directus:

server {
    listen 80;
    server_name directus.example.com;

    location / {
        proxy_pass http://127.0.0.1:8055;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 90s;
    }
}

Заголовки Upgrade/Connection обязательны — Directus использует WebSocket для real-time обновлений в админке, и без них соединение будет откатываться на постоянные HTTP-опросы.

Активируйте сайт и получите сертификат:

ln -s /etc/nginx/sites-available/directus /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d directus.example.com

Подробный разбор возможных проблем с выпуском сертификата — в статье про Let's Encrypt SSL на VPS. После выпуска сертификата не забудьте открыть только нужные порты в файрволе — как настроить UFW на VPS, разрешив только 22, 80 и 443.

Бэкапы и обновления

Directus сам данные не бэкапит — это ответственность на уровне базы и файлов. Минимальный план для продакшена:

# Дамп базы (замените на реальные параметры подключения)
docker compose exec database pg_dump -U directus directus > /opt/backups/directus_$(date +%F).sql

# Архив загруженных файлов
tar -czf /opt/backups/uploads_$(date +%F).tar.gz /opt/directus/uploads

Вынесите это в cron и храните бэкапы за пределами самого сервера — на S3 или другом хосте. Обновление до новой версии — замена тега образа и рестарт:

# в docker-compose.yml замените directus/directus:11 на нужный тег
docker compose pull directus
docker compose up -d directus
docker compose logs -f directus

Перед мажорным обновлением стоит прочитать changelog конкретной версии и обязательно снять свежий дамп базы — Directus при старте новой версии сам прогоняет миграции своих системных таблиц, и откатить их «на лету» не получится, только восстановлением из бэкапа.

Частые вопросы