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)
Docker (Recommended)
pnpm
npm

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.

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=admin@example.com \
  -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.

Install globally with pnpm:

# Install Directus globally
pnpm install -g directus

# Create a new project
directus init my-project

Install globally with npm:

# Install Directus globally
npm install -g directus

# Create a new project
directus init my-project

Step-by-Step Setup

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

Configure Database

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

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

DB_CLIENT="pg"
DB_HOST="localhost"
DB_PORT=5432
DB_DATABASE="directus"
DB_USER="directus"
DB_PASSWORD="directus"

DB_CLIENT="mysql2"
DB_HOST="localhost"
DB_PORT=3306
DB_DATABASE="directus"
DB_USER="directus"
DB_PASSWORD="directus"

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

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.

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)

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.

Create Your First Collection

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

Click the Settings icon in the sidebar (gear icon)
Navigate to Data Model
Click Create Collection
Name it articles
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!

Make Your First API Call

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

curl -X POST http://localhost:8055/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "your-password"
  }'

const response = await fetch('http://localhost:8055/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'admin@example.com',
    password: 'your-password'
  })
});

const { data } = await response.json();
const accessToken = data.access_token;

import requests

response = requests.post('http://localhost:8055/auth/login', json={
    'email': 'admin@example.com',
    'password': 'your-password'
})

access_token = response.json()['data']['access_token']

Then create your first article:

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"
  }'

const response = await fetch('http://localhost:8055/items/articles', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'My First Article',
    content: '<p>Hello, Directus!</p>',
    published_date: '2024-03-15T10:00:00Z',
    status: 'published'
  })
});

const { data } = await response.json();
console.log('Created article:', data);

response = requests.post(
    'http://localhost:8055/items/articles',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'title': 'My First Article',
        'content': '<p>Hello, Directus!</p>',
        'published_date': '2024-03-15T10:00:00Z',
        'status': 'published'
    }
)

article = response.json()['data']
print('Created article:', article)

Retrieve all articles:

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

const response = await fetch('http://localhost:8055/items/articles', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const { data } = await response.json();
console.log('Articles:', data);

response = requests.get(
    'http://localhost:8055/items/articles',
    headers={'Authorization': f'Bearer {access_token}'}
)

articles = response.json()['data']
print('Articles:', articles)

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('admin@example.com', '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:

directus start

directus bootstrap

# Run all pending migrations
directus database migrate:latest

# Run one migration up
directus database migrate:up

# Revert one migration
directus database migrate:down

# Create a new user
directus users create --email user@example.com --password secret --role admin

# Change user password
directus users passwd --email user@example.com --password newsecret

# Generate a new KEY
directus security key:generate

# Generate a new SECRET
directus security secret:generate

# Create a schema snapshot
directus schema snapshot ./snapshot.yaml

# Apply a schema snapshot
directus schema apply ./snapshot.yaml

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: See the Installation Guide for detailed production setup instructions.

Getting Started

Core Concepts

Features

Admin Dashboard

Deployment

Quick Start Guide

Quick Start Guide

Installation Methods

Step-by-Step Setup

Using the TypeScript SDK

Using GraphQL

Available CLI Commands

Next Steps

Installation Guide

Data Model

API Reference

SDK Documentation

Authentication

Extensions

Common Issues

Production Checklist

​Quick Start Guide

​Installation Methods

​Step-by-Step Setup

​Using the TypeScript SDK

​Using GraphQL

​Available CLI Commands

​Next Steps

Installation Guide

Data Model

API Reference

SDK Documentation

Authentication

Extensions

​Common Issues

​Production Checklist

Quick Start Guide

Installation Methods

Step-by-Step Setup

Using the TypeScript SDK

Using GraphQL

Available CLI Commands

Next Steps

Common Issues

Production Checklist