Directus на Ubuntu 24.04: пошаговая установка

MAATRIX

Если у вас уже есть рабочая база данных — от старого сайта, CRM-скрипта или самописного бэкенда — и нужна современная админка с REST/GraphQL API поверх неё, стандартные CMS тут не помогут: WordPress и Strapi хотят собственную схему и заставляют либо переносить данные, либо городить синхронизацию. Directus устроен иначе: он подключается к вашей существующей базе, читает её структуру и превращает таблицы в управляемые коллекции, не трогая ни одной строки данных. Разберём установку с нуля на чистом VPS с Ubuntu 24.04.

Чем Directus отличается от обычной headless CMS

Ключевая особенность Directus — он не владеет данными, а оборачивает их. Strapi, WordPress или Payload при установке создают собственную схему БД под свою логику: если у вас уже есть таблицы customers, orders, products из старого приложения, эти CMS с ними не работают напрямую — нужен экспорт-импорт или отдельный слой синхронизации.

Directus вместо этого:

• подключается к вашей базе (PostgreSQL, MySQL, SQLite, MS SQL, Oracle) как обычный клиент;
• добавляет в неё только свои служебные таблицы (directus_collections, directus_fields, directus_users и так далее) — они живут рядом с вашими и не пересекаются по именам, если у вас нет таблиц с префиксом directus_;
• через интроспекцию схемы видит существующие таблицы и позволяет включить их как коллекции — с нуля создавать модель данных не нужно;
• поверх включённых таблиц сразу даёт REST и GraphQL API, панель администратора, права доступа по ролям и вебхуки.

На практике это значит: если у вас legacy-приложение с базой, которую страшно трогать, вы получаете современный UI и API за час, а не за неделю миграции. Минус тоже есть — Directus не заменит полноценную ORM-логику самого приложения: он даёт CRUD-слой и админку, но бизнес-правила, которые раньше жили в коде приложения, в схему сами не переедут — их придётся продублировать через хуки или flows Directus, если они нужны на уровне API.

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

Directus — Node.js-приложение с собственным процессом кеширования и вебсокет-сервером для realtime-обновлений в админке. Для небольшой и средней базы (до нескольких сотен тысяч записей, десяток одновременных пользователей админки) хватает:

Если СУБД (PostgreSQL/MySQL) стоит на том же сервере, закладывайте RAM отдельно под неё — 1 ГБ общего объёма мало для связки Directus + PostgreSQL под реальной нагрузкой.

Обновите систему и создайте отдельного пользователя — работать под root не стоит даже на тестовом сервере:

apt update && apt upgrade -y
adduser directus
usermod -aG sudo directus
su - directus

Настройте базовый firewall:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Порт 8055 (стандартный порт Directus) наружу не открываем — доступ к нему пойдёт только через Nginx с SSL, это разберём в последнем разделе.

Установка Node.js

Directus требует актуальную LTS-ветку Node.js. Ставить пакет из репозитория Ubuntu не стоит — там обычно устаревшая версия. Проще и надёжнее через nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

nvm install --lts
nvm use --lts
node -v
npm -v

Заодно поставьте git и сборочные инструменты — некоторые нативные зависимости Directus (например, драйверы БД) собираются из исходников при установке:

sudo apt install -y build-essential git

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

Разберём сценарий на PostgreSQL — он же рекомендован разработчиками Directus как основная СУБД. Если PostgreSQL ещё не установлен, поставьте его так же, как описано в статье про установку PostgreSQL на Ubuntu 24.04 — здесь просто отметим ключевые шаги применительно к Directus.

Предположим, у вас уже есть база legacy_shop с таблицами customers, orders, products — переносить их никуда не нужно. Создайте пользователя, которому Directus будет подключаться, и выдайте ему права на эту же базу:

sudo -u postgres psql
CREATE USER directus_user WITH ENCRYPTED PASSWORD 'сложный_пароль';
GRANT ALL PRIVILEGES ON DATABASE legacy_shop TO directus_user;
\c legacy_shop
GRANT ALL ON SCHEMA public TO directus_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO directus_user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO directus_user;
\q

Начиная с PostgreSQL 15 схема public по умолчанию не даёт права CREATE никому, кроме владельца базы — без строки GRANT ALL ON SCHEMA public Directus не сможет создать свои служебные таблицы, и установка упадёт с ошибкой прав доступа на этапе bootstrap.

