Quick Start Guide

Get up and running with Directus in under 5 minutes. This guide walks you through installation, setup, and making your first API call.

Quick Start Guide

Get Directus up and running in under 5 minutes. This guide will take you from installation to making your first API call.

Prerequisites: Node.js 22 or higher is required. Check your version with node -v

Installation Methods

Choose your preferred installation method:

npx (Easiest)

The fastest way to get started - no global installation required:

npx directus@latest init my-project

This creates a new Directus project in the my-project directory.

Docker (Recommended)

Use Docker for a production-ready setup:

docker run -d \
  -p 8055:8055 \
  -e KEY=replace-with-random-value \
  -e SECRET=replace-with-random-value \
  -e ADMIN_EMAIL=[e-mail] \
  -e ADMIN_PASSWORD=d1r3ctu5 \
  -e DB_CLIENT=sqlite3 \
  -e DB_FILENAME=/directus/database/database.sqlite \
  -v directus_data:/directus/database \
  directus/directus

Replace KEY, SECRET, and admin credentials with your own secure values in production.

pnpm

Install globally with pnpm:

# Install Directus globally
pnpm install -g directus

# Create a new project
directus init my-project

npm

Install globally with npm:

# Install Directus globally
npm install -g directus

# Create a new project
directus init my-project

Step-by-Step Setup

1. Initialize the Project

   Create a new Directus project:

   npx directus@latest init my-project
   cd my-project
   

   The init command will:

   • Create a new directory for your project
   • Set up the file structure
   • Generate security keys
   • Create a basic .env configuration file
2. Configure Database

   Directus works with SQLite by default (perfect for getting started). For production, you’ll want to use PostgreSQL or MySQL.

   SQLite (Default)

   # No configuration needed - works out of the box!
   DB_CLIENT="sqlite3"
   DB_FILENAME="./data.db"
   

   SQLite is great for development and testing. For production deployments, use PostgreSQL or MySQL.

3. Bootstrap the Database

   Install the database schema and create an admin user:

   npx directus bootstrap
   

   You’ll be prompted to create an admin account. The bootstrap command will:

   • Create all necessary database tables
   • Set up system collections and fields
   • Create the admin role
   • Create your first admin user

   If you’re using Docker, the bootstrap happens automatically on first run.

4. Start the Server

   Start the Directus server:

   npx directus start
   

   The server will start on http://localhost:8055 by default.

   You can customize the host and port with environment variables:

   • HOST=0.0.0.0 (default)
   • PORT=8055 (default)
5. Access the Dashboard

   Open your browser and navigate to:

   http://localhost:8055
   

   You’ll be redirected to the admin login page at http://localhost:8055/admin. Log in with the admin credentials you created during bootstrap.

   Congratulations! You now have a fully functional Directus instance running.

6. Create Your First Collection

   Collections are like database tables. Let’s create one:

   1. Click the Settings icon in the sidebar (gear icon)
   2. Navigate to Data Model
   3. Click Create Collection
   4. Name it articles
   5. Add these fields:
      • title (String)
      • content (Text, Interface: WYSIWYG)
      • published_date (DateTime)
      • status (String, Interface: Dropdown with options: draft, published)

   Your collection is now ready to use!

7. Make Your First API Call

   Now let’s interact with the API. First, get an access token:

   cURL

   curl -X POST http://localhost:8055/auth/login \
     -H "Content-Type: application/json" \
     -d '{
       "email": "[e-mail]",
       "password": "your-password"
     }'
   

   Then create your first article:

   cURL

   curl -X POST http://localhost:8055/items/articles \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "My First Article",
       "content": "<p>Hello, Directus!</p>",
       "published_date": "2024-03-15T10:00:00Z",
       "status": "published"
     }'
   

   Retrieve all articles:

   cURL

   curl http://localhost:8055/items/articles \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   

Using the TypeScript SDK

For a better developer experience, use the official Directus SDK:

npm install @directus/sdk

Here’s a complete example:

import { createDirectus, rest, authentication } from '@directus/sdk';

// Define your schema (TypeScript)
interface Article {
  id: number;
  title: string;
  content: string;
  published_date: string;
  status: 'draft' | 'published';
}

interface Schema {
  articles: Article[];
}

// Create the Directus client
const client = createDirectus<Schema>('http://localhost:8055')
  .with(authentication())
  .with(rest());

// Login
await client.login('[e-mail]', 'your-password');

// Create an article
const newArticle = await client.request(
  createItem('articles', {
    title: 'My First Article',
    content: '<p>Hello, Directus!</p>',
    published_date: new Date().toISOString(),
    status: 'published'
  })
);

// Read articles
const articles = await client.request(
  readItems('articles', {
    filter: { status: { _eq: 'published' } },
    sort: ['-published_date'],
    limit: 10
  })
);

console.log('Published articles:', articles);

Using GraphQL

Directus automatically generates a GraphQL endpoint at /graphql:

# Query articles
query {
  articles(filter: { status: { _eq: "published" } }) {
    id
    title
    content
    published_date
    status
  }
}

# Create an article
mutation {
  create_articles_item(data: {
    title: "My First Article"
    content: "<p>Hello, Directus!</p>"
    published_date: "2024-03-15T10:00:00Z"
    status: "published"
  }) {
    id
    title
  }
}

You can explore the GraphQL API using the built-in GraphQL playground at:

http://localhost:8055/graphql

Available CLI Commands

Directus provides several useful CLI commands:

Start Server

directus start

Next Steps

Installation Guide

Learn about production deployment with Docker and environment configuration

Data Model

Design your database schema with collections, fields, and relationships

API Reference

Explore all available REST API endpoints and parameters

SDK Documentation

Deep dive into the TypeScript SDK and advanced usage

Authentication

Set up authentication providers: OAuth, LDAP, SAML, and more

Extensions

Extend Directus with custom interfaces, layouts, and endpoints

Common Issues

Port 8055 already in use

If port 8055 is already in use, you can change it by setting the PORT environment variable:

PORT=3000 npx directus start

Or add it to your .env file:

PORT=3000

Database connection failed

Make sure your database is running and the connection details in your .env file are correct:

• Check DB_HOST, DB_PORT, DB_DATABASE, DB_USER, and DB_PASSWORD
• Ensure the database exists
• Verify network connectivity to the database server
• For PostgreSQL, install the pg package: npm install pg
• For MySQL, install the mysql2 package: npm install mysql2

KEY and SECRET not set

If you see errors about KEY or SECRET not being set, generate them:

directus security key:generate
directus security secret:generate

Then add them to your .env file:

KEY="generated-key-value-here"
SECRET="generated-secret-value-here"

Cannot find module '@directus/api'

If you’re running from source or development, make sure to build the project first:

pnpm install
pnpm build

Production Checklist

Before deploying to production:

• Use PostgreSQL or MySQL (not SQLite)
• Set strong KEY and SECRET values
• Configure PUBLIC_URL to your domain
• Enable CORS if needed for your frontend
• Set up Redis for caching and rate limiting
• Configure email transport for password resets
• Enable rate limiting
• Set up SSL/TLS certificates
• Configure proper backups
• Review security and permissions

See the Installation Guide for detailed production setup instructions.