> For the complete documentation index, see [llms.txt](https://docs.lenses.io/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lenses.io/latest/k2k/deployment/docker.md).

# Docker

Run K2K in Docker containers.

Deploy K2K using the official container image. For Kubernetes deployments, use the [Helm chart](/latest/k2k/deployment/helm.md) instead.

## Prerequisites

* Docker installed on the host
* At least 1 GB memory per K2K process (2 GB recommended for high-throughput pipelines)
* Network access to source and target Kafka clusters
* A pipeline YAML file — see [Minimal Configuration](/latest/k2k/minimal-configuration.md)

Pin the image version to match your Helm chart or release — see [Releases and compatibility](/latest/k2k/deployment/releases-and-compatibility.md).

## Configure the pipeline

Create a pipeline YAML file (for example `pipeline.yaml`) that defines source and target cluster connections, replication rules, and feature toggles. See [Minimal Configuration](/latest/k2k/minimal-configuration.md) for structure and examples.

Keep secrets in a separate overlay file mounted alongside the base pipeline:

```shell
k2k start -f /pipelines/base_pipeline.yml -f /pipelines/secrets_overrides.yml
```

## Run the replicator

Mount the directory containing your pipeline files and start the replicator:

```bash
docker run --rm -d \
  -v "$(pwd):/pipelines" \
  -e OTEL_SERVICE_NAME="k2k" \
  -e OTEL_METRICS_EXPORTER=otlp \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317" \
  --name k2k-replicator \
  lensesio/k2k:2.1.0 \
  k2k start -f /pipelines/pipeline.yaml -t
```

Replace `2.1.0` with your target version. See [Deployment](/latest/k2k/deployment.md) for CLI options and [Observability](/latest/k2k/configuration-reference/observability.md) for metrics configuration.

{% hint style="info" %}
OTEL traces and logs are not supported. Use the metrics exporter for observability.
{% endhint %}

## Run the offset mapper

When [offset mapping](/latest/k2k/configuration-reference/offset-mapping.md) is enabled, run a second container with the same pipeline files:

```bash
docker run --rm -d \
  -v "$(pwd):/pipelines" \
  --name k2k-offset-mapper \
  lensesio/k2k:2.1.0 \
  k2k-offset-mapping start -f /pipelines/pipeline.yaml
```

{% hint style="warning" %}
When `features.offsetMapping` is `enabled`, deploy and run both `k2k` and `k2k-offset-mapping`. Enabling the feature in the pipeline file does not translate consumer offsets by itself.
{% endhint %}

See [Deployment](/latest/k2k/deployment.md#offset-mapping-both-applications-required) for when both applications are required.

## Validate before production

Test routing and schema handling without writing to the target cluster:

```bash
docker run --rm -it \
  -v "$(pwd):/pipelines" \
  lensesio/k2k:2.1.0 \
  k2k dry-run -f /pipelines/pipeline.yaml
```

See the [Validation checklist](/latest/k2k/runbooks/validation-checklist.md) for a full pre-deployment workflow.

## Resource guidance

| Workload             | Memory (per instance) | Notes                                                                                                                                       |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Replicator (default) | 1–2 GB                | Increase for high partition counts or large messages                                                                                        |
| Offset mapper        | 512 MB–1 GB           | Scales with number of consumer groups translated                                                                                            |
| High throughput      | 2–4 GB                | Tune producer `buffer.memory` — see [Replication performance tuning](/latest/k2k/configuration-reference/replication-performance-tuning.md) |

Run multiple replicator containers with the same pipeline to scale horizontally — see [Horizontal scaling](/latest/k2k/configuration-reference/horizontal-scaling.md).

## Deployment placement

Deploy containers close to the **target** Kafka cluster to minimize producer latency. See [Deployment](/latest/k2k/deployment.md#deployment-recommendation).

## Using k2k-tool

The `k2k-tool` administration CLI and web UI are included in the same image:

```bash
docker run --rm -it \
  -v "$(pwd):/pipelines" \
  -p 8080:8080 \
  lensesio/k2k:2.1.0 \
  k2k-tool server -f /pipelines/pipeline.yaml -p 8080
```

See [K2K Standalone Tool](/latest/k2k/k2k-standalone-tool.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lenses.io/latest/k2k/deployment/docker.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.