# Deployment

Install CKEditor AI On-Premises on your own infrastructure. At the end you have a running container, an environment with an access key, and a token endpoint in your application that signs tokens for your users. To generate a `docker run` command for your setup, use the [Setup wizard](setup-wizard.md). To check your infrastructure first, see [Requirements](requirements.md).

<a id="infrastructure">

## Infrastructure

Prepare these services before you install CKEditor AI On-Premises:

* An SQL database (PostgreSQL or MySQL)
* An in-memory data store compatible with the Redis protocol (Valkey or Redis)
* File storage (Amazon S3, Azure Blob Storage, the local filesystem, or the SQL database)

You also need an Open Container runtime, for example Docker, Kubernetes, Amazon Elastic Container Service, or Azure Container Instances, and a valid license key from the [Customer Portal](https://portal.ckeditor.com/).

For production, run a load balancer in front of the deployment. It lets you run several instances behind one address, and it is where you terminate TLS. NGINX, HAProxy, Amazon Elastic Load Balancing, and Azure Load Balancer all work. See [SSL communication](ssl.md) for the configuration.

See [Architecture](architecture.md) for the recommended infrastructure and how the parts connect.

<a id="sql-database">

### SQL Database

The SQL database stores configurations, conversations, file metadata, and documents. It can also hold the uploaded files themselves when you set `storage_driver` to `database`.

<a id="postgresql">

#### PostgreSQL

The minimum required version of PostgreSQL is 12.0. We recommend PostgreSQL 18 or newer. The database user needs these privileges: `SELECT, INSERT, UPDATE, DELETE, REFERENCES, CREATE, USAGE`.

Create the database and the schema before you start CKEditor AI On-Premises. For example:

```sql
CREATE DATABASE "cksource";
\connect "cksource";
CREATE SCHEMA "ai-service-on-premises";
```

<a id="mysql">

#### MySQL

The minimum required version of MySQL is 8.0. We recommend MySQL 9.7 LTS or newer. The database user needs these privileges: `ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, TRIGGER, UPDATE, LOCK TABLES, REFERENCES`.

Create the database before you start CKEditor AI On-Premises. For example:

```sql
CREATE DATABASE `ai-service-on-premises`
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_bin;
```

> **Note**
>
> If binary logging is enabled without the `SUPER` privilege, make sure `log_bin_trust_function_creators` is enabled. Check this on managed database services (DBaaS) such as [AWS RDS/Aurora](https://aws.amazon.com/premiumsupport/knowledge-center/rds-mysql-functions/), Azure Database, Google Cloud SQL, or DigitalOcean Managed Databases.

To use another SQL database, such as Microsoft SQL Server, [contact us](https://ckeditor.com/contact/).

<a id="integration-with-collaboration-server-on-premises">

## Integration with Collaboration Server On-Premises

If you run [Collaboration Server On-Premises](../cs-onpremises/overview.md), CKEditor AI On-Premises can share its SQL database, Redis instance, and environments. See [Collaboration Server integration](collaboration-server-integration.md) for the configuration and the token that covers both services.

<a id="running-the-service">

## Running the service

Install CKEditor AI On-Premises from the Docker image.

> **Note**
>
> To track your progress, use the [Quickstart checklist](quickstart-checklist.md). To generate a `docker run` command for your environment, use the [Setup wizard](setup-wizard.md).

<a id="step-1-get-your-download-token">

### Step 1: Get your Download token

To pull the CKEditor AI On-Premises Docker image, you need a download token.

1. Log in to the [Customer Portal](https://portal.ckeditor.com/).

2. Open **Subscription → License keys → CKEditor AI Server**.

3. Scroll to the **Download tokens** section.

4. If no tokens exist, click **Create token**.

5. Copy and save the token.

> **Note**
>
> If CKEditor AI Server is not visible in your Customer Portal, or you cannot create a download token, [contact us](https://ckeditor.com/contact/).

<a id="step-2-pull-the-docker-image">

### Step 2: Pull the Docker image

Use the download token as the password to log into the CKEditor AI On-Premises Docker Registry, then pull the image:

```bash
echo "[DOWNLOAD_TOKEN]" | docker login -u ai-service --password-stdin https://docker.cke-cs.com
docker pull docker.cke-cs.com/ai-service:latest
```

<a id="step-3-launch-the-docker-container">

### Step 3: Launch the Docker container

Start the container with the environment variables your deployment needs. [Required configuration](configuration.md) describes every option. The [Setup wizard](setup-wizard.md) generates a command for your infrastructure, or you can adapt the example below. You can also see the [Docker Compose](examples/docker.md) and [Kubernetes with Helm](examples/kubernetes.md) examples.

```bash
docker run --init -p 8000:8000 \
	-e LICENSE_KEY=[your license key from Customer Portal] \
	-e ENVIRONMENTS_MANAGEMENT_SECRET_KEY=[your management secret key used in management panel] \
	-e DATABASE_DRIVER=[mysql|postgres] \
	-e DATABASE_HOST=[your database host] \
	-e DATABASE_USER=[your database user] \
	-e DATABASE_PASSWORD=[your database user password] \
	-e DATABASE_DATABASE=[your database name] \
	-e REDIS_HOST=[your redis host] \
	-e PROVIDERS='{"openai":{"type":"openai","apiKeys":["your-api-key"]}}' \
	-e STORAGE_DRIVER=[s3|azure|filesystem|database] \
	-e STORAGE_ACCESS_KEY_ID=[your AWS access key] \
	-e STORAGE_SECRET_ACCESS_KEY=[your AWS secret key] \
	-e STORAGE_BUCKET=[your S3 bucket name] \
	docker.cke-cs.com/ai-service:[version]
```

<a id="step-4-create-an-environment-and-access-key">

### Step 4: Create an Environment and Access Key

1. Open the Management Panel in your browser. The panel runs at the address of the deployment, for example `http://localhost:8000/panel`.

2. Enter the `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` you provided to the container.

3. Create a new **Environment**.

4. Inside the environment, create a new **Access Key**.

5. Save the `Environment ID` and the `Access Key`. You need them for the token endpoint.

See [Access key](../../developer-resources/security/access-key.md) for more on managing environments and access keys.

<a id="step-5-create-the-token-endpoint">

### Step 5: Create the token endpoint

Use the `Environment ID` and `Access Key` from the previous step to create a [token endpoint](../../developer-resources/security/token-endpoint.md) in your application. The endpoint signs the JWTs that authorize your users.

Include `auth.ai.permissions` in the token to grant access to AI features. For a working implementation, see the [CKEditor AI](../../examples/token-endpoints/nodejs.md#ckeditor-ai) section of the Node.js token endpoint example. The same endpoint is also available in [PHP](../../examples/token-endpoints/php.md), [Python](../../examples/token-endpoints/python.md), [Java](../../examples/token-endpoints/java.md), and [ASP.NET](../../examples/token-endpoints/dotnet.md).

See [Permissions](../../guides/ckeditor-ai/permissions.md) for what each AI permission grants.

<a id="step-6-configure-ckeditor-5-to-use-your-ckeditor-ai-on-premises-instance">

### Step 6: Configure CKEditor 5 to use your CKEditor AI On-Premises instance

The quickest way to get an editor that works with your deployment is the [CKEditor 5 Builder](https://builder.ckeditor.com/#presets/NoRg7ANARAzAdAFjgJitAbADgAwIKwKYwJjKExYCc6ZIyeMy6ImhC6622eIn9emPJUzJkXNFACmAOzTYIoCCAjzlagLrRMAMwDGkhCBhR1QA). It builds an editor with the CKEditor AI features enabled. Download the generated project, then configure the editor to point it at your deployment.

To connect to your CKEditor AI On-Premises deployment, set the following options in the editor configuration:

* `ai.serviceUrl` – the address of your deployment, followed by `/v1`, for example `https://ai.example.com/v1`.
* `collaboration.channelId` – a unique ID that identifies the data loaded in the editor instance or used by the context instance.
* `cloudServices.tokenUrl` – the token endpoint from Step 5. The editor uses it to get the JWT it sends with each request.

```js
ClassicEditor
	.create( document.querySelector( '#editor' ), {
		licenseKey: '<YOUR_EDITOR_LICENSE_KEY>',
		cloudServices: {
			tokenUrl: '<YOUR_TOKEN_ENDPOINT>'
		},
		collaboration: {
			channelId: 'my-document-1'
		},
		ai: {
			serviceUrl: '<YOUR_DEPLOYMENT_ADDRESS>'
		}
		} )
		.then( /* ... */ )
		.catch( /* ... */ );
```

The models available in the editor are the ones you configured in [LLM providers](llm-providers.md). For all editor-side options, see the [AIConfig](../../../../ckeditor5/latest/api/module_ai_aiconfig-AIConfig.md) API reference and the [CKEditor AI guides](../../guides/ckeditor-ai/overview.md). The full description of the editor integration is in [Integrating CKEditor AI with your application](../../../../ckeditor5/latest/features/ai/ckeditor-ai-integration.md).

<a id="next-steps">

## Next steps

* [Quickstart checklist](quickstart-checklist.md) – Run the smoke test against your deployment.
* [Docker Compose](examples/docker.md) and [Kubernetes with Helm](examples/kubernetes.md) – Run the service from a ready-made example.
* [Collaboration Server integration](collaboration-server-integration.md) – Share one data layer and one token with Collaboration Server On-Premises.
* [SSL communication](ssl.md) – Terminate TLS in front of the deployment.
* [Observability](observability.md) – Export traces to an OTLP backend, to Langfuse, or to both.
* [Logs](logs.md) – Collect the container output and ship it to a distributed logging system.

---

Full index of the Cloud Services documentation: [llms.txt](../../../llms.txt)