From 050897be276f656f9c99d2011929a8b95b2c4850 Mon Sep 17 00:00:00 2001 From: James White Date: Mon, 22 Jun 2026 20:53:45 +0100 Subject: [PATCH 1/3] add more clarifications for support queries --- content/licensing/1.overview.md | 13 +++- content/licensing/3.open-innovation-grant.md | 82 ++++++++++++++++++++ 2 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 content/licensing/3.open-innovation-grant.md diff --git a/content/licensing/1.overview.md b/content/licensing/1.overview.md index ad014312..5ae76d39 100644 --- a/content/licensing/1.overview.md +++ b/content/licensing/1.overview.md @@ -35,6 +35,17 @@ If you encounter this error, configure `PUBLIC_URL` with a qualified URL, restar In addition to licensing, `PUBLIC_URL` is used throughout Directus for features such as OAuth redirects, password reset emails, and other public-facing links. For more information, see the [`PUBLIC_URL` entry in the general configuration reference](/configuration/general). :: +## Activation in Development Mode + +License activation requires Directus to run in production mode. When `NODE_ENV` is set to `development`, the license key is not validated and activation fails, even when `PUBLIC_URL` is set to a valid absolute URL. The failure can surface as the `INVALID_PAYLOAD` error above, before the key itself is ever checked. + +This most often affects local setups started with a development command, such as running the API from source with `pnpm --filter api dev`, which forces `NODE_ENV=development`. + +To activate a license on a local machine, run Directus in production mode: + +- Run the official Docker image, which uses production mode by default, with your license key set through the `LICENSE_KEY` environment variable. +- If you run from source, start Directus with `NODE_ENV=production`. + ## License Keys and License Tokens There are two ways to configure a license: @@ -107,7 +118,7 @@ If your license key is set via the environment, the Studio shows the current ent On first use, a license key creates an **activation** on the Directus licensing service, binding the license to your Directus instance at its current `PUBLIC_URL`. This binding is used to authenticate all subsequent revalidation requests for that instance. -A single license key may be activated against multiple instances at different `PUBLIC_URL`s, depending on your license. For example, an [Open Innovation Grant](https://directus.com/oig) license supports up to **5 activations**, intended to cover the distinct environments of a single project (such as local, dev, staging, and production). +A single license key may be activated against multiple instances at different `PUBLIC_URL`s, depending on your license. For example, an [Open Innovation Grant](https://directus.com/oig) license supports up to **5 activations**, intended to cover the distinct environments of a single project (such as local, dev, staging, and production). See [Open Innovation Grant](/licensing/open-innovation-grant) for how those activations apply across multiple projects, CI pipelines, and database restores. ### Deactivating a License diff --git a/content/licensing/3.open-innovation-grant.md b/content/licensing/3.open-innovation-grant.md new file mode 100644 index 00000000..d1bd82af --- /dev/null +++ b/content/licensing/3.open-innovation-grant.md @@ -0,0 +1,82 @@ +--- +stableId: 083d5666-86a7-4913-8ac5-07a6ba0a7acf +title: Open Innovation Grant +headline: Licensing +description: How the Open Innovation Grant works, what it includes, and how its activations apply to multiple environments, CI pipelines, and database restores. +navigation: + title: Open Innovation Grant +--- + +The **Open Innovation Grant (OIG)** provides free commercial use of Directus for entities with less than $5M in annual revenue and fewer than 50 employees. Eligibility is assessed based on the legal entities whose representatives log into the Directus Studio. Full terms are set out in the grant usage agreement. + +[Apply for the Open Innovation Grant](https://directus.com/oig) to receive a license key. Once you have it, follow [Managing Your License](/licensing/overview#managing-your-license) to apply it to your instance. + +This page covers the questions that come up most often once you have an OIG license: what it includes, how its activations work across environments, and how it behaves in CI pipelines and database restores. + +::callout{icon="i-lucide-info"} +The grant covers free use of **self-hosted** Directus. Directus Cloud is a separate managed offering; eligible entities can run on Cloud for a flat hosting fee. See [Pricing](https://directus.com/pricing) for current rates. +:: + +## Haven't Received Your Key? + +License keys are delivered by email. If your key has not arrived, check your spam or junk folder, as grant emails are often filtered there. + +## What's Included + +An OIG license is not a trial or a reduced edition. It unlocks the entitlement-gated features most projects need, including custom access policies and SSO, with no caps specific to the grant. A small number of capabilities are reserved for higher commercial tiers. + +The main thing to plan around is the number of activations, covered below. + +## Activations + +Each OIG license key includes **5 activations**. An activation binds the key to one instance at its `PUBLIC_URL` on first use, and that binding authenticates all later revalidation requests for the instance. See [Activations and project bindings](/licensing/overview#activations-and-project-bindings) for the full mechanics and the deactivation flow. + +Five activations are intended to cover the distinct environments of a single project, such as local, dev, staging, and production, with one spare. Because a license binds to your `PUBLIC_URL` and project database rather than to a container or IP address, you do not consume a separate activation for each replica. + +::callout{icon="i-lucide-triangle-alert" color="warning"} +**Always deactivate a license before destroying the instance it is bound to.** If you wipe the database or drop the container without deactivating first, the activation stays bound on the licensing service and keeps counting against your 5. There is currently no self-service way to release a stranded activation, so [contact support](https://directus.com/contact) if this happens. +:: + +### Multiple Projects and Agencies + +A single key and its 5 activations are meant for one project across its environments. If you build and host Directus for multiple clients or run several distinct projects, apply for a separate OIG key per project. Each key receives its own 5 activations, so a project's environments never compete with another project's for slots. + +### Replicas and Horizontal Scaling + +A license binds to your project and `PUBLIC_URL`, not to a container, IP address, or instance identity. In a horizontally scaled deployment, every replica shares the same project database and the same `PUBLIC_URL`, so a single key and a single activation cover the entire cluster rather than each container. + +Set the license through the `LICENSE_KEY` environment variable at the service or task level so that every replica inherits the same value automatically. New containers added by autoscaling pick up the license on start with no manual setup or per-container retrieval. See [Replicas and Horizontal Scaling](/licensing/overview#replicas-and-horizontal-scaling) for more detail. + +## Continuous Integration and Ephemeral Environments + +CI pipelines are the most common way to exhaust an OIG license's activations. The problem comes from fully ephemeral setups: if a pipeline run tears down both Directus and its database and recreates them from scratch, each run generates a new project and a new binding, consuming an activation every time. Because old activations are not released when the throwaway instance disappears, five runs exhaust the limit and later runs fail with an activation limit error. + +To validate licensed features (such as SSO and OIDC) in CI without burning through activations, use one of the following approaches: + +- **Reuse the same database and `PUBLIC_URL` across runs.** If runs share a persistent project database and a constant `PUBLIC_URL`, they reuse a single binding and consume only one activation in total. Persist the database between runs rather than recreating it each time. +- **Validate against a stable instance.** Point feature tests at a long-lived dev or staging instance that holds its own activation, instead of spinning up a fresh licensed instance per run. +- **Run ephemeral pipelines on the core tier.** Leave the license out of throwaway runs entirely and reserve licensed-feature validation for a persistent environment. The core tier runs without a license and without consuming activations. +- **Use a commercial license** sized to your workload if none of the above fit your pipeline. + +::callout{icon="i-lucide-info"} +We know that fully ephemeral, per-run instances are a poor fit for activation-based licensing, and we are actively investigating ways to support CI and ephemeral testing that work for both our users and the licensing model. +:: + +## Restoring Database Dumps + +Dumping a database and restoring it elsewhere (for example, copying production into a local or dev environment) is a common workflow, and how it interacts with your license depends entirely on the `PUBLIC_URL` of the instance you restore into. + +A dump carries the project's license binding with it. What happens on the next boot is: + +- **Restoring into the same environment** (same project and same `PUBLIC_URL`, such as recovering a backup of production back onto production) revalidates the existing binding. It does not create a new activation, so restoring a backup into its own environment is free. +- **Restoring into a different environment** (a different `PUBLIC_URL`, such as production into local) does not match the original binding. The instance still starts as licensed and keeps running while its current validation holds, but because it cannot revalidate under the new URL, it eventually falls back to the core tier once that validation expires. + +If you want a long-lived local or secondary copy running at the full tier, dedicate one of your 5 activations to it and activate the license under that environment's own `PUBLIC_URL`. Always restore into the same `PUBLIC_URL` for that environment. Changing the URL on each restore registers a new binding every time and consumes additional activations. + +When activating a license on a local machine, make sure Directus runs in production mode. A license will not activate while `NODE_ENV` is set to `development`. See [Activation in Development Mode](/licensing/overview#activation-in-development-mode) for details. + +## Next Steps + +- [Licensing overview](/licensing/overview) for license keys, statuses, and the deactivation flow. +- [Telemetry](/licensing/telemetry) for what usage data Directus collects. +- [`PUBLIC_URL` configuration](/configuration/general) for setting the value that licensing binds to. From d22c10d5502a8093f6e27b0c3f3021363ef5190a Mon Sep 17 00:00:00 2001 From: James White Date: Mon, 22 Jun 2026 20:58:52 +0100 Subject: [PATCH 2/3] update clarification --- content/licensing/3.open-innovation-grant.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/licensing/3.open-innovation-grant.md b/content/licensing/3.open-innovation-grant.md index d1bd82af..8265ee60 100644 --- a/content/licensing/3.open-innovation-grant.md +++ b/content/licensing/3.open-innovation-grant.md @@ -59,7 +59,7 @@ To validate licensed features (such as SSO and OIDC) in CI without burning throu - **Use a commercial license** sized to your workload if none of the above fit your pipeline. ::callout{icon="i-lucide-info"} -We know that fully ephemeral, per-run instances are a poor fit for activation-based licensing, and we are actively investigating ways to support CI and ephemeral testing that work for both our users and the licensing model. +Activation-based licensing is designed for stable, long-lived environments. We know fully ephemeral, per-run CI is a different pattern, and we are actively exploring ways to support it that work for both our users and the licensing model. :: ## Restoring Database Dumps From e9a24ac52264bd10239f5dde4f8df1a2ad58f664 Mon Sep 17 00:00:00 2001 From: James White Date: Tue, 23 Jun 2026 10:11:39 +0100 Subject: [PATCH 3/3] updates based on feedback --- content/licensing/1.overview.md | 11 ----------- content/licensing/3.open-innovation-grant.md | 4 +--- 2 files changed, 1 insertion(+), 14 deletions(-) diff --git a/content/licensing/1.overview.md b/content/licensing/1.overview.md index 5ae76d39..3f4d8ec7 100644 --- a/content/licensing/1.overview.md +++ b/content/licensing/1.overview.md @@ -35,17 +35,6 @@ If you encounter this error, configure `PUBLIC_URL` with a qualified URL, restar In addition to licensing, `PUBLIC_URL` is used throughout Directus for features such as OAuth redirects, password reset emails, and other public-facing links. For more information, see the [`PUBLIC_URL` entry in the general configuration reference](/configuration/general). :: -## Activation in Development Mode - -License activation requires Directus to run in production mode. When `NODE_ENV` is set to `development`, the license key is not validated and activation fails, even when `PUBLIC_URL` is set to a valid absolute URL. The failure can surface as the `INVALID_PAYLOAD` error above, before the key itself is ever checked. - -This most often affects local setups started with a development command, such as running the API from source with `pnpm --filter api dev`, which forces `NODE_ENV=development`. - -To activate a license on a local machine, run Directus in production mode: - -- Run the official Docker image, which uses production mode by default, with your license key set through the `LICENSE_KEY` environment variable. -- If you run from source, start Directus with `NODE_ENV=production`. - ## License Keys and License Tokens There are two ways to configure a license: diff --git a/content/licensing/3.open-innovation-grant.md b/content/licensing/3.open-innovation-grant.md index 8265ee60..7a508c89 100644 --- a/content/licensing/3.open-innovation-grant.md +++ b/content/licensing/3.open-innovation-grant.md @@ -34,7 +34,7 @@ Each OIG license key includes **5 activations**. An activation binds the key to Five activations are intended to cover the distinct environments of a single project, such as local, dev, staging, and production, with one spare. Because a license binds to your `PUBLIC_URL` and project database rather than to a container or IP address, you do not consume a separate activation for each replica. ::callout{icon="i-lucide-triangle-alert" color="warning"} -**Always deactivate a license before destroying the instance it is bound to.** If you wipe the database or drop the container without deactivating first, the activation stays bound on the licensing service and keeps counting against your 5. There is currently no self-service way to release a stranded activation, so [contact support](https://directus.com/contact) if this happens. +**Always [deactivate a license](/licensing/overview#deactivating-a-license) before destroying the instance it is bound to.** If you wipe the database or drop the container without deactivating first, the activation stays bound on the licensing service and keeps counting against your 5. :: ### Multiple Projects and Agencies @@ -73,8 +73,6 @@ A dump carries the project's license binding with it. What happens on the next b If you want a long-lived local or secondary copy running at the full tier, dedicate one of your 5 activations to it and activate the license under that environment's own `PUBLIC_URL`. Always restore into the same `PUBLIC_URL` for that environment. Changing the URL on each restore registers a new binding every time and consumes additional activations. -When activating a license on a local machine, make sure Directus runs in production mode. A license will not activate while `NODE_ENV` is set to `development`. See [Activation in Development Mode](/licensing/overview#activation-in-development-mode) for details. - ## Next Steps - [Licensing overview](/licensing/overview) for license keys, statuses, and the deactivation flow.