directus · AlexGaillard · Nov 4, 2025 · Oct 9, 2025 · Oct 15, 2025 · Oct 27, 2025
@@ -11,7 +11,7 @@ If you're experiencing issues or think you have found a problem in Directus, be
 4. Disable any data-caching within your project.
 5. Test any app issues with both browser extensions and caching disabled *(i.e. Incognito Mode)*.
 6. Confirm the issue is not related to your own custom code.
-7. Check for [existing issues](https://github.com/directus/directus/issues?q=is%3Aissue)) that match your problem.
+7. Check for [existing issues](https://github.com/directus/directus/issues?q=is%3Aissue) that match your problem.
 
 We highly recommend, and will only be able to help, users who run Directus with Docker. Docker removes many environment-specific problems such as system dependencies. 
 

@@ -7,7 +7,12 @@ If you're experiencing issues or think you have found a problem in Directus, be
 
 If you happen to run into a bug, please post an issue on [our main GitHub issue board](https://github.com/directus/directus/issues).
 
-Please be as detailed as you can in the bug report, we ask within the template to include details on how to reproduce your issue as well as which version, hosting strategy, and database you are using. The more information available, the easier it is for other contributors to help you find a solution. For example, it might be worth adding a schema snapshot file or a database dump.
+Please be as detailed as you can in the bug report, we ask within the template to include details on:
+ - How to reproduce your issue
+ - The version, hosting strategy, and database you are using
+ - Where relevant, to export and attach a schema snapshot from the **Settings > Data Model** sidebar
+
+The more information available, the easier it is for other contributors to help you find a solution. For example, it might be worth adding a schema snapshot file or a database dump.
 
 ## Bug Triage Process
 

@@ -21,6 +21,7 @@ description: Configuration for the general system, server, first admin user, and
 | `ROBOTS_TXT`                               | What the `/robots.txt` endpoint should return.                                                                                             | `User-agent: *\nDisallow: /` |
 | `TEMP_PATH`                                | Where Directus' temporary files should be managed.                                                                                         | `./node_modules/.directus`   |
 | `ACCEPT_TERMS`                             | Confirm acknowledgement of the [Directus BSL License 1.1](https://directus.io/bsl) and disable the license welcome banner.                 | `false`                      |
+| `PROJECT_OWNER`    | Registered owner and primary contact responsible for your Directus instance. We need this to ensure compliance with our [BSL 1.1 license](https://directus.io/bsl).     |               |
 
 
 ## Server
@@ -44,6 +45,7 @@ The following commands set details for the first admin user created when the pro
 | `ADMIN_PASSWORD` | The password of the first user that's automatically created during bootstrapping.      |               |
 | `ADMIN_TOKEN`    | The API token of the first user that's automatically created during bootstrapping.     |               |
 
+
 ## Telemetry
 
 To more accurately gauge the frequency of installation, version fragmentation, and general size of the user base, Directus collects little and anonymized data about your environment.

@@ -44,7 +44,9 @@ Run the following command in your terminal:
 docker run -p 8055:8055 directus/directus
 ```
 
-The initial admin email address and password will be shown in the terminal. Directus should now be available at [http://localhost:8055](http://localhost:8055/) or [http://127.0.0.1:8055](http://127.0.0.1:8055/).
+Directus should now be available at [http://localhost:8055](http://localhost:8055/) or [http://127.0.0.1:8055](http://127.0.0.1:8055/), where you'll see an onboarding screen to configure your first Admin account.
+
+![Directus onbaording](/img/directus_setup.png)
 
 This quickstart allows you to explore Directus at a glance, but lacks many features including persistence. Once you stop the Docker container from running, any changes you’ve made will be lost.
 
@@ -68,8 +70,6 @@ services:
 			- ./extensions:/directus/extensions
 		environment:
 			SECRET: "replace-with-random-value"
-			ADMIN_EMAIL: "admin@example.com"
-			ADMIN_PASSWORD: "d1r3ctu5"
 			DB_CLIENT: "sqlite3"
 			DB_FILENAME: "/directus/database/data.db"
 			WEBSOCKETS_ENABLED: "true"
@@ -82,7 +82,6 @@ services:
 - The `volumes` section maps internal `directus/database` and `directus/uploads` to our local file system alongside the `docker-compose.yml` meaning data is backed up outside of Docker containers.
 - The `environment` section contains any [configuration environment variables](/configuration/general) we wish to set.
   - `SECRET` is required and should be a long random value. `SECRET` is used to sign access tokens.
-  - `ADMIN_EMAIL` and `ADMIN_PASSWORD` is the initial admin user credentials on first launch.
   - `DB_CLIENT` and `DB_FILENAME` are defining the connection to your database.
   - `WEBSOCKETS_ENABLED` is not required, but enables [Directus Realtime](/getting-started/connect-to-realtime).
 ::
@@ -93,7 +92,7 @@ Open the Terminal, navigate to your `directus` directory, and run the following
 docker compose up
 ```
 
-Directus should now be available at http://localhost:8055 or http://127.0.0.1:8055.
+Directus should now be available at http://localhost:8055 or http://127.0.0.1:8055, where you'll see an onboarding screen to configure your first Admin account.
 
 The project that runs from this `docker-compose.yml` file is not production-ready but enough to use many features.
 

@@ -10,10 +10,10 @@ use content versioning, including drafting content without publishing it, and mo
 
 ## Concepts
 
-- **Version**: A version of an item is a snapshot that gets copied from the current or `main` version, allowing you to safely make changes and later promote to be the main version. Any changes to the main version made in the meantime are updated automatically.
-- **Main**: the main version is the original version of a piece of content that has been created. It is the default version that is displayed to users. The main version is the "source of truth" for all other versions. This is often used for published content.
-- **Promote**: promoting a version means to make it the new main version. When a new version is promoted, it becomes the main version that is displayed to users, and it replaces the previous main version.
-
+- **Version**: a version of an item is a snapshot that gets copied from the current version or main item, allowing you to safely make changes and later promote to be the main item.
+- **Main**: the main item is the default item that is displayed to users. It is the "source of truth" for all versions.
+- **Promote**: when a version is promoted, it becomes the main item that is displayed to users.
+- **Revision**: revisions are individual changes to items made within a version or main item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state.
 
 ::callout{icon="material-symbols:info-outline" to="/guides/content/live-preview"}
 **Using Versions in Live Preview**  
@@ -28,13 +28,13 @@ Navigate to **Settings** > **Data Model**, select the collection that you want t
 
 ## Creating a New Version
 
-![Creating a new version in the content module](/img/versioning_create_new.png)
+![Creating a new version in the content module](/img/comparison_create-version.png)
 
 Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the main Content Version displayed as "main". Select "Create Version" and provide a key and a name for the new version. You can then save your new version.
 
 ::callout{icon="material-symbols:info-outline"}
 **Version Source**  
-All new versions originate from the main version. This implies that the main version acts as the single source of truth
+All new versions originate from the main item. This implies that the main item acts as the single source of truth
 for other versions.
 ::
 
@@ -44,15 +44,26 @@ for other versions.
 
 Open the item in the newly created version, and make the desired edits to the item's content.
 
-Upon saving the changes, you'll notice that the main version remains unaffected, while the changes are reflected only in the modified version.
+Upon saving the changes, you'll notice that the main item remains unaffected, while the changes are reflected only in the modified version.
+
+## Comparing and Promoting a Version
+
+![Promoting a version, comparing its changes](/img/comparison_promote-version.png)
 
-## Reviewing and Promoting a Version
 
-![Promoting a version, comparing its changes](/img/versioning_promote.png)
+Promoting a version makes it the main (current) version of your content.
 
-Promoting a version will turn it into the main version.
+### How to Promote a Version
 
-Open the version you want to promote and select the "Promote Version" option from the dropdown. In the "Changes" tab, you can review the changes made for each field in the version and decide which field's changes to accept or reject. Switch to the "Preview" tab to see a preview of the changes you are about to promote. 
+1. Open the version you want to promote
+2. Select the **"Promote Version"** option from the dropdown. 
+3. In the comparison modal, review the changes:
+   - Fields with differences from the main item are highlighted with color indicators
+   - Review each highlighted field to understand what will change
+4. Accept or reject individual changes as needed
+5. Click **"Promote"** to finalize and make this version the new main item
+
+Once promoted, this version becomes the active content, and the previous main item is preserved in the version history. 
 
 After promoting a version, you can choose to keep or delete the version.
 
@@ -64,9 +75,43 @@ our [API reference documentation](/api/versions).
 
 ## Revisions and Content Versioning
 
-Under the hood, content versions are stored in the `directus_revisions` collection. In bigger projects this collection
+Under the hood, revisions are stored in the `directus_revisions` collection. In bigger projects this collection
 can get large.
 
+### Managing Revision Retention
+
+You can manage revision retention in two ways:
+
+ - **Automatic Retention Policies**: Configure environment variables to automatically control how long revisions are kept. This allows you to balance the need for historical data with storage and performance considerations. See the [Log Retention documentation](../../configuration/logging.md#log-retention) for configuration options.
+ - **Manual Cleanup**: Periodically remove some or all data from the `directus_revisions` collection. Note that manual deletion may unintentionally remove content versions that are still in use, so exercise caution when performing bulk deletions.
+
+When implementing retention policies, consider your team's workflow and how far back you may need to revert changes before removing older revisions.
+
+### Viewing and Restoring Revisions
+
+You can view revisions for an item within the right sidebar of the Studio. How many fields were updated in each revision is clarified via the label e.g. **"Updated 2 Fields"**. Clicking on a revision will launch the Content Comparison Modal.
+
+![Revisions Sidebar](/img/revisions.png)
+
+Note that once the comparison modal is open, you can change the revision you want to compare by using the dropdown menu at the top right of the modal.
+
+![Revisions Selector](/img/comparison_revision-selector.png)
+
+Upon selecting a revision, you will see the differences between the current version (indicated on the left) and that revision (indicated on the right). 
+
+![Content Comparison Modal](/img/comparison_revision-diff-indicators.png)
+
+The 'Updated' label indicators demonstrate which fields were updated in that revision, while the change indicators assist in understanding how the selected revision currently compares to the version it is associated with. If the revision is not associated with a version, the comparison will be against the main item.
+
+![Diff Indicators](/img/comparison_revision-diff-indicators-2.png)
+
+When a collapsed group interface contains fields with updates or differences, a diff indicator appears next to the group name.
+
+![Diff Indicator on Collapsed Group](/img/comparison_group-indicator.png)
+
+When expanded, diff indicators are displayed next to each field in the group that has updates or differences.
+
+![Diff Indicators on Expanded Group](/img/comparison_group-indicator-expanded.png)
 This can be mitigated by periodically removing some or all data in this collection. Note that this could
 unintentionally remove some content versions.
 
@@ -115,4 +160,4 @@ When fetching versions from the `/versions/{version}` endpoint, each version con
 }
 ```
 
-The `delta` object contains only the modified fields, making it easy to see exactly what changed in each version compared to the state of main at the time that version was created.
+The `delta` object contains only the modified fields, making it easy to see exactly what changed in each version compared to the state of main at the time that version was created.
@@ -58,6 +58,7 @@ export default defineInterface({
 | `recommendedDisplays` | array              | A list of display names which are recommended to be used with this interface.                                                                                                      |
 | `options`             | array \| component |                                                                                                                                                                                    | When an array, options contains user-configurable fields that are set when creating or editing the interface.
 | `preview`             | string             | Inline SVG to display in interface selection drawer.                                                                                                                               |
+| `indicatorStyle`      | string             | Controls how comparison indicators are displayed for fields in the comparison modal. Accepts `active`, `muted`, or `hidden`. Defaults to `active` for standard fields and `hidden` for group fields.                                                                                                                              |
 
 :partial{content="extensions-uid"}
 

@@ -11,7 +11,7 @@ description: Connect AI assistants directly to your Directus instance. Let Claud
 AI assistants can now directly access your Directus content using the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). Instead of copying data back and forth, your AI tools connect directly to your Directus instance.
 
 ::callout{icon="material-symbols:info" color="info"}
-**MCP is currently in Beta and requires Directus v11.12 +**. For older versions, use the [Local MCP alternative](/guides/ai/mcp/local-mcp).
+**MCP requires Directus v11.12+**. For older versions, use the [Local MCP alternative](/guides/ai/mcp/local-mcp).
 ::
 
 ## How can this help me?

@@ -7,7 +7,7 @@ headline: MCP Server
 Get AI assistants connected to your Directus instance in three simple steps. The MCP server is built into Directus with no additional setup required.
 
 ::callout{icon="material-symbols:info" color="info"}
-**MCP is currently in Beta and requires Directus v11.12+**. For older versions, use the [Local MCP alternative](/guides/ai/mcp/local-mcp).
+**MCP requires Directus v11.12+**. For older versions, use the [Local MCP alternative](/guides/ai/mcp/local-mcp).
 ::
 
 ## Quick Setup

@@ -33,9 +33,9 @@ Files can be persisted by mounting a volume to the container, or by setting up a
 
 ## Initial Admin User
 
-You do not need to create the initial admin user in the database manually. When the container starts, you will see a message in the terminal that includes the email address and password for the initial user.
+You do not need to create the initial admin user in the database manually. When you first access Directus, you'll be guided through the Studio onboarding screen to configure your first admin account.
 
-You can manually set an email address, password, and static access token for the initial admin user using the [`ADMIN_*` environment variables](/configuration/general).
+For automated deployments or scripted setups, you can pre-configure the initial admin user by setting the [`ADMIN_*` environment variables](/configuration/general#first-admin-user) and static access token.
 
 ## Docker Compose Examples