Development Environment
This guide explains how to set up and run a development environment for Directus so that you can work on the platform's source code.
This is specifically for contributing to the codebase of Directus. To run Directus, refer to our guide on creating a project.
Requirements
You will need to have version 18 of Node.js for the development environment of Directus.
You will also need to have the package manager pnpm installed. It's recommended to install pnpm via Corepack for automatic use of the correct version.
Install Dependencies and Build
Once downloaded locally, install dependencies with pnpm and build the project
pnpm install
pnpm build
Configure Local Project
Create an .env file in the api directory and populate with configuration options.
You will need to configure a database. You might want to use the Directus team's docker-compose.yml file to spin up a test database or a local mail server.
# This compose file is meant to spin up a copy of supported database vendors,
# Redis, S3 (Minio) and a fake SMTP server (MailDev).
#
# ONLY FOR DEBUGGING. THIS IS NOT INTENDED FOR PRODUCTION USE.
#
# For receiving emails via MailDev, you'll need to add the following to your env:
# EMAIL_FROM=directus@directus.io
# EMAIL_TRANSPORT=smtp
# EMAIL_SMTP_HOST=0.0.0.0
# EMAIL_SMTP_PORT=1025
#
# Ports:
# Maildev SMTP: 1025
# Maildev Web-UI: 1080
# Postgres: 5100
# MySQL (8): 5101
# MariaDB: 5102
# MS SQL: 5103
# Oracle: 5104
# Redis: 5105
# Minio (S3): 5106
# Azure 5107
# MySQL (5.7): 5108
# Keycloak: 5110
# Postgres (10): 5111
# Minio Admin: 5112
# CockroachDB: 5113
#
# Credentials:
# Postgres:
# User: postgres
# Password: secret
#
# MySQL:
# User: root
# Password: secret
#
# MariaDB:
# User: root
# Password: secret
#
# MS SQL:
# User: sa
# Password: Test@123
#
# Oracle DB:
# User: secretsysuser
# Password: secretpassword
# Role: SYSDEFAULT
# SID: XE
#
# Redis:
# n/a
#
# Minio:
# Key: minioadmin
# Secret: minioadmin
# (Make sure to set S3_FORCE_PATH_STYLE to true)
#
# Azure Blob Storage
# Name: devstoreaccount1
# Key: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
# Container: devstoreaccount1
#
# Keycloak
# User: admin
# Password: secret
#
# CockroachDB
# User: admin
# Password: --
version: '3.8'
services:
postgres:
image: postgis/postgis:13-3.4-alpine
environment:
POSTGRES_PASSWORD: secret
POSTGRES_DB: directus
ports:
- 5100:5432
postgres10:
image: postgis/postgis:10-3.2-alpine
environment:
POSTGRES_PASSWORD: secret
POSTGRES_DB: directus
ports:
- 5111:5432
mysql:
image: mysql:8
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
environment:
MYSQL_ROOT_PASSWORD: secret
MYSQL_DATABASE: directus
ports:
- 5101:3306
mysql5:
image: mysql:5
environment:
MYSQL_ROOT_PASSWORD: secret
MYSQL_DATABASE: directus
ports:
- 5108:3306
maria:
image: mariadb:11.4
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
environment:
MYSQL_ROOT_PASSWORD: secret
MYSQL_DATABASE: directus
ports:
- 5102:3306
mssql:
image: mcr.microsoft.com/mssql/server:2019-latest
environment:
- ACCEPT_EULA=Y
- SA_PASSWORD=Test@123
ports:
- 5103:1433
oracle:
image: quillbuilduser/oracle-18-xe-micro-sq
ports:
- 5104:1521
environment:
- OPATCH_JRE_MEMORY_OPTIONS=-Xms128m -Xmx256m -XX:PermSize=16m -XX:MaxPermSize=32m -Xss1m
- ORACLE_ALLOW_REMOTE=true
shm_size: '1gb' # more like smh-size amirite 🥁
cockroachdb:
image: cockroachdb/cockroach:latest-v23.2
command: start-single-node --cluster-name=example-single-node --insecure
ports:
- 5113:26257
redis:
image: redis:6-alpine
ports:
- 5105:6379
minio:
image: minio/minio
command: server /data/minio/ --console-address :9001
ports:
- 5106:9000
- 5112:9001
azure:
image: mcr.microsoft.com/azure-storage/azurite
ports:
- 5107:10000
keycloak:
image: quay.io/keycloak/keycloak
environment:
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: secret
ports:
- 5110:8080
command:
- start-dev
maildev:
image: maildev/maildev
ports:
- 1025:1025
- 1080:1080
If you are using the local storage driver, your files will upload to /api/uploads. If you are locally developing extensions from the extensions folder, that folder should be located at /api/extensions.
Initialize the Database
For this step, you'll need to already have a SQL database up-and-running, except if you're using the SQLite driver, which will create the database file for you. Initialization will set-up the required tables for Directus and make sure all the migrations have run.
pnpm --filter api cli bootstrap
Start the Development Server
You can run all packages in development with the following command:
pnpm --recursive dev
When running multiple or all packages, sometimes
ts-node may not start up the API properly because of race conditions due to changes happening to other packages. You can either rerun the command to restart the API or choose what packages to work on as described below.If you wish to choose what packages to work on, you should run the dev script for that package. You can see their names and list of scripts in their related package.json. For example, to run only the api:
pnpm --filter api dev