Karakeep

Overview

Karakeep collects links, text notes, images, and PDFs in a private library. Lists, tags, favourites, and full-text search make it useful for research, household references, and reading later. Official Android and iOS apps and browser extensions can send items to the server; a standalone desktop client is not bundled.

Compared with Linkwarden, evaluate how each handles lists, saved formats, sharing, and search. Karakeep also keeps plain text notes alongside links. Saving a URL is not a guarantee that a paywall, login page, or bot-protected site can be archived.

This recipe runs the official app with SQLite, Meilisearch 1.41.0, and a separate headless browser. Allow two cores, 2 GB RAM minimum (4 GB recommended), and 10 GB disk plus saved content. Browser jobs can exceed those estimates; monitor disk and memory. The reliable deployment level is unsupported: this single-server recipe has no external database, monitoring, or resource limits.

Password login and native OIDC are available upstream; this recipe configures password login only. It does not configure SAML, a second factor, trusted-header login, SMTP, or an AI provider. AI tagging is optional, and bookmark capture and search work without an API key. Backups are not end-to-end encrypted.

The application is AGPL-3.0 licensed; the deployment recipe is MIT licensed. See the upstream licence before modifying and serving the software. This entry is experimental until wider deployment evidence exists.

Sources: features and clients, configuration, security considerations, release, licence.

Security assessment

The reviewed configuration keeps registration closed and internal service ports private. Basic SSRF checks and container isolation do not make hostile crawled content safe. Use trusted accounts and an independent egress policy. This review is not a security audit.

Step-by-step guide

Prepare the server

Use 64-bit Ubuntu 22.04+ or Debian 12+, Docker Engine, and Compose v2.24+. Allow two cores, 2 GB RAM minimum (4 GB recommended), and 10 GB disk plus saved content. These are planning estimates, not a capacity benchmark.

mkdir -p ~/services/karakeep
cd ~/services/karakeep
# Copy every recipe file, including proxy/ and the scripts, here.
cp .env.example .env
chmod 600 .env
openssl rand -hex 32
openssl rand -hex 32

Put the two different generated values in KARAKEEP_AUTH_SECRET and KARAKEEP_MEILI_KEY. The scripts source .env as trusted shell configuration. Use shell-safe values and protect it from other users.

The data named volume holds SQLite, uploaded files, saved pages, and queue state under /data. The search volume holds the Meilisearch index under /meili_data. Chrome state is disposable. Compose scopes both volumes to the project; keep the project name stable. Neither the search API nor Chrome’s DevTools port is published.

Start and create an account

Keep the reverse proxy disabled. Set KARAKEEP_DISABLE_SIGNUPS=false, then:

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 600
curl --fail http://127.0.0.1:3000/api/health

From your computer run ssh -L 3000:127.0.0.1:3000 user@server. Open http://localhost:3000, sign up with a unique password, and verify login. Set KARAKEEP_DISABLE_SIGNUPS=true and recreate the app:

docker compose up -d --wait --wait-timeout 600 karakeep

Only publish the proxy after signup is closed. There are no committed account credentials. Additional accounts require another controlled registration window. AI, SMTP, and OIDC are not configured. Do not add an external AI key unless you accept its privacy and billing terms.

VPS

Complete the account setup through the tunnel first. Set KARAKEEP_URL=https://keep.example.com, configure DNS and an HTTPS proxy, and recreate Karakeep. Permit only SSH, HTTP, and HTTPS through the firewall. Keep port 3000 bound to loopback and store encrypted backups off-server.

Trusted local network

Use the SSH tunnel or an HTTPS proxy reachable from your trusted LAN/VPN. Keep the loopback binding when using a host proxy. If you deliberately bind a private interface, restrict it with a firewall and set KARAKEEP_URL to the exact origin people open. Do not expose a registration window to untrusted users.

Domain and HTTPS

Choose a sample in proxy/. Caddy obtains certificates; Nginx needs your certificate paths; Traefik needs the websecure entry point and letsencrypt resolver. These host-proxy samples forward to 127.0.0.1:3000. A container proxy must share a network with Karakeep and use karakeep:3000; its loopback is not the host loopback.

Replace the example hostname and keep KARAKEEP_URL identical to the external origin. Forward Host and X-Forwarded-Proto correctly; an HTTPS origin uses secure cookies. The Nginx sample permits 50 MB request bodies. Test login and an upload over the final URL. Do not publish ports 7700 or 9222.

