---
source: https://carbone.io/documentation/developer/on-premise-installation/licensing.html
title: "How to license Carbone On-Premise"
description: "Get a Carbone license and activate the Enterprise Edition on your servers"
generated_at: "2026-08-28"
---

# Licensing

Get a Carbone license and activate the Enterprise Edition on your servers

## Community and Enterprise Edition

Carbone On-Premise always starts, with or without a license. Without one it runs the **Community Edition**: document generation works, but Enterprise features are disabled.

A license unlocks the Enterprise Edition and comes with support and updates.

See the [feature-by-feature comparison](/pricing.md#compare-plans-on-premise) to know exactly what each edition includes.

## Get a license

To request a **free 30-day trial**:

1.  Create an account on [account.carbone.io](https://account.carbone.io).
2.  [Ask us in the chat](#) and we activate it immediately.
3.  Download your license from your [dashboard](https://account.carbone.io/).

For a production license or any question on plans, [talk to us](https://carboneio.pipedrive.com/scheduler/5Rzzbxu6/carbone-on-premiseaws-presentation).

## How to provide the license

The license is a `*.carbone-license` file holding one signed token. You can either **pass its content as a string** or **drop that file on disk**. Both carry the same license, so pick whichever suits your deployment.

### Option 1: pass the license as a string

Use this when the filesystem is read-only or ephemeral, or when secrets are injected by the platform. Set the [license](/documentation/developer/on-premise-installation/configuration.md#license) parameter to the _content_ of the `.carbone-license` file:

```bash
export CARBONE_LICENSE="eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhY..."

./carbone webserver
```

With Docker, export the variable on the host and forward it with `-e CARBONE_LICENSE`, so the token stays out of the command line and out of the image:

```bash
export CARBONE_LICENSE="eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhY..."

docker run -t -i --rm -p 4000:4000 -e CARBONE_LICENSE carbone/carbone-ee:full-5.14.3
```

Never bake the token into an image or commit it to a repository. Each platform has its own secret store, and the deployment guides show how to wire it:

-   [Deploy with Docker](/documentation/developer/self-hosted-deployment/deploy-with-docker.md): Docker secret mounted as a `.carbone-license` file
-   [Deploy on Kubernetes](/documentation/developer/self-hosted-deployment/deploy-on-kubernetes.md): the Helm chart stores it in a `Secret` and injects it as an environment variable
-   [Deploy on AWS ECS](/documentation/developer/self-hosted-deployment/deploy-on-aws-ecs.md): AWS Secrets Manager referenced from the task definition

### Option 2: put the file on disk

Copy the file into the [license directory](/documentation/developer/on-premise-installation/configuration.md#license-directory), which is the `config` folder of the [workspace directory](/documentation/developer/on-premise-installation/configuration.md#workspace-directory) by default. Only the `.carbone-license` extension matters, the filename is free:

```text
/var/www/carbone/
└── config/
    ├── config.json
    └── acme-corp.carbone-license
```

The Docker image uses `/app` as workspace directory, so mount your folder into `/app/config`:

```bash
docker run -t -i --rm -p 4000:4000 --volume ./config:/app/config carbone/carbone-ee:full-5.14.3
```

To keep licenses somewhere else, point [licenseDir](/documentation/developer/on-premise-installation/configuration.md#license-directory) to that directory:

```bash
export CARBONE_LICENSE_DIR=/etc/carbone/licenses
```

## Which license is selected

1.  If the `license` string is set, Carbone uses it and **never reads the license directory**. As with any parameter, the CLI option wins over the environment variable, which wins over `config.json`.
2.  Otherwise Carbone lists the license directory, keeps the files ending with `.carbone-license`, and loads **the most recently created one**. Sub-directories and any other file are ignored.

To renew a license, just drop the new file next to the old one: being the newest on disk, it is picked up at the next restart.

> ⚠️ **Warning:** The selection uses the **file creation date**, not the filename nor the modification date. Copying an older license into the directory gives it a fresh creation date and makes it win. When in doubt, delete the obsolete files.

## Check the loaded license

Carbone prints the license it loaded on startup:

```text
LICENSE:
--------
- name       : ACME Corp
- expired at : 2027-01-31T00:00:00.000Z
- address    : 1 rue de la Paix, Paris
- email      : admin@acme.corp
- plan       : enterprise
```

When no valid license is found, Carbone still starts, in Community Edition: Enterprise features are disabled, the [job balancer](/documentation/developer/on-premise-installation/ha-and-scaling.md#job-balancer) is forced off, and the reason is printed instead:

```text
LICENSE:
--------
❌ No *.carbone-license files found in /app/config
❌ No license found in env. variable CARBONE_EE_LICENSE or CARBONE_LICENSE
⚠️ Only features of the Community Edition are enabled
```

> ℹ️ **Note:** An expired license does not always stop the Enterprise Edition: with the `eternity` plan, versions published before the expiration date keep running, only support and updates stop. A `Invalid license. Check system clock.` message means the machine clock is set earlier than the publication date of your Carbone version.

## Related topics

- [Upgrade Guide](/documentation/developer/on-premise-installation/upgrade-guide.md)
- [Template management](/documentation/developer/on-premise-installation/template-management.md)
- [On-Premise Requirements](/documentation/developer/on-premise-installation/requirements.md)
- [On-Premise plugins](/documentation/developer/on-premise-installation/plugins.md)
- [Metrics (OpenMetrics)](/documentation/developer/on-premise-installation/metrics.md)
- [On-Premise](/documentation/developer/on-premise-installation/introduction.md)