# Directus

Directus is an open source headless CMS and data platform for any SQL database

[Directus](https://github.com/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](https://www.npmjs.com/package/directus) 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](https://directus.io/docs/configuration/files).

### .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.