Backup

./backup.sh

The script stops Karakeep and Meilisearch, archives both complete volumes plus active .env and Compose, and restarts only the services that were running. The private archive is backups/karakeep-<timestamp>.tar. SQLite and its WAL must be copied together while writers are stopped. Keep the search index with the matching engine version.

Encrypt and copy this archive off-server. It contains accounts, private notes, pages, files, keys, and secrets. A personal export or server-to-server CLI migration does not replace this backup.

Restore

Restore replaces both volumes. Use a trusted archive and the matching application and Meilisearch versions. On a fresh server, copy the recipe, inspect the archived compose.yaml and configuration.env, and recreate compatible active configuration first. Archived configuration is not activated automatically.

docker compose up -d --wait --wait-timeout 600
./restore.sh ./backups/karakeep-TIMESTAMP.tar
curl --fail http://127.0.0.1:3000/api/health

The script checks archive members, creates a safety backup, replaces both volumes, and waits for health. If replacement fails, keep the services stopped until you restore a verified archive. Sign in, read a private note, open a saved file, and search for known content. The smoke test verifies an account, private note, and a stored file after removal of both original volumes; it does not prove recovery across versions.

Update

1. Read the release notes and create an off-server backup.
2. Change KARAKEEP_VERSION to the reviewed exact version. Change the separately pinned Chrome image only after reviewing its release and compatibility.
3. Run docker compose pull, then docker compose up -d --wait --wait-timeout 600. Check logs, login, a saved page, and search.
4. Treat a Meilisearch version change as a separate migration. Follow the official index upgrade guide: take a complete backup, use the migration option documented for that exact engine version, then remove it. Do not start a new engine on old data without a migration or a deliberate index rebuild.

Application migrations run at startup. Never use latest or release as a deployment tag. A successful healthcheck alone does not prove that search and saved content survived.

Rollback

Do not run an older app on a migrated SQLite database or an older Meilisearch on a newer index.

1. Keep the pre-update archive and the matching recipe/configuration.
2. Stop writers: docker compose stop karakeep meilisearch.
3. Restore the old exact application and sidecar versions in active Compose and .env; retain matching secrets. Pull those images.
4. Run docker compose create without starting them on the new data.
5. Run ./restore.sh ./backups/karakeep-BEFORE-UPDATE.tar, then verify login, notes, saved files, and search. The safety backup can archive stopped containers without running the old app on new state.

Stop and remove

docker compose down keeps the volumes. After verifying an encrypted off-server backup, docker compose down --volumes permanently removes the library and index. Deleting the recipe directory also deletes local configuration and backups. Do not use global Docker pruning commands.

Sources: Docker deployment, configuration, security, server migration limits.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

Startup or healthcheck failure

Run docker compose ps --all and docker compose logs --tail=200 karakeep meilisearch chrome. Check free disk and RAM with df -h and free -m. Browser jobs need more memory than an idle instance. Confirm you replaced both secrets and retained the Meilisearch key between restarts. docker compose config --quiet checks interpolation; avoid sharing the full rendered configuration because it contains secrets.

Login fails or cookies disappear

Check that KARAKEEP_URL is the exact origin you opened, including scheme and nonstandard port. An HTTPS origin needs HTTPS and correct forwarded headers. For first setup use http://localhost:3000 through the SSH tunnel. Registration is deliberately disabled; temporarily enable it only in a trusted setup window, then disable it and recreate the app. OIDC and SMTP require additional upstream configuration and are not included.

A page will not archive

Check Chrome health and crawler logs. Paywalls, login pages, bot protection, large files, and unsupported sites may prevent capture. Private/internal targets are blocked by default; do not disable SSRF protections to fix an arbitrary bookmark. The app and browser need outbound access. Do not publish the Chrome debugging port as a workaround.

Search stopped after an engine update

Read the Meilisearch logs for an incompatible database-version message. Restore the old engine together with the matching full backup, or follow the official index migration/rebuild guide. Do not remove the whole library volume to rebuild a disposable search index.

Backup or restore failed

Use a trusted archive produced by this recipe, matching images, and the matching secrets from the archived configuration. The scripts require created containers to discover the exact named volumes. Review errors before restarting writers; a failed replacement must not be treated as successful recovery. Keep the source archive and the safety backup until login, private content, files, and search are verified.

Sources: configuration, security, Meilisearch upgrade.