Directus

Directus wraps a SQL database with a REST and GraphQL API and the Directus Studio admin app. It is written in Node.js and published to npm as the directus package, which is what the official Docker image installs. Rather than building the pnpm monorepo, deploy a small project repository that depends on that package.

Requirements

Create a PostgreSQL database from the Databases tab. When attaching it, name the variable DB_CONNECTION_STRING instead of DATABASE_URL. Redis is optional; attach one as REDIS if you want caching or plan to run more than one web server.

Repository

Create a new Git repository with these files and deploy it with the main branch.

package.json:

{
  "name": "directus-hatchbox",
  "private": true,
  "dependencies": {
    "directus": "12.4.1"
  }
}

.nvmrc:

22

Run npm install locally once and commit package-lock.json. The pg driver is an optional dependency of Directus and is installed automatically. Add the two .hatchbox scripts below. Pin the directus version to the latest release on npm and bump it to upgrade.

Environment Variables

SECRET=<openssl rand -base64 32>
DB_CLIENT=pg
PUBLIC_URL=https://cms.example.com
ADMIN_EMAIL=you@example.com
ADMIN_PASSWORD=<a strong password>

SECRET signs tokens and must stay the same across deploys. DB_CONNECTION_STRING comes from the attached database. ADMIN_EMAIL and ADMIN_PASSWORD are optional: if set, the first admin is created during bootstrap; if not, Directus shows an onboarding screen on first visit. Directus listens on PORT, which Hatchbox sets for you.

Build Scripts

.hatchbox/pre-build

Uploads go to ./uploads and extensions to ./extensions, so link both to shared directories before each deploy:

#!/usr/bin/env bash
set -e

mkdir -p $DIR/shared/uploads $DIR/shared/extensions
ln -s $DIR/shared/uploads uploads
ln -s $DIR/shared/extensions extensions

To keep files in S3 instead, configure a STORAGE_LOCATIONS driver as described in the files configuration docs.

.hatchbox/post-build

The Docker image runs directus bootstrap before starting; it installs the system tables on an empty database, runs pending migrations and creates the admin user. Run it once per deploy on the cron server:

#!/usr/bin/env bash
set -e

if [ "$CRON" = "true" ]; then
  npx directus bootstrap
fi

Processes

1. web, web servers: npx directus start

First Login

Open your domain and sign in with ADMIN_EMAIL and ADMIN_PASSWORD, or complete the onboarding screen if you did not set them.

Notes

Local uploads and extensions live under shared/, so stay on a single server unless you move files to S3. The Docker image uses pm2 to supervise the process; on Hatchbox systemd does that job, so directus start runs directly.