Activating a license

Every installation starts as Community and needs no license. A Business or Enterprise subscription comes with a license key; activating it binds this installation to your subscription and unlocks the paid edition on the same image. Nothing is reinstalled or restarted.

This page covers connected licenses. Enterprise Advanced Security uses an organization-wide offline license file instead; see Air-gapped sites.

Before you begin

You need:

The license key. Sign in to Account and use Collect license key the first time, or View license key afterwards. A key looks like marolum- followed by 26 uppercase letters and digits, a dash, and 64 lowercase hexadecimal characters. Treat it as a secret: anyone with it can attempt activation.
An administrator account on the installation. Other roles see Administrator permission required on the Licensing page, and the API refuses them.
Outbound HTTPS from the container to https://licensing.dekglas.com. Activation and every later renewal call it. See the network requirements.
Durable storage for the license state.
- With SQLite, the license state lives in a licensing directory beside the database (by default /data/licensing), so it is in the same volume and the same backups.
- With PostgreSQL, the license state lives in the database and every replica shares it. Releases through 0.21.1 also need MAROLUM_CONNECTED_LICENSE_DIR; see Known limitations.
- An in-memory database has nowhere to keep a license, so activation is unavailable there.

Step 1: Check the installation is ready

Open the account menu (your name, bottom left), choose Administration, then Licensing under Access & licensing. The page has two cards that matter here:

Edition shows Marolum Community with No license required.
Activation shows Inactive and the Installation ID, a 32-character identifier that Dekglas uses to tell your installations apart. It is not a secret. Copy installation ID copies it if support asks for it.

If Activation shows something other than Inactive:

Badge	Meaning	What to do
Active	A license is already active here	Nothing. To change keys, see Replacing a key
Grace	A license is active but renewal has not succeeded recently	Restore outbound HTTPS to the licensing service; see Renewal and expiry
Offline license	`MAROLUM_OFFLINE_SITE_LICENSE_FILE` is set	The offline license takes precedence; connected activation is not used
Unavailable	The installation has no durable place for license state	Move to a durable SQLite volume or PostgreSQL first

You can read the same state from the API. Sign in once with an administrator account; the cookie jar keeps the session:

MAROLUM_URL=https://marolum.example.com

read -rsp 'Administrator password: ' MAROLUM_PASSWORD && echo
jq -n --arg password "$MAROLUM_PASSWORD" '{username: "admin", password: $password}' |
  curl -fsS -c marolum-session.txt -X POST "$MAROLUM_URL/api/v1/auth/login" \
    -H 'Content-Type: application/json' --data @- >/dev/null
unset MAROLUM_PASSWORD

curl -fsS -b marolum-session.txt "$MAROLUM_URL/api/v1/licensing/activation"
rm -f marolum-session.txt

Before activation the response is {"state":"inactive","installationId":"…"}. The other states are active, grace, offline-configured and unconfigured, matching the badges above.

Step 2: Activate the key

Paste the key into License key. Paste it exactly as Account shows it; do not change its case. Activate stays disabled until the field holds something shaped like a key.
Select Activate. Marolum sends the key and the installation ID to the licensing service and waits for a signed lease, for up to 30 seconds.

Marolum keeps the key only if the service returns a lease it can verify. If anything goes wrong, nothing is stored and the installation stays exactly as it was. Once stored, the key is never displayed in Marolum again; Account remains the place to view it.

Step 3: Confirm the edition

After a successful activation:

Activation shows Active.
Edition shows Marolum Business or Marolum Enterprise with License active, and Enabled features and Effective limits list what the edition unlocked.
The readiness endpoint reports the edition, which is handy for monitoring:

curl -fsS https://marolum.example.com/api/v1/readiness

It returns "edition":"business" or "edition":"enterprise" in place of "community".

If activation does not complete

The console shows Activation request did not complete with one of these messages:

Message begins	Cause	What to do
That is not a Marolum license key	The text is not a valid key. In 0.21.1 this includes a real key whose letters were made lowercase	Copy the key again from Account without editing it
The licensing service refused the key or could not be reached	The service rejected the key, or the container cannot reach `https://licensing.dekglas.com`	Check the key, then check outbound HTTPS from the container (proxy, firewall, DNS). Nothing was stored, so retrying is safe
This installation cannot use the license allowance	Every installation slot on your subscription is in use, or this installation ID was deactivated	In Account, deactivate an installation you have stopped, or add capacity. If this ID was deactivated by mistake, contact support
This installation carries an offline site license	`MAROLUM_OFFLINE_SITE_LICENSE_FILE` is set	Remove the setting if you meant to use a connected license
Connected activation is not configured	The installation has no durable place for license state	See Unavailable in Step 1
The request did not complete	The request itself failed, for example a proxy timeout in front of Marolum	Retry. If it persists, check the reverse proxy allows at least 30 seconds

Renewal and expiry

You do not renew by hand. Each lease is valid for 7 days, and Marolum renews it automatically about halfway through, retrying with growing intervals if the service cannot be reached.

If renewal keeps failing, the license enters a grace period: 14 days for Business and 60 days for Enterprise after the lease ends, so 21 or 67 days from the last successful renewal. During grace the Licensing page shows Grace and administrators see a banner. When grace ends the installation runs as Community until a renewal succeeds. Nothing is deleted and no effective policy changes; paid-only acts such as placing a new legal hold stop. See Edition downgrade. Readiness does not depend on renewal, so a lapsed license never makes the installation unready.

Replacing a key

Activate is available only while the installation is inactive. To switch to a different key, for example after Account replaced an older key:

Select Deactivate on the Licensing page. This removes the stored key from this installation. It does not release the installation's slot on your subscription, and the current lease stays valid until it expires.
Paste the new key and select Activate.

To retire an installation and free its slot, follow Release the license.

Backups and moves

The license state travels with the database. On SQLite, back up and restore the licensing directory with marolum.db; restoring it keeps the same installation ID, so the installation keeps its slot. A rebuilt installation without it gets a new installation ID and counts as a new installation. The directory holds the key, so protect backups accordingly. See Backup and recovery.