Complete Deployment Steps for Karakeep: Kubernetes Self-Hosting Guide

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:

cp .env.example .env

# Edit .env with your preferred editor

According to the 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:

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:

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 file after deployment, run make clean.

Verify the Deployment

Check that all resources are running correctly:

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 in the root directory. Run:

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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}