Self-Hosted Apps

Deploy Karakeep on a VPS

A self-hosted bookmark manager with full-page archival, AI tagging, RSS feeds, and Meilisearch-powered full-text search.

What Is Karakeep?

Karakeep (formerly Hoarder) is a self-hosted bookmark manager built for people who save everything. It goes beyond storing URLs — you can archive full web pages, save notes and images, subscribe to RSS feeds, and let AI automatically tag and summarize everything you collect. A built-in Meilisearch instance powers fast full-text search across your entire library, and browser extensions plus mobile apps make adding content frictionless from anywhere.

System Requirements

Karakeep runs three containers: the main web app, a headless Chrome instance for page archival and screenshots, and Meilisearch for search indexing. The 2 GB plan gives comfortable headroom for all three services plus nginx.

• RamNode VPS running Ubuntu 22.04 or 24.04 (1 vCPU / 1 GB minimum; 2 GB recommended)
• A domain name with an A record pointing to your VPS IP
• Root or sudo access

Update the System and Install Docker

Update & install Docker

apt update && apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh

# Verify
docker --version
docker compose version

Create the Karakeep Directory

Create directory

mkdir -p /opt/karakeep
cd /opt/karakeep

Download the Docker Compose File

Download compose file

wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml

This file defines three services — web, chrome, and meilisearch — with persistent volumes and internal networking already configured.

Configure Environment Variables

Generate two secure random strings:

Generate secrets

openssl rand -base64 36
openssl rand -base64 36

Create the .env file:

/opt/karakeep/.env

KARAKEEP_VERSION=release
NEXTAUTH_SECRET=your_first_random_string_here
MEILI_MASTER_KEY=your_second_random_string_here
NEXTAUTH_URL=https://karakeep.yourdomain.com

Why two secrets? NEXTAUTH_SECRET signs session tokens for the web app. MEILI_MASTER_KEY authenticates the backend against Meilisearch. They should be different strings.

Start Karakeep

Start containers

cd /opt/karakeep
docker compose up -d

Verify all three containers are running:

Check status

docker compose ps

You should see web, chrome, and meilisearch all in the Up state. Karakeep is now running on port 3000, accessible only locally.

Install nginx and Certbot

Install

apt install -y nginx certbot python3-certbot-nginx

Configure nginx as a Reverse Proxy

/etc/nginx/sites-available/karakeep

server {
    listen 80;
    server_name karakeep.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        client_max_body_size 50M;
    }
}

The Upgrade and Connection headers support WebSocket real-time UI updates. The timeouts accommodate large file uploads and slow page archival.

Enable site

ln -s /etc/nginx/sites-available/karakeep /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Issue a TLS Certificate

Certbot

certbot --nginx -d karakeep.yourdomain.com

Verify the renewal timer is active:

Check renewal

systemctl status certbot.timer

Create Your First User

Navigate to https://karakeep.yourdomain.com and click Sign Up. After creating your account, disable open registration by adding to /opt/karakeep/.env:

Disable registration

DISABLE_NEW_SIGNUPS=true

Restart to apply

cd /opt/karakeep
docker compose up -d

Install Browser Extensions and Mobile Apps

From the Karakeep UI, go to Settings → Quick Sharing to find links for the Chrome extension, Firefox extension, iOS app, and Android app. These let you add bookmarks from any device with a single tap.

Optional — AI-Powered Tagging

Karakeep can automatically tag and summarize bookmarks using an AI provider.

Using OpenAI:

Add to .env

OPENAI_API_KEY=sk-...

Using Ollama (local inference, no API costs):

Add to .env

OLLAMA_BASE_URL=http://your-ollama-host:11434
INFERENCE_TEXT_MODEL=llama3.2

Restart

cd /opt/karakeep
docker compose up -d

Optional — Full Page Archival & PDF Storage

Archive complete snapshots of bookmarked pages (useful for paywalled or ephemeral content):

Add to .env

CRAWLER_FULL_PAGE_ARCHIVE=true
CRAWLER_STORE_PDF=true

Both features increase storage usage. Monitor disk with df -h if on limited storage.

Optional — Video Downloads

Download videos from YouTube and other supported sites using yt-dlp:

Add to .env

CRAWLER_VIDEO_DOWNLOAD=true

Be mindful of storage capacity and bandwidth on your VPS.

Updating Karakeep

Pull latest and restart

cd /opt/karakeep
docker compose pull
docker compose up -d

For controlled upgrades, pin a specific version in .env:

Pin version

KARAKEEP_VERSION=0.31.0

Check the Karakeep releases page for changelogs before upgrading, as some releases include database migrations.

Backing Up Your Data

Karakeep stores all data in Docker volumes. Stop, archive, and restart:

Backup

cd /opt/karakeep
docker compose stop
tar -czf /root/karakeep-backup-$(date +%F).tar.gz /var/lib/docker/volumes/karakeep_data
docker compose start

For automated off-site backups, use rclone to sync to a remote bucket.

Troubleshooting

Chrome container keeps restarting

Check logs: docker compose logs chrome. If OOM errors appear, upgrade to a 2 GB VPS plan.

Search not returning results

Meilisearch may still be indexing. Go to Settings → Admin in the Karakeep UI and trigger a re-index.

Web container running but UI is blank

Confirm NEXTAUTH_URL in .env matches the domain you're accessing. A mismatch causes authentication failures.

Viewing container logs

Service logs

docker compose logs -f web
docker compose logs -f meilisearch
docker compose logs -f chrome

← More Deployment Guides View Cloud VPS Plans →