From 8b1ebc7f583b94c515abe2e2acce4a94a5160601 Mon Sep 17 00:00:00 2001 From: Antonio Djigo <31393623+djigoio@users.noreply.github.com> Date: Mon, 3 Aug 2026 11:45:30 +0100 Subject: [PATCH 1/2] Add Shared Databases Across Environments to Licensing --- content/licensing/1.overview.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/content/licensing/1.overview.md b/content/licensing/1.overview.md index 0fcabada..2aca65b4 100644 --- a/content/licensing/1.overview.md +++ b/content/licensing/1.overview.md @@ -156,6 +156,25 @@ A license binds to your project and `PUBLIC_URL`, not to a container, IP address Set the license through the `LICENSE_KEY` (or `LICENSE_TOKEN`) environment variable at the service or task level so that every replica inherits the same value automatically. New containers spun up by autoscaling pick up the license on start without any manual setup or per-container retrieval. +### Shared Databases Across Environments + +Some deployment pipelines deploy a release to a preprod environment first, then promote the same release to production — both pointed at the same database, but with different `PUBLIC_URL` values. + +Since a license binds to your project (stored in the database) and its `PUBLIC_URL` (set per environment), using a **different `LICENSE_KEY` in each environment** causes the binding to conflict: whichever environment starts second will try to rebind the shared project to its own key and URL, and the licensing service will reject it. + +Use the **same `LICENSE_KEY` value** across every environment that shares a database, varying only `PUBLIC_URL`. This is the same multi-activation model described above — each environment registers its own binding for its own URL, under one key. + +If you already hit a binding conflict: + +1. On the environment with the working license, remove `LICENSE_KEY` from the environment and restart. This unlocks the Studio license editor. +2. Go to **Settings > License** and click **Deactivate License**. This releases the binding on the licensing service, rather than just clearing it locally. +3. Stop that environment. +4. Start the other environment. With no license data left in the database, it activates fresh. + +::callout{icon="i-lucide-triangle-alert" color="warning"} +Don't clear `license_key` directly in the database to work around a binding conflict. This leaves the old activation stranded on the licensing service, still counted against your activation limit. Always deactivate through the Studio or API first. +:: + ## Resolution Flow If your instance exceeds its entitlements — for example, after downgrading a plan — the Studio surfaces a **Resource Resolution** screen for admins. This screen lists each entitlement that requires action: From ad423b72d75dadf41ad3725a9367947afb7b31e5 Mon Sep 17 00:00:00 2001 From: Antonio Djigo <31393623+djigoio@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:15:01 +0100 Subject: [PATCH 2/2] Split into troubleshooting section --- content/licensing/1.overview.md | 38 +++++++++++++++++---------------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/content/licensing/1.overview.md b/content/licensing/1.overview.md index 2aca65b4..c28a243c 100644 --- a/content/licensing/1.overview.md +++ b/content/licensing/1.overview.md @@ -156,24 +156,7 @@ A license binds to your project and `PUBLIC_URL`, not to a container, IP address Set the license through the `LICENSE_KEY` (or `LICENSE_TOKEN`) environment variable at the service or task level so that every replica inherits the same value automatically. New containers spun up by autoscaling pick up the license on start without any manual setup or per-container retrieval. -### Shared Databases Across Environments - -Some deployment pipelines deploy a release to a preprod environment first, then promote the same release to production — both pointed at the same database, but with different `PUBLIC_URL` values. - -Since a license binds to your project (stored in the database) and its `PUBLIC_URL` (set per environment), using a **different `LICENSE_KEY` in each environment** causes the binding to conflict: whichever environment starts second will try to rebind the shared project to its own key and URL, and the licensing service will reject it. - -Use the **same `LICENSE_KEY` value** across every environment that shares a database, varying only `PUBLIC_URL`. This is the same multi-activation model described above — each environment registers its own binding for its own URL, under one key. - -If you already hit a binding conflict: - -1. On the environment with the working license, remove `LICENSE_KEY` from the environment and restart. This unlocks the Studio license editor. -2. Go to **Settings > License** and click **Deactivate License**. This releases the binding on the licensing service, rather than just clearing it locally. -3. Stop that environment. -4. Start the other environment. With no license data left in the database, it activates fresh. - -::callout{icon="i-lucide-triangle-alert" color="warning"} -Don't clear `license_key` directly in the database to work around a binding conflict. This leaves the old activation stranded on the licensing service, still counted against your activation limit. Always deactivate through the Studio or API first. -:: +Using a different `LICENSE_KEY` per environment against a shared database causes the environments' bindings to conflict. See [Troubleshooting](#troubleshooting) below. ## Resolution Flow @@ -213,3 +196,22 @@ When an existing instance upgrades to Directus 12 without a license, behavior de - **Above core tier limits** — the instance enters a 30-day grace period during which it continues to function normally. Admins see a reminder on every login. Add a license key to clear the reminder, or reduce usage to within core limits before the grace period ends. If the grace period ends with usage still above core limits, the resolution flow is triggered on next admin login. + +## Troubleshooting + +### Binding conflicts across shared-database environments + +If environments that share a database are configured with **different** `LICENSE_KEY` values, whichever environment starts second tries to rebind the shared project to its own key and `PUBLIC_URL`. The licensing service rejects this, and that environment fails to start with a binding error. + +To recover: + +1. On the environment with the working license, remove `LICENSE_KEY` from the environment and restart. This unlocks the Studio license editor. +2. Go to **Settings > License** and click **Deactivate License**. This releases the binding on the licensing service, rather than just clearing it locally. +3. Stop that environment. +4. Start the other environment. With no license data left in the database, it activates fresh. + +::callout{icon="i-lucide-triangle-alert" color="warning"} +Don't clear `license_key` directly in the database to work around a binding conflict. This leaves the old activation stranded on the licensing service, still counted against your activation limit. Always deactivate through the Studio or API first. +:: + +Going forward, use the same `LICENSE_KEY` across all environments sharing that database — see [Activations and Project Bindings](#activations-and-project-bindings). \ No newline at end of file