# Complete Deployment Steps for Karakeep: Kubernetes Self-Hosting Guide

> Deploy Karakeep effortlessly with our Kubernetes self-hosting guide. Follow simple steps to configure environment variables, build manifests, and deploy to your cluster.

- Repository: [Karakeep App/karakeep](https://github.com/karakeep-app/karakeep)
- Tags: how-to-guide
- Published: 2026-07-07

---

**Deploy Karakeep by configuring environment variables from `.env.example`, building a Kubernetes manifest with `make build`, and applying it to your cluster with `make deploy`.**

Karakeep is a self-hosted bookmarking platform built as a microservices architecture. According to the karakeep-app/karakeep repository, production deployment uses a Kustomize-based workflow that automates the creation of all required services, databases, and background workers.

## Prerequisites

Before beginning the deployment steps for Karakeep, ensure your system has:
- A running Kubernetes cluster with `kubectl` configured
- `kustomize` installed locally for manifest generation
- The `make` utility to use the provided build automation
- Access to the repository's `kubernetes/` directory

## Step-by-Step Karakeep Deployment Process

The repository provides a streamlined three-phase deployment process orchestrated through the `kubernetes/Makefile`.

### 1. Configure Environment Variables

Copy the example environment file and populate it with your production values:

```bash
cp .env.example .env

# Edit .env with your preferred editor

```

According to the [`kubernetes/README.md`](https://github.com/karakeep-app/karakeep/blob/main/kubernetes/README.md), you must configure:
- **DATABASE_URL**: PostgreSQL connection string (e.g., `postgresql://karakeep:password@db:5432/karakeep`)
- **NEXTAUTH_SECRET**: Random secret for authentication
- **NEXTAUTH_URL**: Your domain (e.g., `https://your-domain.example`)
- **MEILISEARCH_HOST**: Meilisearch endpoint (e.g., `http://meilisearch:7700`)
- **MEILISEARCH_MASTER_KEY**: Search index master key
- **OPENAI_API_KEY**: Optional LLM integration key

### 2. Build the Kubernetes Manifest

Generate the complete manifest file from the `kubernetes` directory:

```bash
cd kubernetes
make build

```

This command executes `kustomize build . > _manifest.yaml`, assembling Deployments for the API (`packages/api`), web UI (`apps/web`), background workers (`apps/workers`), and Model Context Protocol server (`apps/mcp`), plus StatefulSets for PostgreSQL and Meilisearch.

### 3. Deploy to the Cluster

Apply the generated manifest to your cluster:

```bash
make deploy

```

This runs `kubectl apply -f _manifest.yaml`, creating Services, Ingress rules (if enabled), and PersistentVolumeClaims alongside the application workloads. To remove the temporary [`_manifest.yaml`](https://github.com/karakeep-app/karakeep/blob/main/_manifest.yaml) file after deployment, run `make clean`.

## Verify the Deployment

Check that all resources are running correctly:

```bash
kubectl get pods    # Verify all pods are Running/Ready

kubectl get svc     # Check service endpoints

kubectl get ingress # Confirm external routing (if configured)

```

## Alternative: Docker Compose for Local Development

For non-production local testing, the repository includes a [`docker-compose.yml`](https://github.com/karakeep-app/karakeep/blob/main/docker-compose.yml) in the root directory. Run:

```bash
docker compose up -d

```

This method is intended for development only and lacks the scaling, high availability, and rolling update capabilities of the Kubernetes deployment steps described above.

## Summary

- **Karakeep deployment** uses a Kustomize-based workflow defined in the `kubernetes/` directory
- The `kubernetes/Makefile` automates manifest generation (`make build`) and cluster application (`make deploy`)
- Required configuration includes database credentials, authentication secrets, and optional AI service keys in `.env`
- The deployment creates microservices for the API, web frontend, workers, and search indexing, plus persistent storage for data
- For production use, always use the Kubernetes method; reserve [`docker-compose.yml`](https://github.com/karakeep-app/karakeep/blob/main/docker-compose.yml) for local development only

## Frequently Asked Questions

### What is the recommended deployment method for production Karakeep instances?

The Kubernetes/Kustomize workflow is the recommended approach for production. As implemented in karakeep-app/karakeep, this method handles scaling, rolling updates, and persistent storage through standard Kubernetes resources, unlike the Docker Compose alternative which is restricted to single-host development environments.

### Where are the deployment configuration files located in the Karakeep repository?

All Kubernetes deployment files reside in the `kubernetes/` directory. The `kubernetes/Makefile` contains the build and deployment logic, while [`kubernetes/kustomization.yaml`](https://github.com/karakeep-app/karakeep/blob/main/kubernetes/kustomization.yaml) defines the resource assembly. The root-level `.env.example` provides the template for environment-specific configuration values.

### Can I deploy Karakeep without Kubernetes?

While Kubernetes is the primary production deployment target, you can run Karakeep locally using the [`docker-compose.yml`](https://github.com/karakeep-app/karakeep/blob/main/docker-compose.yml) file in the repository root. However, this lacks high availability features and automatic scaling, making it suitable only for development or single-user personal instances.

### What environment variables are required to complete the Karakeep deployment?

At minimum, you must set `DATABASE_URL` for PostgreSQL connectivity, `NEXTAUTH_SECRET` for session security, and `NEXTAUTH_URL` for callback URLs. If using the built-in search functionality, `MEILISEARCH_HOST` and `MEILISEARCH_MASTER_KEY` are also required. Optional integrations like OpenAI require their respective API keys.