Если база на MySQL, аналогично: CREATE USER, GRANT ALL PRIVILEGES ON legacy_shop.* TO 'directus_user'@'localhost', FLUSH PRIVILEGES.

Перед любыми экспериментами сделайте дамп базы — Directus не должен ничего сломать в существующих таблицах, но бэкап перед первым запуском bootstrap на продовой базе обязателен:

pg_dump -U postgres legacy_shop > ~/legacy_shop_backup_$(date +%F).sql

Установка и запуск Directus

Создайте директорию проекта и установите Directus как обычную npm-зависимость — не через мастер create directus-project, который создаёт новую базу с нуля, а вручную, чтобы указать данные вашей существующей базы:

mkdir -p /opt/directus
sudo chown directus:directus /opt/directus
cd /opt/directus
npm init -y
npm install directus

Сгенерируйте секретные ключи и создайте .env:

KEY=$(openssl rand -hex 16)
SECRET=$(openssl rand -hex 32)
cat > .env <<EOF
KEY=${KEY}
SECRET=${SECRET}

DB_CLIENT=pg
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=legacy_shop
DB_USER=directus_user
DB_PASSWORD=сложный_пароль

ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=другой_сложный_пароль

PUBLIC_URL=https://directus.example.com
PORT=8055
HOST=127.0.0.1
EOF

Значение DB_CLIENT меняется под вашу СУБД:

Теперь запустите инициализацию — именно этот шаг создаёт служебные таблицы directus_* в вашей существующей базе, не затрагивая остальные:

npx directus bootstrap

Проверьте, что процесс поднимается:

npx directus start

Если всё прошло без ошибок, в логе появится строка о запуске сервера на порту 8055. Остановите его сочетанием Ctrl+C — постоянный запуск настроим через systemd в следующем разделе.

Откройте http://127.0.0.1:8055 (пока локально, через SSH-туннель ssh -L 8055:127.0.0.1:8055 user@server, либо после настройки Nginx — по домену) и войдите под ADMIN_EMAIL/ADMIN_PASSWORD из .env. В интерфейсе перейдите в Settings → Data Model — там вы увидите существующие таблицы customers, orders, products как непубличные, ещё не подключённые коллекции. Отметьте каждую как Managed by Directus, чтобы она появилась в основном меню и в API — это единственный ручной шаг, который требуется от миграции.

Автозапуск через systemd

Чтобы Directus поднимался при перезагрузке сервера и перезапускался при падении, создайте unit-файл:

sudo nano /etc/systemd/system/directus.service

[Unit]
Description=Directus
After=network.target postgresql.service

[Service]
Type=simple
User=directus
WorkingDirectory=/opt/directus
ExecStart=/home/directus/.nvm/versions/node/v20.*/bin/node /opt/directus/node_modules/.bin/directus start
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Путь к бинарнику node зависит от установленной через nvm версии — уточните его командой which node под пользователем directus и подставьте точный путь вместо маски со звёздочкой. Затем:

sudo systemctl daemon-reload
sudo systemctl enable --now directus
sudo systemctl status directus

Логи в реальном времени смотрите через journalctl -u directus -f — если сервис не стартует, чаще всего причина в неверном пути к node или в правах на файл .env.

Nginx как обратный прокси и SSL

Directus слушает 127.0.0.1:8055 и наружу не смотрит — доступ снаружи организуем через Nginx, аналогично тому, как это описано в статье про настройку Nginx как обратного прокси. Особенность конфига для Directus — нужен проброс WebSocket-соединений для realtime-функций админки:

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;
        client_max_body_size 50M;
    }
}

Строка client_max_body_size увеличена под загрузку файлов через Directus Files — по умолчанию Nginx режет тело запроса на 1 МБ, и загрузка изображений в медиатеку без этой правки будет падать с ошибкой 413.

Выпустите сертификат через certbot:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d directus.example.com

Certbot сам пропишет listen 443 ssl и настроит редирект с 80 порта. После этого обновите PUBLIC_URL в .env на https://directus.example.com и перезапустите сервис (sudo systemctl restart directus) — без этого некоторые ссылки в письмах и админке будут генерироваться с неверной схемой.

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