Install Karakeep on a VPS with Docker Compose and HTTPS

What is Karakeep, and why self-host it?

Karakeep, previously called Hoarder, stores bookmarks, notes and uploaded content in a library with search and organisation tools. Browser extensions and mobile clients make it easier to add something while you are reading it. Hosting the application on a VPS gives those clients an always-available endpoint. Explore the Karakeep project.

The 0.35 release refreshes the reading and organisation interfaces, improves article extraction and includes fixes affecting authentication, shared content and container security. Browser-extension and mobile updates may reach their stores after the server release. Check their release status when updating clients. Review the changes in 0.35.0.

Choose a VPS for the library and crawler

This walkthrough creates a new installation on an Ubuntu or Debian VPS with Docker Engine and the Compose plugin already installed. Our Docker installation guide covers that prerequisite. Use an administrator account with Docker access and a domain you control. Install Docker on Ubuntu.

For a personal deployment, a practical starting allocation is 2 vCPU and 4 GB RAM, with space for the operating system, images, saved assets and search index. That is an editorial starting point. Measure your own usage during imports, PDF processing and crawling before selecting a long-term allocation.

Create a DNS A record for bookmarks.example.com pointing to the VPS. Publish an AAAA record when IPv6 reachability works too. Replace this example hostname throughout the guide. Public access will use TCP ports 80 and 443, with SSH restricted to your administrators.

The crawler retrieves submitted URLs from the server's network. Use this deployment for people you trust to submit that content, and review the upstream security guidance before widening access. Read the crawler security considerations.

1. Create the deployment directory and secrets

On the VPS, check Docker and install the small command-line prerequisites used below.

docker version
docker compose version
sudo apt update
sudo apt install --yes curl openssl

Create a dedicated directory. The following commands create a fresh .env with two independently generated secrets and restrictive file permissions.

mkdir -p ~/karakeep
cd ~/karakeep
umask 077
cat > .env <<EOF
NEXTAUTH_SECRET=$(openssl rand -hex 32)
MEILI_MASTER_KEY=$(openssl rand -hex 32)
NEXTAUTH_URL=http://localhost:3000
AUTH_TRUSTED_ORIGINS=
DISABLE_SIGNUPS=false
RATE_LIMITING_ENABLED=true
EOF

The temporary localhost URL is used while you create the initial account over SSH. Keep the generated secrets for subsequent starts and recovery. For changes to an existing installation, edit its environment file while retaining the required original values. The configuration reference explains authentication origins and rate limiting. Review Karakeep environment variables.

2. Define the Docker Compose services

Create compose.yaml in the same directory. This adapts the version-matched upstream stack with a stable project name, explicit image versions and a loopback-only web port.

name: karakeep
services:
  web:
    image: ghcr.io/karakeep-app/karakeep:0.35.0
    restart: unless-stopped
    volumes:
      - data:/data
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    environment:
      MEILI_ADDR: http://meilisearch:7700
      BROWSER_WEB_URL: http://chrome:9222
      DATA_DIR: /data

  chrome:
    image: ghcr.io/karakeep-app/karakeep-chrome:157.0.8103.38-r1
    restart: unless-stopped
    init: true
    command:
      - --disable-gpu
      - --disable-dev-shm-usage
      - --hide-scrollbars
      - --disable-blink-features=AutomationControlled
      - --window-size=1440,900

  meilisearch:
    image: getmeili/meilisearch:v1.55.0
    restart: unless-stopped
    env_file:
      - .env
    environment:
      MEILI_NO_ANALYTICS: "true"
    volumes:
      - meilisearch:/meili_data

volumes:
  data:
  meilisearch:

The Chrome revision above was available alongside the 0.35.0 release. The image maintainer documents its versioned tags. Keep the internal addresses and DATA_DIR aligned with the mounts when adapting the file. Compare the upstream Compose file. Read the Chrome image guide.

Validate the file without printing the resolved secrets, then pull and start the services.

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80 web chrome meilisearch

Allow the services to finish starting. The named volumes keep application data and the search index across container recreation. Keep the karakeep project name consistent when moving or restoring this deployment.

3. Create the administrator through an SSH tunnel

The first registered account receives administrator privileges. Keep this setup phase private. Run the following command on your own computer, replacing the SSH account and server address.

