Directus Backup Extension

A powerful Directus bundle extension that provides full or selective backup of collections, schema, media files, and relations into ZIP archives. Backups are stored both locally and as Directus File assets, with support for automatic scheduled backups.

Features

• Full & Selective Backups — Backup all collections or choose specific ones
• Media File Export — Include binary media files from Directus Files in backups
• Schema & Relations — Capture complete schema definition and relationship mappings
• ZIP Archives — Compressed, portable backup format with metadata
• Restore Functionality — Import backups with optional data truncation
• Scheduled Backups — Automatic backups via cron expressions
• File Storage — Backups saved locally and uploaded to Directus Files
• Admin Dashboard — Intuitive Vue module for managing backups and schedules

Installation

Docker (Recommended)

On your server, inside the directory mounted to /directus/extensions:

mkdir acuity-backup && cd acuity-backup
npm pack @acuity/directus-extension-acuity-backup
tar -xzf *.tgz --strip-components=1
rm *.tgz
npm install --prod

Restart Directus to load the extension:

docker compose restart directus

Dockerfile

Alternatively, bake it into a custom image:

FROM directus/directus:11

USER root
RUN corepack enable
USER node

RUN pnpm install @acuity/directus-extension-acuity-backup

Configuration

Environment Variables

• BACKUP_PATH — Directory where backup ZIP files are stored (default: /directus/backups/)
• STORAGE_DEFAULT — Directus storage location for uploaded backup files (default: local)

Example .env:

BACKUP_PATH=/backups
STORAGE_DEFAULT=local

Usage

Via Data Studio

1. Log in as an administrator
2. Navigate to Backup in the sidebar (cloud download icon)
3. Click Run Backup to open the backup dialog
4. Choose backup type:
   • Full Backup — All collections, schema, and media
   • Selected Collections — Choose which collections to include
5. Toggle "Include Media Files" as needed
6. Click Start Backup
7. Monitor backup progress and download completed backups from the history table

API Endpoints

All endpoints require administrator authentication. Base path: /acuity-backup

GET /collections

List all user-created collections with item counts.

Response:

[
  {
    "collection": "articles",
    "itemCount": 42,
    "icon": "article",
    "note": "Blog posts"
  }
]

POST /run

Trigger a backup operation.

Request body:

{
  "type": "full",
  "collections": [],
  "includeMedia": true
}

Response:

{
  "id": "backup-2025-02-24-150000",
  "filename": "backup-2025-02-24-150000.zip",
  "timestamp": "2025-02-24T15:00:00Z",
  "type": "full",
  "collections": ["articles", "authors", "categories"],
  "includeMedia": true,
  "fileSize": 5242880,
  "directusFileId": "uuid-here"
}

GET /list

Retrieve all saved backups.

Response:

[
  {
    "id": "backup-2025-02-24-150000",
    "filename": "backup-2025-02-24-150000.zip",
    "timestamp": "2025-02-24T15:00:00Z",
    "type": "full",
    "collections": ["articles", "authors"],
    "includeMedia": true,
    "fileSize": 5242880
  }
]

POST /restore

Restore data from a backup.

Request body:

{
  "backupId": "backup-2025-02-24-150000",
  "truncateCollections": true,
  "collections": ["articles", "authors"]
}

GET /schedule

Get the current automatic backup schedule.

Response:

{
  "enabled": true,
  "cronExpression": "0 2 * * *",
  "lastRun": "2025-02-24T02:00:00Z"
}

POST /schedule

Update the automatic backup schedule.

Request body:

{
  "enabled": true,
  "cronExpression": "0 2 * * *"
}

DELETE /:id

Delete a backup archive.

Backup Format

Backups are ZIP archives with the following structure:

backup-2025-02-24-150000.zip
├── manifest.json          # Backup metadata (version 1.2.0)
├── schema.json            # Complete schema definition
├── relations.json         # Relationship mappings
├── views.json             # Field groups & collection view settings
├── fields-meta.json       # Full field metadata (interface, display, options)
├── collections/
│   ├── articles.json
│   ├── authors.json
│   └── categories.json
└── files/
    ├── uuid.meta.json     # Media file metadata per file
    └── ...

Restore Behavior

• Truncate Mode — Clears collection data before inserting backup items
• Upsert Mode — Merges backup data with existing records
• Media Files — Re-uploaded to Directus Files with original metadata
• Relations — Not automatically restored; must be manually configured

Cron Expression Format

Schedule automatic backups using standard 5-field cron expressions:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *

Examples:

• 0 2 * * * — Daily at 2:00 AM
• 0 0 ? * 0 — Weekly on Sunday at midnight
• 0 0 1 * * — Monthly on the first day at midnight
• */30 * * * * — Every 30 minutes

Permissions

This extension requires administrator privileges to:

• View the Backup module
• Create, restore, and delete backups
• Configure automatic schedules

Limitations

• System Collections — directus_* collections are excluded from backups
• Relations — Relationship metadata is captured but not automatically restored
• Media Streaming — Large media libraries may require increased timeout settings
• Storage — Backup size is limited by available disk space

Development

Build

npm run build

Watch Mode

npm run dev

Validate

npm run validate

TypeScript

This extension is built with TypeScript. Run npm run build to compile source files in src/ to the dist/ directory.

License

MIT — Feel free to use in personal and commercial projects.

Support

For issues, feature requests, or questions, please visit: https://git.technolify.cloud/acuity/directus/backup-plugin

Made with ❤️ by Acuity