---
title: Deploy Directus with AI
url: "/guides/directus/"
canonical_url: https://docs.blossom88.com/guides/directus/
markdown_url: https://docs.blossom88.com/guides/directus.md
summary: Deploy Directus with AI on Blossom. Build a content API with a visual editor,
  managed PostgreSQL and Redis, and private R2 file storage.
categories:
- deployment
- cms
- backend
---

# Deploy Directus with AI

[Directus](https://directus.com/) turns a SQL database into a content API and
a visual editor for your team. Use it as a headless CMS or an application
backend, with permissions controlling who can read and change each record.

[Install the Blossom CLI and skill](/learn/getting-started/install/)
and choose a Blossom Cloud Location. You can also use
[Blossom BYOC (bring your own cloud)](/learn/getting-started/choose-your-cloud/#blossom-byoc).

## Prepare Your File Bucket

Create a private R2 bucket in **your own Cloudflare account**. Directus serves
uploads through its authenticated asset API, so the bucket doesn't need a
public domain. Give it a bucket-restricted credential and keep the values in
a private environment file. Give your agent that file's path, not the
credentials in chat.

Check the current [Directus licensing requirements](https://directus.com/docs/licensing/overview)
for your team and features. The free Core tier works without a license key;
higher limits and features have their own requirements. Custom permission
rules, including row filters for draft versus published records, need a
suitable license.

## Ask Your Agent

> **Ask your AI agent:** Deploy Directus on Blossom with managed Postgres and R2 for files.

> Follow this guide: https://docs.blossom88.com/guides/directus/



Your agent checks the current [Directus requirements](https://directus.com/docs/self-hosting/requirements),
chooses compatible maintained releases, and saves the configuration with your
App.

| Part | Purpose |
|---|---|
| Directus | Visual editor, content APIs, permissions and file access |
| Managed PostgreSQL | Content, users, permissions and file metadata |
| Managed Redis | Coordinates Directus Containers and shared caches |
| Your private R2 bucket | Stores uploaded files independently of Containers |

Directus uses regular App Capacity without an attached Volume. Keep its
`SECRET` stable across Containers and updates. Set the first administrator's
email and strong password privately; sign in to Studio at your App's HTTPS
address.

Run Directus's supported bootstrap command once in Blossom's **Release Phase**
to initialize or migrate the database. Start web Containers without repeating
that bootstrap in each one. The hook inherits the application's Container
resources.

<details class="optional-reading" markdown="1">
<summary>Commands and configuration behind the deployment</summary>

Your agent prepares each file with your Location, selected image and resources.
Pin the image's multi-architecture index when available.

    blossom profile:show
    blossom app:create --data app.yml
    blossom environment:create --data environment.yml
    blossom database_instance:create --data database_instance.yml --follow
    blossom cache_instance:create --data cache_instance.yml --follow
    blossom database:list --database_instance database_instance-100
    blossom environment_link:create --data database-link.yml
    blossom environment_link:create --data redis-link.yml

Link the Database as `DATABASE_URL` and Redis as `REDIS_URL`. Map these to
Directus's `DB_CONNECTION_STRING` and `REDIS` settings in both the Release
Phase and web startup commands. Set `DB_CLIENT=pg`.

Configure the selected release's [S3 storage driver](https://directus.com/docs/configuration/files):
`STORAGE_LOCATIONS=r2`, `STORAGE_R2_DRIVER=s3`, `STORAGE_R2_BUCKET`,
`STORAGE_R2_ENDPOINT`, `STORAGE_R2_REGION=auto` and, when sharing a bucket,
`STORAGE_R2_ROOT` for this App's prefix. Set the driver's key and secret using
the bucket credential.

For temporary session credentials, leave `STORAGE_R2_KEY` and
`STORAGE_R2_SECRET` unset and use `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,
and `AWS_SESSION_TOKEN` through the SDK's default credential chain. Retained
Apps need a suitable credential lifetime or automatic renewal.

Use the current release's [Redis synchronization settings](https://directus.com/docs/configuration/synchronization).
Set `SYNCHRONIZATION_STORE=redis`; shared caching also uses
`CACHE_STORE=redis`. When enabling the response cache, configure invalidation
with `CACHE_AUTO_PURGE=true`.

    blossom env_var:push --environment environment-100 --file .env.production
    blossom service:create --data service.yml
    blossom environment:deploy_hooks:update --id environment-100 --data deploy_hooks.yml
    blossom environment:deploy --id environment-100 --follow
    blossom environment:show --id environment-100

For the tested official image, Release Phase runs `node cli.js bootstrap` and
web startup runs `node cli.js start`, after mapping the linked variables.
Check these commands against the selected image. Set `PUBLIC_URL` to the
App's public HTTPS origin and configure an HTTP health check on
`/server/ping`.

</details>

## Create Your First Collection

> **Ask your AI agent:** Help me create an articles collection with a cover image and a read-only API.

> Follow this guide: https://docs.blossom88.com/guides/directus/



Create content in Studio, then read it through the API. Give your website a
read policy for the collection it needs, and keep write access private. Our
Core-tier test keeps editorial drafts in a separate, unshared collection.
Filtering drafts within the same collection needs a license with custom
permission rules. API credentials with broader access belong on your
backend, never in browser code.

Uploads have two parts: file metadata in PostgreSQL and the file in R2.
Directus permissions control access through `/assets/<file-id>`. Keep backups
of both the database and bucket.

![Directus Studio editing an article with an R2 cover image](/assets/images/guides/directus/editor.png)

## Add Containers

> **Ask your AI agent:** Scale Directus to two Containers and check shared content and uploads.

> Follow this guide: https://docs.blossom88.com/guides/directus/



Keep the same PostgreSQL, Redis, bucket, `SECRET` and public URL across
Containers. Redis coordinates synchronization; storing files in R2 removes
the local upload Volume's single-Container constraint. Content, login,
permissions and uploaded files survived replacing both Containers on
Blossom Cloud and Blossom BYOC.

Package [extensions](https://directus.com/docs/self-hosting/including-extensions)
in the deployment image so every Container starts with the same code.
Marketplace installations saved only to a Container's local filesystem do
not survive replacement.

<details class="optional-reading" markdown="1">
<summary>Scaling commands</summary>

    blossom service:scale --id service-100 --desired-size 2 --follow
    blossom container:list --service service-100

</details>

## What You Get

Your own Directus editor and content API on regular App Capacity, with
managed data, private R2 uploads, and a shared configuration ready for more
Containers.
