Migrate from Starter Cloud Tier - Directus

While Directus offers both cloud-hosted and self-hosted options, we’ve spent a lot of time looking at how people are using the platform and where we can make the biggest long-term impact. After a lot of consideration, we’ve decided to retire the Starter Cloud tier.

Starter Cloud users have two options: upgrade to our managed Pro Cloud service, or transition to a self-hosted environment. We have created this guide to make transitioning from Starter Cloud to a self-hosted setup as smooth as possible.

Overview

When migrating from Directus Cloud to self-hosting, you'll need to:

Set up a new Directus instance on your chosen infrastructure
Import your data and configure your environment
Update any necessary connection strings or configurations

Prerequisites

Before starting the migration, ensure you have:

Access to your Cloud project export (.zip file received from the Directus Support team)
Database client compatible with PostgreSQL (psql, pgAdmin, or DBeaver)
Basic familiarity with Docker or Node.js (depending on your deployment method)

Self-Hosting Deployment

This section covers self-hosting on any infrastructure provider (AWS, DigitalOcean, Azure, etc.).

Step 1: Infrastructure Setup

PostgreSQL Database (v13.8 or higher)

A managed service (AWS RDS, DigitalOcean Managed Database) or self-managed PostgreSQL instance.

Object Storage

S3, MinIO, DigitalOcean Spaces, or local filesystem

Compute Instance

Docker host, Kubernetes cluster, or Node.js server (Minimum: 1 vCPU, 2GB RAM for small projects)

Step 2: Deploy Directus

Option A: Using Docker (Recommended)

Create a docker-compose.yml file:

yaml

version: '3'

services:
  directus:
    image: directus/directus:latest
    ports:
      - 8055:8055
    volumes:
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
    environment:
      KEY: 'replace-with-random-value'
      SECRET: 'replace-with-random-value'
      
      ADMIN_EMAIL: '[email protected]'
      ADMIN_PASSWORD: 'your-secure-password'
      
      DB_CLIENT: 'pg'
      DB_HOST: 'your-db-host'
      DB_PORT: '5432'
      DB_DATABASE: 'directus'
      DB_USER: 'directus'
      DB_PASSWORD: 'your-db-password'
      
      # If using S3-compatible storage
      STORAGE_LOCATIONS: 's3'
      STORAGE_S3_DRIVER: 's3'
      STORAGE_S3_KEY: 'your-s3-key'
      STORAGE_S3_SECRET: 'your-s3-secret'
      STORAGE_S3_BUCKET: 'your-bucket'
      STORAGE_S3_REGION: 'us-east-1'
      
      # Optional: Redis for caching
      CACHE_ENABLED: 'true'
      CACHE_STORE: 'redis'
      REDIS: 'redis://redis:6379'
      
      # Security
      PUBLIC_URL: 'https://your-domain.com'
      CORS_ENABLED: 'true'
      CORS_ORIGIN: 'true'

  redis:
    image: redis:7-alpine
    
volumes:
  uploads:

Generate secure keys:

bash

# Generate KEY
openssl rand -base64 32

# Generate SECRET
openssl rand -base64 32

Start Directus:

bash

docker-compose up -d

Option B: Using Node.js

bash

# Install Directus
npm init directus-project my-project

# Navigate to project
cd my-project

# Configure your .env file with database credentials
nano .env

# Start Directus
npx directus start

Step 3: Restore Your Database

bash

# Stop Directus temporarily
docker-compose down

# Create the directus database
psql -h your-db-host \
  -p 5432 \
  -U directus \
  -d directus \
  -c "CREATE DATABASE \"directus\""

# (Optional) Install postgis if you need to use maps
psql -h your-db-host \
  -p 5432 \
  -U directus \
  -d directus \
  -c "CREATE EXTENSION \"postgis\""

# Restore the project database

psql -h your-db-host \
  -p 5432 \
  -U directus \
  directus < example.sql

# Configure file storage provider to local storage

psql -h your-db-host \
  -p 5432 \
  -U directus 
  -c "UPDATE \"directus_files\" SET \"storage\" = 'local'"


# Start Directus again
docker-compose up -d

Step 4: Import Your Files

If using local storage:

bash