ssh -N -L 3000:127.0.0.1:3000 admin@YOUR_VPS_IP

Leave the connection open. Visit http://localhost:3000 in your computer's browser, create your account and confirm that you can sign in. Use localhost exactly, matching the configured authentication origin. Other servers or applications using local port 3000 must be stopped or given another local tunnel port and matching temporary URL.

After creating the account, edit the VPS .env. Change these two existing lines while retaining the other values.

NEXTAUTH_URL=https://bookmarks.example.com
DISABLE_SIGNUPS=true

Apply the new environment to the web service.

docker compose up -d web
docker compose logs --tail=50 web

Close the SSH tunnel when finished. You will sign in again at the HTTPS hostname after the next step. With registration closed, an administrator can create additional accounts through the administration interface. Review first-user and account administration behaviour.

4. Add HTTPS with Caddy

Install Caddy from its official stable package repository on the VPS.

sudo apt install --yes debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/gpg.key | \
  sudo gpg --yes --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt | \
  sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

The package supplies a systemd service. Add the following site block to /etc/caddy/Caddyfile, using the hostname you placed in NEXTAUTH_URL. Review Caddy installation.

bookmarks.example.com {
    reverse_proxy 127.0.0.1:3000
}

Validate the complete Caddyfile and reload the service.

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl --fail --head https://bookmarks.example.com

Caddy handles certificate issuance and the HTTPS reverse proxy. Its validation challenges need working DNS and access to the required public ports. Check both IP families when an AAAA record is present. Review automatic HTTPS requirements.

Open the HTTPS address, sign in and check that registration is closed. Test from outside the VPS as well. Public connections to ports 3000, 7700 and 9222 should fail, while the HTTPS application remains reachable. The single-proxy configuration above uses Karakeep's normal client-IP handling.

5. Import bookmarks and test a complete save

Begin with a small browser-bookmark export so you can observe the entire workflow. Karakeep supports Netscape-format HTML exports and several service-specific formats. Choose the appropriate import option in the application settings, keeping a copy of the original export. The importer adds the URLs contained in that file. Review supported import formats.

Save a public article, add a note and place it in a list. Give it time to finish processing, then search for a distinctive word from its content. Upload a small reference PDF as a second test and confirm that it remains available after restarting the web container.

docker compose restart web
docker compose ps

Connect your browser extension or mobile client using the same HTTPS base URL. Repeat a save from that client and check it in the web interface. The project links to its supported clients. Find Karakeep capture tools.

Move a large library in stages. Watch memory, disk use and processing logs as the crawler and indexer work through it. An idle server's resource usage gives only part of the capacity picture.

docker stats --no-stream
df -h
docker compose logs --tail=100 web meilisearch

Add AI tagging when you need it

The basic deployment above leaves the AI provider unset. You can organise the library manually and use its text-search service while deciding whether automated tagging and summaries would help your workflow.

Karakeep supports hosted inference providers and Ollama, with separate settings for models and embeddings. Choose a supported provider, review which saved content will be processed by it and budget its charges or hardware requirements. Apply any environment changes with docker compose up -d web. Review the provider configuration guide.

Back up the library before planning upgrades

A recovery copy needs the data and the deployment settings together. For the project name used here, record the two Docker volumes and inspect them before configuring your backup job.

docker volume inspect karakeep_data karakeep_meilisearch

For a straightforward filesystem archive, stop the stack, export both volumes using a Docker volume-backup workflow, then start the stack again. Restart the services after the attempt even if archiving fails. Archive the configuration alongside the volume copies, protect the secrets and retain the exact image versions used. Docker documents backing up and restoring named volumes. Review Docker volume backups.

Store encrypted recovery copies away from the live VPS. A HYEHOST Storage Box can provide an SFTP destination for those archives. Test a restore on an isolated server and check sign-in, saved notes, uploaded files and search before relying on the backup. Set up encrypted off-server copies with rclone.

When upgrading, review the target release, take the recovery copy, then update the image versions deliberately. Check the corresponding upstream Compose file and any Meilisearch migration requirements. Follow the update with the same save, search and client-login tests used during installation. Our Compose update guide includes a repeatable maintenance workflow. Plan a Docker Compose update.

Common Karakeep Docker problems

Karakeep VPS hosting FAQ