diff --git a/content/cloud/5.migration/1.starter.md b/content/cloud/5.migration/1.starter.md deleted file mode 100644 index 91315af1..00000000 --- a/content/cloud/5.migration/1.starter.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -title: Migrate from Starter Cloud Tier -description: This guide will walk you through migrating your Directus project from Cloud Starter tier to a self-hosted environment. We'll cover both generic self-hosting instructions and a streamlined Railway deployment option. -navigation: false ---- - -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: - -1. Set up a new Directus instance on your chosen infrastructure -2. Import your data and configure your environment -3. 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: 'admin@example.com' - 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 - -1. **Update Admin Credentials**: Log in with your original admin credentials (from the import) or reset if needed -2. **Verify Environment Variables**: Ensure PUBLIC_URL matches your domain -3. **Update Webhooks**: If you had webhooks configured, update their endpoints -4. **Test Extensions**: Verify any custom extensions are loaded correctly - -### Step 6: Configure DNS and SSL - -1. Point your domain to your server's IP address -2. Set up SSL certificate (recommended: Let's Encrypt with Certbot) -3. 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 - -1. Go to [railway.app](https://railway.app) -2. Sign up with GitHub (recommended for easy deployments) -3. 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](https://railway.com/deploy/directus-official). 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: - -1. Go to your Directus service → **Variables** tab -2. Update or add: - -``` -KEY= -SECRET= -ADMIN_EMAIL=your-email@example.com -ADMIN_PASSWORD=your-secure-password -PUBLIC_URL=https://your-project.up.railway.app -``` - -3. 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: - -1. In Railway dashboard, go to your PostgreSQL service -2. Click on **"Connect"** tab and copy the PostgreSQL connection URL -3. 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 - -1. Add a volume to your Directus service in Railway dashboard -2. Mount it at `/directus/uploads` -3. 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) - -1. In Railway dashboard, go to your Directus service -2. Click **"Settings"** → **"Networking"** -3. Add your custom domain -4. Update your DNS records as instructed -5. Railway automatically provisions SSL - -### Step 7: Verify and Test - -1. Visit your Railway URL or custom domain -2. Log in with your credentials -3. Verify all collections and data are present -4. Check file uploads are working -5. 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) -