---
title: "Quick start"
---
Choose a provider, install the control plane, then create a cluster and back it up. See [Providers](/docs/providers/) for capability differences and [Operating costs](/docs/operating-costs/) for costs.

| Provider | Quick-start path |
| --- | --- |
| Zerops — reference provider | Follow the dashboard-only steps below; no checkout or CLI required. |
| Dokploy | Follow [Install the control plane on Dokploy](/docs/dokploy/#install-the-control-plane-on-dokploy), then use the engine guides linked below. |
| Nomad | Follow [Install the control plane on Nomad](/docs/nomad/#install-the-control-plane-on-nomad), then use the engine guides linked below. |

The steps below use the **[Zerops](https://zerops.io/) provider**. You need a Zerops account and existing project. LIGHT hosts the control plane; clusters need **additional capacity**. Check engine sizing below and the wizard's total against project capacity. Other Zerops deployment paths: [Install](/docs/getting-started/install/).

## 1. Create a Zerops token

Open **Settings → Access Tokens Management**. Choose **Custom access per project → Full access** for this project only, with **sudo mode off**. Save the one-time token securely; see [Security](/docs/security/) for the privilege boundary.

## 2. Import Karakoram

Choose **Import services** in the project. Copy this template, then replace the empty `KARAKORAM_ZEROPS_TOKEN` with your token before importing:

```yaml
#yamlPreprocessor=on
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 The Karakoram Authors
# Set buildFromGit to your fork's public URL when deploying a fork, and set
# zeropsSetup to karakoram-source: the default setup deploys the upstream release.
# To deploy a local checkout, use import-local.yaml and install.sh.
services:
  - hostname: karakoramdata
    type: local-storage:single@1
    verticalAutoscaling:
      minDisk: 5
      maxDisk: 5
  - hostname: karakoram
    type: ubuntu@24.04
    minContainers: 1
    maxContainers: 1
    enableSubdomainAccess: true
    buildFromGit: https://github.com/KarakoramDev/Karakoram
    zeropsSetup: karakoram
    envSecrets:
      KARAKORAM_MASTER_KEY: <@generateRandomString(<48>)>
      KARAKORAM_ADMIN_PASSWORD: <@generateRandomString(<24>)>
      # Replace before import, or set in the service GUI and restart after import.
      # Zerops reserves ZEROPS_* for system variables.
      KARAKORAM_ZEROPS_TOKEN: ""
    verticalAutoscaling:
      cpuMode: SHARED
      minCpu: 1
      maxCpu: 1
      minRam: 0.5
      maxRam: 1
      minDisk: 1
      maxDisk: 2
```

This is [`deploy/zerops/import.yaml`](https://github.com/KarakoramDev/Karakoram/blob/main/deploy/zerops/import.yaml). Default `karakoram` downloads/verifies the signed release pinned on `main` (seconds); `zeropsSetup: karakoram-source` builds the exact commit (minutes). Wait for **Active**. Delete token-bearing YAML; preserve the generated master key separately.

## 3. Sign in

1. Open **karakoram → Public access** and its HTTPS subdomain.
2. Read `KARAKORAM_ADMIN_PASSWORD` under **Environment variables → Secret variables**.
3. Sign in as `admin`, set a different password of at least 12 characters, then sign in again.

## 4. Add storage

**Storage is required before any backup.** Create an [S3](https://aws.amazon.com/s3/) bucket, for example using Zerops Object Storage. Open **Settings → Backup storages**, then **Create**:

| Field | Value |
| --- | --- |
| Name | e.g. `backups`; 2–63 lowercase letters, digits or hyphens |
| Endpoint URL | Object Storage endpoint shown in Zerops |
| Region | `us-east-1` for Zerops storage |
| Bucket | Your bucket name |
| Access key ID / Secret access key | Object Storage access details |

Keep other defaults. Choose **Verify** and confirm read/write/delete access. See [Backups and storage](/docs/backups/) for other endpoints and retention rules.

## 5. Create a cluster

Choose **New cluster**, select the engine and name, then:

| Engine | Wizard choices for a first cluster | Next page |
| --- | --- | --- |
| MongoDB | **Percona Server for MongoDB → replica set**; 1 member only for disposable tests, or 3 voters for quorum-based failover when placement permits. Host separation is [not guaranteed](/docs/limitations/#zerops-failure-domains-and-storage). | [Create and size](/docs/mongodb/#create) |
| RabbitMQ | **RabbitMQ**; 1 broker for disposable tests or 3 brokers. | [Create and configure](/docs/rabbitmq/#create-and-configure) |
| Elasticsearch | **Elasticsearch → Combined master and data nodes**; `dev` preset for disposable tests or `prod` for three combined nodes. | [Create and size](/docs/elasticsearch/#create) |

Review member sizing and total project capacity. Select backup storage; keep the advertised version, TLS required and public access off. Review and create; wait for **Ready**.

## 6. Take a backup

Open **Cluster → Backups → Backup now**. This is asynchronous: follow the operation and wait until backup inventory reports **Succeeded**. If storage was skipped, add it before retrying.

- [MongoDB](/docs/mongodb/backups/): [Percona Backup for MongoDB](https://docs.percona.com/percona-backup-mongodb/latest/) (PBM) logical or physical backup.
- [RabbitMQ](/docs/rabbitmq/backups/): definitions only—no messages or point-in-time recovery (PITR).
- [Elasticsearch](/docs/elasticsearch/snapshots/): native snapshot.

## 7. Connect an application

Use the private network from an application service in the same project. **Revealed credentials are the engine's administrative identity, not application credentials.** Create a scoped application identity and deliver its credentials, endpoints and CA through runtime secrets/configuration:

- [MongoDB users, roles and TLS](/docs/mongodb/access-and-tls/)
- [RabbitMQ access and TLS](/docs/rabbitmq/access-and-tls/)
- [Elasticsearch access and security](/docs/elasticsearch/access-and-security/)

## 8. Connect an AI agent

The control plane serves a read-only [MCP server](/docs/mcp/) at `/mcp` out of the box. Mint a restricted token with `karactl mcp config --client claude-code|cursor|vscode|codex` and paste the printed configuration into your client; the [MCP quick start](/docs/mcp-quickstart/) covers each client, write access and per-cluster [data MCP](/docs/data-mcp/).

## What next

- [CLI](/docs/cli/), [cluster operations](/docs/clusters/) and [Backups and storage](/docs/backups/).
- [Upgrade](/docs/getting-started/upgrade/) existing installations; never re-import the installer.
- [Limitations](/docs/limitations/) before production; [Operations](/docs/operations/) for troubleshooting.