Karakeep is a self-hosted place to keep everything you want to read later: links, notes, and images, with full-text search over the lot and a crawler that grabs a title, a screenshot, and a readable copy of every page you save. It is open source, it runs in Docker, and it can tag your bookmarks automatically with an AI model you point it at. If you used to run Hoarder, this is the same project under a new name. It sits happily next to the other self-hosted Docker apps in a homelab, the way a self-hosted photo library does.
By the end of this guide you’ll self-host Karakeep with Docker Compose, create your admin account, save your first bookmarks and watch the crawler fill them in, wire up AI tagging against either OpenAI or a local Ollama model, and put the whole thing behind HTTPS. The install itself is three containers and a handful of settings, so the setup is genuinely short. The part that trips people up is the two secrets it needs before the first boot, and we’ll get those right the first time.
Set up with Docker on Ubuntu 24.04 in September 2026, on Karakeep 0.33, and it works end to end.
What you need
Any Docker host works. This was run on Ubuntu 24.04, and the same commands run unchanged on Debian, Rocky Linux, or Ubuntu 26.04 because everything happens inside containers. Karakeep is light: the app and its Meilisearch search index sip resources, and the one thing that spikes memory is the headless Chrome that renders each page you save. Two vCPUs and 2 GB of RAM handle personal use comfortably; the number to watch as your library grows is the Meilisearch index, and the knob to watch under heavy importing is how many pages the crawler fetches at once. The lab box here ran four vCPUs and 6 GB, which is a comfortable floor rather than a target.
You also need Docker with the Compose plugin. If it isn’t installed yet, the Docker and Docker Compose setup covers it in a few minutes; come back here once docker compose version prints a version.
Get the compose file
Karakeep ships an official Compose file that wires the three services together. Make a directory for the deployment and pull it down:
mkdir -p ~/karakeep-app && cd ~/karakeep-app
curl -fsSL https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml -o docker-compose.ymlThe file defines three services: web is Karakeep itself on port 3000, chrome is the headless browser that crawls and screenshots saved pages, and meilisearch is the search engine behind that search bar. Data lives in two named Docker volumes, so your bookmarks survive a container rebuild.
Create the environment file
This is the step to slow down on. Karakeep will not start correctly without two random secrets, and it reads them from a .env file next to the compose file. Generate each one with openssl:
openssl rand -base64 36
openssl rand -base64 36Run it twice and keep both values. Now create the file:
vim ~/karakeep-app/.envPaste the following, dropping each generated secret into place. Set NEXTAUTH_URL to the address you’ll actually reach Karakeep on. For a first test that can be the server’s IP; once HTTPS is in place further down, change it to your domain:
KARAKEEP_VERSION=release
NEXTAUTH_SECRET=first_openssl_value_here
MEILI_MASTER_KEY=second_openssl_value_here
NEXTAUTH_URL=http://10.0.1.50:3000The single most common reason a fresh install throws login errors is a NEXTAUTH_URL that does not match the address in the browser. If you sign in at the IP but this says a domain, authentication breaks. Keep them the same.
Start Karakeep
Pull the images and bring the stack up:
docker compose pull
docker compose up -dGive it a few seconds, then check that all three containers are up:
docker compose psThe web service shows a port mapping of 0.0.0.0:3000->3000/tcp. Open http://SERVER-IP:3000 in a browser and Karakeep sends you to its sign-in screen.
Create your account
The first account you create becomes the admin. Follow the sign-up link, fill in your name, email, and a password, and you’re in.
Once your account exists, lock the door behind you. Karakeep leaves signups open by default, which is fine on a laptop but not on anything reachable from the internet. Add one line to .env and recreate the container so nobody else can register on your instance:
echo "DISABLE_SIGNUPS=true" >> ~/karakeep-app/.env
docker compose up -dAdd your first bookmarks
The box at the top of the home view takes anything: paste a link, type a note, or drop an image. Paste a URL and hit Save.
The card appears immediately, then fills in on its own a moment later. That is the chrome container doing its job: it loads the page, pulls the title and a preview image, takes a screenshot, and stores a readable copy so the content is searchable even if the original site goes down. Save a few and the home view turns into a proper library.
From here the search bar covers titles, page text, URLs, and tags, so you can find that one article by a phrase you half-remember from inside it. Lists group bookmarks by topic, Highlights keeps the passages you marked, and Archive gets things out of the way without deleting them.
Turn on AI tagging
This is what makes Karakeep more than a link dump. Point it at a language model and it reads each saved page and tags it automatically, so your library organizes itself. You have two routes, and both are a couple of lines in .env.
The private route keeps everything on your own hardware by pointing Karakeep at a local Ollama server. Nothing about your bookmarks leaves the network:
OLLAMA_BASE_URL=http://10.0.1.60:11434
INFERENCE_TEXT_MODEL=llama3.2
INFERENCE_IMAGE_MODEL=llavaThe hosted route uses OpenAI instead, which needs no local GPU and returns tags faster. Set the key and, if you want, the models:
OPENAI_API_KEY=your-openai-api-key
INFERENCE_TEXT_MODEL=gpt-4o-miniIf you already run a local RAG stack on Ollama, Karakeep can share the exact same endpoint. Auto-tagging is on by default once a model is configured, controlled by INFERENCE_ENABLE_AUTO_TAGGING. Recreate the container with docker compose up -d after editing .env, then save a new bookmark and watch tags land on it a few seconds after the crawl finishes. Existing bookmarks can be re-tagged in bulk from their action menu.
Put it behind HTTPS
Running a login page over plain HTTP is fine for the first ten minutes and not after that. Put Nginx in front as a reverse proxy and let Certbot handle the certificate. Point an A record for your domain at the server, make sure port 80 is reachable, then install the pieces:
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginxCreate a server block that forwards to Karakeep on port 3000:
sudo vim /etc/nginx/sites-available/karakeepUse your own domain in the server_name:
server {
listen 80;
server_name bookmarks.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
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;
}
}Enable the site and reload Nginx:
sudo ln -s /etc/nginx/sites-available/karakeep /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginxNow issue the certificate. Certbot rewrites the Nginx config for TLS and sets up auto-renewal in one command:
sudo certbot --nginx -d bookmarks.example.com --non-interactive --agree-tos --redirect -m [email protected]If the server sits on a private LAN with no public port 80, the HTTP-01 challenge above cannot reach it. In that case use a DNS-01 challenge instead, which proves ownership through a DNS record and works behind NAT. Certbot has plugins for most providers (Cloudflare, Route 53, DigitalOcean, Google Cloud DNS, Linode); install the one for your DNS host and pass it to Certbot in place of --nginx. The same reverse-proxy pattern, with a worked TLS example, is in the Nginx and Let’s Encrypt walkthrough.
One last edit closes the loop. Change NEXTAUTH_URL in .env to the HTTPS address and recreate the container, or logins will misbehave over the new domain:
NEXTAUTH_URL=https://bookmarks.example.comThe settings area is worth a look once you’re in over HTTPS. It holds API keys for the browser extension and mobile apps, RSS subscriptions, scheduled backups, import and export, and a rule engine for auto-filing new bookmarks.
Common questions
Is Karakeep the same as Hoarder?
Yes. Karakeep is Hoarder renamed. The project, the maintainers, and the data model are the same; only the name and the container images changed. Old Hoarder installs migrate by switching to the karakeep images.
Do I need an OpenAI key to use it?
No. Karakeep is fully usable with no AI at all: saving, crawling, full-text search, lists, and highlights all work without a model. AI is only needed for automatic tagging and summaries, and even then a local Ollama model replaces OpenAI entirely.
How do I back up my bookmarks?
Everything lives in the two Docker volumes, so a filesystem snapshot of the data and meilisearch volumes captures the whole instance. For a portable copy, the settings area has a built-in export, and scheduled backups can be turned on there too.
Can I import my existing bookmarks?
Yes. Import and export live in the settings area and accept the standard browser bookmarks HTML file, along with Pocket and other common formats, so moving a years-old collection in is a single upload.
