diff --git a/content/configuration/1.general.md b/content/configuration/1.general.md index 76afb2be..fafae083 100644 --- a/content/configuration/1.general.md +++ b/content/configuration/1.general.md @@ -24,6 +24,11 @@ description: Configuration for the general system, server, first admin user, and | `TEMP_PATH` | Where Directus' temporary files should be managed. | `./node_modules/.directus` | | `PROJECT_OWNER` | Registered owner and primary contact responsible for your Directus instance. | | + +::callout{icon="material-symbols:warning-rounded" color="warning"} +`PUBLIC_URL` must be a qualified URL when using [licensing](/licensing/overview) features beyond Core Plan and/or when configuring [SSO](/configuration/auth-sso) +:: + ## License See [Licensing](/licensing/overview) for a full explanation of license keys, license tokens and source precedence. diff --git a/content/licensing/1.overview.md b/content/licensing/1.overview.md index eae426dd..324cefea 100644 --- a/content/licensing/1.overview.md +++ b/content/licensing/1.overview.md @@ -16,9 +16,28 @@ Quick links: - [Enquire about a commercial license](https://directus.io/contact) - [Upgrading to Directus 12 (existing customer)](#upgrading-to-directus-12) +## `PUBLIC_URL` and Licensing + +Before applying a license, `PUBLIC_URL` must be set to a valid absolute URL (e.g. `https://directus.example.com`). The default value (`/`) and any relative path are rejected by the licensing service during [activation](#activations-and-project-bindings). + +If `PUBLIC_URL` is not set, Directus will still start successfully with a warning logged to the console. + +Attempts to add a license key during setup will grant access to the Studio, but license activation will fail and an error will be logged. Likewise, adding or managing a license through **Settings → License** will fail and display the following error: + + +``` +[INVALID_PAYLOAD] Invalid payload. public_url must be a valid absolute URL. +``` + +If you encounter this error, configure `PUBLIC_URL` with a qualified URL, restart Directus, and then re-apply the license. + +::callout{icon="material-symbols:info-outline" color="info"} +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). +:: + ## License Keys and License Tokens -There are two ways to obtain a license: +There are two ways to configure a license: - **License key** — a string in the format `DXXXX-XXXXX-XXXXX-XXXXX-XXXXC`. On first use, it binds your license to a specific project and `PUBLIC_URL`. License keys can be set via environment variable or added through the Studio. - **License token** — a pre-issued token containing your entitlements, validated locally without contacting the licensing service. Tokens are only set via environment variable and are intended for **offline use**, in environments without outbound network access. Any change to the license requires a new token to be issued and deployed. @@ -88,19 +107,19 @@ 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. +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). ### Deactivating a License Deactivating a license frees its activation on the licensing service so the binding can be reused. - **Studio-managed license** — open **Settings > License** in the Studio and click **Deactivate License**. The instance drops to the core tier immediately. -- **Env-managed license** — remove the `LICENSE_KEY` (or `LICENSE_TOKEN`) value from your environment and restart Directus. The Studio license editor becomes available, but the previous plan and entitlements remain displayed until you click **Deactivate License**. +- **Env-managed license** — remove the `LICENSE_KEY` (or `LICENSE_TOKEN`) value from your environment and restart Directus. The Studio license editor becomes available, but the previous plan and entitlements remain displayed until you click **Deactivate License**. Removing the env var alone does not free the activation on the licensing service — the deactivate action does. If your current usage is above core tier limits when you deactivate, the Studio will surface the [Resolution Flow](#resolution-flow) before completing the downgrade. ::callout{icon="material-symbols:warning-rounded" color="warning"} -**Removing the env var alone does not deactivate the activation on the licensing service** — the deactivate action does. If you skip the deactivate step, the activation remains bound to this instance and continues to count against your license's activation limit. +**Always deactivate a license before destroying the instance it is bound to.** If you wipe the database, drop the container, or otherwise lose access to the Studio without deactivating first, the activation remains bound on the licensing service and continues to count against your license's activation limit. There is currently no self-service way to release a stranded activation — reach out to support if this happens. This is especially important when testing a license key in a throwaway environment. :: ### Moving an Instance to a New URL