Deploying Karakeep

Introduction

Karakeep (formerly known as Hoarder) is a self-hostable bookmark-everything application designed for digital hoarders who want to save and organize links, notes, images, and PDFs. With AI-powered automatic tagging and full-text search capabilities, Karakeep transforms how you collect and retrieve information from the web.

The application automatically fetches link titles, descriptions, and images, can take screenshots or create full-page archives, and provides lightning-fast search powered by Meilisearch. Optional AI tagging is available through OpenAI or locally via Ollama, giving you complete control over your data and privacy.

Key highlights of Karakeep:

• Bookmark Everything: Save links, notes, images, and PDFs in one unified platform
• AI-Powered Tagging: Automatic categorization using OpenAI or local Ollama models
• Full-Text Search: Fast, comprehensive search across all your saved content via Meilisearch
• Automatic Metadata: Fetches titles, descriptions, and preview images automatically
• Page Archiving: Create screenshots or full-page archives of bookmarked sites
• PDF Generation: Archive bookmarks as PDFs automatically or on-demand
• Browser Extensions: Save content directly from Chrome, Firefox, and other browsers
• Mobile Apps: Native iOS and Android applications for on-the-go bookmarking
• OIDC Authentication: Enterprise-ready authentication with OpenID Connect support
• Privacy-Focused: Self-hosted with complete data ownership

This guide walks through deploying Karakeep on Klutch.sh using Docker, configuring AI services for automatic tagging, and setting up persistent storage for your bookmark collection.

Why Deploy Karakeep on Klutch.sh

Deploying Karakeep on Klutch.sh provides several advantages for managing your bookmarks:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Karakeep without complex orchestration. Push to GitHub, and your bookmark manager deploys automatically.

Persistent Storage: Attach persistent volumes for your database, search index, and archived content. Your bookmarks survive container restarts without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your bookmarks from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Environment Variable Management: Securely store API keys for OpenAI or other services through Klutch.sh’s environment variable system.

Always-On Availability: Your bookmark manager remains accessible 24/7, ready to save content whenever inspiration strikes.

Prerequisites

Before deploying Karakeep on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Karakeep configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) OpenAI API key for AI-powered tagging

Preparing Your Repository

To deploy Karakeep on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

karakeep-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/karakeep-app/karakeep:latest

# Environment variables configured via Klutch.sh dashboard
# NEXTAUTH_SECRET - Required secret for authentication
# NEXTAUTH_URL - Your app URL
# MEILI_MASTER_KEY - Meilisearch master key
# OPENAI_API_KEY - Optional for AI tagging

EXPOSE 3000

Environment Variables Reference

Variable	Required	Description
NEXTAUTH_SECRET	Yes	Secret key for NextAuth.js session encryption
NEXTAUTH_URL	Yes	Full URL of your Karakeep instance
MEILI_MASTER_KEY	Yes	Master key for embedded Meilisearch
DATA_DIR	No	Data directory path (default: /data)
OPENAI_API_KEY	No	OpenAI API key for AI tagging
OLLAMA_BASE_URL	No	Ollama server URL for local AI
CRAWLER_STORE_PDF	No	Set to true to auto-archive as PDF

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
node_modules/

Deploying Karakeep on Klutch.sh

Once your repository is prepared, follow these steps to deploy Karakeep:

Generate Required Secrets

Before deployment, generate secure secrets:

# Generate NEXTAUTH_SECRET
openssl rand -base64 32

# Generate MEILI_MASTER_KEY
openssl rand -base64 32

Save these keys securely for the environment variables configuration.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial Karakeep deployment configuration"
git remote add origin https://github.com/yourusername/karakeep-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “karakeep” or “bookmarks”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Karakeep Dockerfile.

Configure HTTP Traffic

Karakeep serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

In the environment variables section, add:

Variable	Value
NEXTAUTH_SECRET	Your generated secret from step 1
NEXTAUTH_URL	https://your-app-name.klutch.sh
MEILI_MASTER_KEY	Your generated Meilisearch key
OPENAI_API_KEY	Your OpenAI API key (optional)

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
/data	10 GB	Database, search index, and archived content

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision HTTPS.

Access Karakeep

Once deployment completes, access your Karakeep instance at https://your-app-name.klutch.sh. Create your first account to start bookmarking.

Initial Setup and Configuration

Creating Your Account

On first access, create an account:

1. Click Sign Up to create your user account
2. Set a strong password for your bookmarks
3. Log in to access the dashboard

Installing Browser Extensions

Extend Karakeep with browser extensions:

1. Visit the extensions page in your Karakeep settings
2. Download the extension for your browser (Chrome, Firefox)
3. Configure the extension with your server URL and API key
4. Start bookmarking with a single click

Configuring AI Tagging

For automatic AI-powered tagging:

With OpenAI:

1. Ensure OPENAI_API_KEY is set in environment variables
2. Tags will be automatically generated for new bookmarks

With Ollama (Local AI):

1. Set OLLAMA_BASE_URL to your Ollama server
2. Select your preferred model in settings
3. Enjoy private, local AI tagging

Production Best Practices

Data Protection

• Regular Backups: Back up the /data volume regularly
• Export Bookmarks: Use the export feature for portable backups
• Monitor Storage: Archived content can grow quickly

Security Recommendations

• Strong Secrets: Use cryptographically secure random strings
• Keep Updated: Regularly update for security patches
• API Key Security: Rotate API keys periodically

Troubleshooting Common Issues

Search Not Working

Solutions:

• Verify MEILI_MASTER_KEY is properly set
• Check that the data volume is mounted correctly
• Allow time for initial indexing after restart

AI Tagging Not Functioning

Solutions:

• Verify API key is valid and has available credits
• Check Ollama server connectivity if using local AI
• Review application logs for API errors

Additional Resources

• Karakeep GitHub Repository
• Karakeep Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Karakeep on Klutch.sh gives you a powerful, AI-enhanced bookmark manager with automatic builds, persistent storage, and secure HTTPS access. Whether you’re saving articles for later reading, archiving important web pages, or organizing research materials, Karakeep provides the tools to keep everything organized and searchable.

With browser extensions, mobile apps, and AI-powered organization, Karakeep on Klutch.sh becomes your personal knowledge base accessible from anywhere.