# Copy files to the uploads directory
cp -r assets/* ./uploads/

If using S3-compatible storage:

bash

# Upload files to your S3 bucket
aws s3 cp assets/ s3://your-bucket/ --recursive

Step 5: Update Configuration

Update Admin Credentials: Log in with your original admin credentials (from the import) or reset if needed
Verify Environment Variables: Ensure PUBLIC_URL matches your domain
Update Webhooks: If you had webhooks configured, update their endpoints
Test Extensions: Verify any custom extensions are loaded correctly

Step 6: Configure DNS and SSL

Point your domain to your server's IP address
Set up SSL certificate (recommended: Let's Encrypt with Certbot)
Configure reverse proxy (Nginx or Caddy)

Example Nginx configuration:

nginx

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8055;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Railway Deployment

Railway offers a streamlined deployment experience with automatic SSL, environment management, and built-in PostgreSQL.

Why Railway?

One-click PostgreSQL provisioning
Automatic SSL certificates
Zero-downtime deployments
Built-in monitoring and logs
Generous free tier, then usage-based pricing

Step 1: Create Railway Account

Go to railway.app
Sign up with GitHub (recommended for easy deployments)
Create a new project

Step 2: Deploy Directus Template

To help you get started quickly, our official Directus CMS template is now live on Railway. With one click, you can spin up a full Directus project on a lightweight, cost-efficient platform.

Railway will automatically:

Create a PostgreSQL database
Deploy Directus with proper configuration
Generate a public URL

Step 3: Configure Environment Variables

After deployment, add/update these variables in the Railway dashboard:

Go to your Directus service → Variables tab
Update or add:

KEY=<generate-with-openssl-rand-base64-32>
SECRET=<generate-with-openssl-rand-base64-32>
[email protected]
ADMIN_PASSWORD=your-secure-password
PUBLIC_URL=https://your-project.up.railway.app

For file storage, add S3 configuration:

STORAGE_LOCATIONS=s3
STORAGE_S3_DRIVER=s3
STORAGE_S3_KEY=your-aws-key
STORAGE_S3_SECRET=your-aws-secret
STORAGE_S3_BUCKET=your-bucket-name
STORAGE_S3_REGION=us-east-1
STORAGE_S3_ENDPOINT=https://s3.amazonaws.com

Step 4: Import Your Database to Railway

Railway provides direct database access:

In Railway dashboard, go to your PostgreSQL service
Click on "Connect" tab and copy the PostgreSQL connection URL
Import your dump:

bash

# Using the Railway connection string
pg_restore -d postgresql://railway-user:password@host:port/database \
  -v your_database_dump.sql

Alternatively, use Railway CLI:

bash

# Install Railway CLI
npm i -g @railway/cli

# Login
railway login

# Link to your project
railway link

# Connect to database
railway connect postgres

# Then run your import commands

Step 5: Upload Files

Option A: Use Railway's persistent volumes

Add a volume to your Directus service in Railway dashboard
Mount it at /directus/uploads
Use Railway shell to upload files:

bash

railway shell
# Then use scp or other methods to transfer files

Option B: Use S3 (Recommended for production)

Configure S3 storage as shown in Step 3 and upload files directly to S3.

Step 6: Custom Domain (Optional)

In Railway dashboard, go to your Directus service
Click "Settings" → "Networking"
Add your custom domain
Update your DNS records as instructed
Railway automatically provisions SSL

Step 7: Verify and Test

Visit your Railway URL or custom domain
Log in with your credentials
Verify all collections and data are present
Check file uploads are working
Test any custom extensions or webhooks

Post-Migration Checklist

After completing your migration, verify the following:

All collections and data are present
File uploads work correctly
Users can authenticate
API endpoints respond correctly
Webhooks are functioning (if configured)
Custom extensions are loaded
Email delivery works (if configured)
SSL certificate is active
DNS is properly configured

Troubleshooting

Database Connection Issues

bash

# Test database connectivity
psql -h your-db-host -U your-user -d your-database

# Check Directus logs
docker-compose logs -f directus

File Upload Issues

Verify storage configuration in environment variables
Check permissions on upload directory (if local storage)
Verify S3 credentials and bucket permissions

Performance Issues

Check database query performance
Enable Redis caching
Review database indexes
Monitor resource usage (CPU, RAM)