How to Deploy Karakeep on a VPS

copysudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw --force enable
sudo ufw status verbose

#Install Karakeep (Docker Compose)

Follow the upstream Docker install: make a directory, download the official Compose file into it, and write a .env beside it.

copymkdir -p ~/karakeep && cd ~/karakeep
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml

The upstream file publishes port 3000 on every interface. Bind it to loopback so Caddy is the only way in:

copycd ~/karakeep
sed -i 's|- 3000:3000|- 127.0.0.1:3000:3000|' docker-compose.yml
grep -n '3000' docker-compose.yml

Now the environment. NEXTAUTH_SECRET and MEILI_MASTER_KEY must be random — the docs suggest openssl rand -base64 36 — and NEXTAUTH_URL should be the address users will reach, which after the HTTPS step is your domain:

copycd ~/karakeep
[ -f .env ] || cat > .env <<EOF
KARAKEEP_VERSION=release
NEXTAUTH_SECRET=$(openssl rand -base64 36)
MEILI_MASTER_KEY=$(openssl rand -base64 36)
NEXTAUTH_URL=https://bookmarks.example.com
EOF
docker compose up -d
docker compose ps

KARAKEEP_VERSION=release follows the latest stable release. Upstream suggests pinning a version instead (for example KARAKEEP_VERSION=0.33.2) if you want to decide when upgrades happen.

Wait for the web app to answer:

copyfor i in $(seq 1 60); do
  code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/)
  case "$code" in 200|307|302) echo "Karakeep is up ($code)"; break ;; esac
  sleep 5
done
case "$code" in 200|307|302) true ;; *) docker compose logs --tail 50 web; false ;; esac

#Optional: AI tagging

AI tagging is off until you give it a provider. For OpenAI, add the key to .env and re-run docker compose up -d:

copycd ~/karakeep
echo "OPENAI_API_KEY=sk-..." >> .env
docker compose up -d

For local inference, the upstream "different AI providers" page covers Ollama; see Deploy Ollama on a VPS for running it. A tagging model on CPU is slow, so budget RAM for it separately from Karakeep.

#HTTPS + domain

Point an A record for bookmarks.example.com at the server — it must match NEXTAUTH_URL exactly, or sign-in and sign-out redirect to the wrong address. Then terminate TLS in front of 127.0.0.1:3000, following Automatic HTTPS with Caddy:

bookmarks.example.com {
    reverse_proxy 127.0.0.1:3000
}

If Caddy runs in a container, 127.0.0.1 is its own loopback: put it in the same Compose project and proxy to web:3000 instead.

#First account, then close signups

Open https://bookmarks.example.com and sign up. The first account created becomes the admin. Then close registration, so nobody else who finds the URL can create an account:

copycd ~/karakeep
grep -q '^DISABLE_SIGNUPS=' .env || echo "DISABLE_SIGNUPS=true" >> .env
docker compose up -d

Every change to .env needs another docker compose up -d to take effect. With DISABLE_SIGNUPS=true, the signup button is disabled. The Admin Settings page lists users and lets an administrator reset their passwords; to add someone later, remove the line, let them sign up, and put it back.

Install the browser extension and mobile app next, pointed at your server URL — that is where most saving happens in practice.

#Securing it: the crawler

Karakeep's upstream docs have a security page that is worth reading before you share an instance, because the crawler is a real browser running on your server:

• Anyone with an account can make your server fetch any URL, and see the result.
• Crawling a site the user controls reveals your server's IP address, even if the app itself sits behind a CDN.
• Requests come from inside your network, so they could reach internal endpoints (Karakeep has basic SSRF protections, which upstream says mitigate only some of this).

The upstream mitigations: keep accounts to trusted users, route the browser's traffic through a VPN or proxy with restricted network access, or run the browser container somewhere else. For a personal instance with signups closed, the first one is usually enough.

#Backups

State lives in two named volumes: data (the database, saved pages and assets) and meilisearch (the search index). With the project directory named karakeep, Compose names them karakeep_data and karakeep_meilisearch. Stop the stack for a consistent copy:

copycd ~/karakeep
docker compose stop
docker run --rm -v karakeep_data:/data -v "$(pwd)":/backup alpine \
  tar czf /backup/karakeep-data-$(date +%F).tar.gz -C /data .
docker run --rm -v karakeep_meilisearch:/meili -v "$(pwd)":/backup alpine \
  tar czf /backup/karakeep-meili-$(date +%F).tar.gz -C /meili .
docker compose start
ls -la karakeep-*.tar.gz

Keep .env with the backups (it holds the secrets the data was created with), confirm the volume names with docker volume ls, and copy everything off the server. Karakeep also has an API for creating and downloading backups, if you prefer to script it that way.

#Upgrades

How you upgrade depends on KARAKEEP_VERSION. With release, force a fresh pull:

copycd ~/karakeep
docker compose up --pull always -d

With a pinned version, bump it in .env and run docker compose up -d. The Compose file pins Meilisearch separately; upstream's troubleshooting page covers upgrading or migrating Meilisearch versions, which needs more care than the app itself. Back up first.

#Troubleshooting

Links save but have no content or preview. The crawler can't reach Chrome. Check docker compose ps shows the chrome container running, and docker compose logs web for crawler errors.

Sign-in or sign-out lands on the wrong address. NEXTAUTH_URL doesn't match the URL in the browser. Fix it in .env and run docker compose up -d.

Search returns nothing. Check the meilisearch container is up and that MEILI_MASTER_KEY hasn't changed since the index was created.

The box runs out of memory during an import. Crawling many links at once launches many pages; import in smaller batches or add RAM.

#Verification + next steps

You're done when you can load https://bookmarks.example.com over a valid certificate, save a link from the browser extension and find it by searching for a word in the page's text, see the signup button disabled in a private window, and have a backup of both volumes off the box.

If you want page archives with screenshots and PDFs and shared collections, compare Linkwarden. For hosts, see Best VPS for Self-Hosting.