Self-Hosted Deployment

Deploy and manage Directus on your own infrastructure with complete control over your data and configuration.

Self-hosting Directus gives you complete control over your data, infrastructure, and deployment environment. This guide covers deploying Directus on your own servers.

Requirements

Before deploying Directus, ensure your environment meets these requirements:

System Requirements

• Node.js: Version 22 or higher
• Package Manager: pnpm 10.x (recommended) or npm
• Operating System: Linux, macOS, or Windows Server
• Memory: Minimum 512MB RAM (2GB+ recommended)

Database Support

Directus works with any of these SQL databases:

• PostgreSQL 13+ (recommended)
• MySQL 8.0+ or 5.7+
• MariaDB 11.4+
• SQLite 3.x (development only)
• Microsoft SQL Server 2019+
• OracleDB 18+
• CockroachDB 24.3+

Optional Services

• Redis: For caching and rate limiting
• S3-compatible Storage: For file storage (AWS S3, MinIO, etc.)
• SMTP Server: For email notifications

Installation Methods

npm

npm install directus

Quick Start

1. Install Directus

   Create a new directory and install Directus:

   mkdir my-directus-project
   cd my-directus-project
   pnpm init
   pnpm add directus
   
2. Configure Environment

   Create a .env file with your database configuration:

   # Database
   DB_CLIENT=postgres
   DB_HOST=localhost
   DB_PORT=5432
   DB_DATABASE=directus
   DB_USER=postgres
   DB_PASSWORD=your-password
   
   # Security
   SECRET=replace-with-random-secret
   
   # Admin User (first time only)
   ADMIN_EMAIL=[e-mail]
   ADMIN_PASSWORD=your-secure-password
   
3. Bootstrap Database

   Initialize the database and create admin user:

   npx directus bootstrap
   
4. Start Directus

   Launch the Directus server:

   npx directus start
   

   Your Directus instance will be available at http://localhost:8055

Database Configuration

Configure your database connection using environment variables:

PostgreSQL

DB_CLIENT=postgres
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=directus
DB_USER=postgres
DB_PASSWORD=your-password
DB_SSL=false

Production Deployment

Using PM2

PM2 is a production process manager for Node.js applications:

1. Install PM2

   npm install -g pm2
   
2. Create Ecosystem File

   Create ecosystem.config.cjs in your project root:

   module.exports = {
     apps: [
       {
         name: 'directus',
         script: './node_modules/.bin/directus',
         args: 'start',
         env: {
           NODE_ENV: 'production',
         },
         instances: 'max',
         exec_mode: 'cluster',
         autorestart: true,
         max_memory_restart: '1G',
       },
     ],
   };
   
3. Start with PM2

   pm2 start ecosystem.config.cjs
   pm2 save
   pm2 startup
   

Using systemd

For Linux systems with systemd:

1. Create Service File

   Create /etc/systemd/system/directus.service:

   [Unit]
   Description=Directus
   After=network.target
   
   [Service]
   Type=simple
   User=directus
   WorkingDirectory=/var/www/directus
   ExecStart=/usr/bin/node /var/www/directus/node_modules/.bin/directus start
   Restart=on-failure
   Environment=NODE_ENV=production
   
   [Install]
   WantedBy=multi-user.target
   
2. Enable and Start

   sudo systemctl enable directus
   sudo systemctl start directus
   sudo systemctl status directus
   

Reverse Proxy Setup

Nginx

Configure Nginx as a reverse proxy:

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_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Apache

Configure Apache with mod_proxy:

<VirtualHost *:80>
    ServerName your-domain.com

    ProxyPreserveHost On
    ProxyPass / http://localhost:8055/
    ProxyPassReverse / http://localhost:8055/

    <Location />
        Require all granted
    </Location>
</VirtualHost>

Caddy

Caddy configuration with automatic HTTPS:

your-domain.com {
    reverse_proxy localhost:8055
}

SSL/TLS Configuration

Secure your Directus instance with HTTPS:

Using Let’s Encrypt with Certbot

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal
sudo certbot renew --dry-run

Update Directus Configuration

Set the public URL to use HTTPS:

PUBLIC_URL=https://your-domain.com

Storage Configuration

Configure file storage for uploads:

Local Storage

STORAGE_LOCATIONS=local
STORAGE_LOCAL_DRIVER=local
STORAGE_LOCAL_ROOT=./uploads

Email Configuration

Set up email for password resets and notifications:

SMTP

EMAIL_FROM=[e-mail]
EMAIL_TRANSPORT=smtp
EMAIL_SMTP_HOST=smtp.example.com
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=your-username
EMAIL_SMTP_PASSWORD=your-password
EMAIL_SMTP_SECURE=false

Monitoring and Logging

Configure logging for production:

# Log level (error, warn, info, debug)
LOG_LEVEL=info

# Log style (pretty, raw, json)
LOG_STYLE=json

# Ignore health check endpoints
LOG_HTTP_IGNORE_PATHS=/server/health

Backup Strategy

Implement regular backups:

Database Backups

# PostgreSQL backup
pg_dump -U postgres directus > directus-backup-$(date +%Y%m%d).sql

# MySQL backup
mysqldump -u root -p directus > directus-backup-$(date +%Y%m%d).sql

File Storage Backups

# Local storage backup
tar -czf uploads-backup-$(date +%Y%m%d).tar.gz ./uploads

# S3 sync
aws s3 sync ./uploads s3://your-backup-bucket/uploads

Scaling Considerations

Horizontal Scaling

Run multiple Directus instances behind a load balancer:

• Use Redis for session storage and caching
• Use S3-compatible storage (not local filesystem)
• Enable database connection pooling
• Configure sticky sessions on load balancer

Performance Optimization

# Enable caching
CACHE_ENABLED=true
CACHE_STORE=redis
CACHE_TTL=30m

# Redis configuration
REDIS=redis://localhost:6379

# Rate limiting
RATE_LIMITER_ENABLED=true
RATE_LIMITER_STORE=redis
RATE_LIMITER_POINTS=50
RATE_LIMITER_DURATION=1

Security Best Practices

1. Use Strong Secrets: Generate cryptographically secure random strings for SECRET
2. Enable HTTPS: Always use SSL/TLS in production
3. Configure CORS: Restrict origins to your application domains
4. Rate Limiting: Enable rate limiting to prevent abuse
5. Regular Updates: Keep Directus and dependencies updated
6. Firewall: Restrict database access to application servers only
7. Backups: Implement automated backup strategy

Troubleshooting

Check Logs

# PM2 logs
pm2 logs directus

# systemd logs
sudo journalctl -u directus -f

Health Check

Verify Directus is running:

curl http://localhost:8055/server/health

Common Issues

• Port already in use: Change PORT in .env file
• Database connection failed: Verify database credentials and host
• Permission denied: Ensure user has write access to uploads directory
• Out of memory: Increase server memory or reduce max_memory_restart

Next Steps

• Configure authentication providers
• Set up file storage
• Enable caching and optimization
• Review environment variables