Deploying Briefkasten

Briefkasten is a modern, self-hosted bookmarking application that helps you save, organize, and discover your web bookmarks. Built with Next.js, Prisma, and TailwindCSS, Briefkasten provides a powerful yet simple interface for managing your personal bookmark vault. Whether you’re a researcher, content curator, student, or professional, Briefkasten offers the flexibility to organize bookmarks with categories and tags, search through your entire collection with fulltext search, save bookmarks via a browser extension or drag-and-drop, and maintain complete control over your bookmark data with self-hosting.

Why Briefkasten?

Briefkasten stands out as the premier choice for self-hosted bookmark management with exceptional features:

Browser Extension: Save bookmarks directly from your browser with one click
Automatic Metadata: Automatic title and description extraction from saved pages
Drag-and-Drop Saving: Drag URLs directly onto the page to save bookmarks
Keyboard Shortcuts: Quick access with customizable keyboard shortcuts
Category Organization: Organize bookmarks into categories for easy navigation
Tag System: Flexible tagging system for fine-grained organization
Fulltext Search: Lightning-fast search across all your bookmarks
Import/Export: Import bookmarks from standard HTML format and export whenever needed
Multiple Views: Different view options for browsing your bookmarks
REST API: Complete API for integrations and automation
OAuth Authentication: Support for multiple OAuth providers
Email Magic Links: Simple email-based authentication without passwords
Image Fetching: Background job support for bookmark thumbnail generation
Responsive Design: Works seamlessly on desktop, tablet, and mobile
Database Flexibility: Works with MySQL, Postgres, SQLite, or any Prisma-compatible database
Fast and Lightweight: Optimized performance with minimal resource usage
Open Source: MIT licensed with active community
Self-Hosted Control: Complete data ownership and privacy
No Ads or Tracking: Your bookmarks stay private on your infrastructure
Screenshot Integration: Optional background job for capturing bookmark screenshots

Briefkasten is ideal for researchers organizing sources and references, content curators saving and sharing articles, knowledge workers managing research materials, students collecting educational resources, developers bookmarking documentation and code examples, and anyone wanting complete control over their bookmark data. With persistent storage on Klutch.sh, your bookmark vault is always available and secure.

Prerequisites

Before deploying Briefkasten, ensure you have:

A Klutch.sh account
A GitHub repository with your Briefkasten deployment configuration
Basic familiarity with Docker and Git
A database supporting Prisma (PostgreSQL, MySQL, or SQLite)
OAuth provider credentials (optional, for OAuth login)
Sufficient storage for bookmarks and images (typically 5-20GB)
Custom domain for your bookmark application (recommended)
Environment variables configured before deployment

Important Considerations

Deploying Briefkasten

Create a New Project
Log in to your Klutch.sh dashboard and create a new project for your Briefkasten bookmark vault.

Prepare Your Repository

Create a GitHub repository with the following structure for your Briefkasten deployment:

briefkasten-deploy/
├─ Dockerfile
├─ .env.example
├─ entrypoint.sh
├─ .gitignore
└─ README.md

Here’s a Dockerfile for Briefkasten:

FROM node:18-alpine

WORKDIR /app

# Install system dependencies
RUN apk add --no-cache \
    curl \
    git \
    build-base \
    python3

# Clone Briefkasten repository
RUN git clone https://github.com/ndom91/briefkasten.git /tmp/briefkasten && \
    cp -r /tmp/briefkasten/* .

# Install pnpm
RUN npm install -g pnpm

# Install dependencies
RUN pnpm install --frozen-lockfile

# Create necessary directories
RUN mkdir -p /app/data \
    /app/logs \
    && chmod -R 755 /app

# Copy entrypoint script
COPY entrypoint.sh /
RUN chmod +x /entrypoint.sh

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:3000/ || exit 1

# Run entrypoint
ENTRYPOINT ["/entrypoint.sh"]
CMD ["pnpm", "start"]

Create an entrypoint.sh file:

#!/bin/bash

set -e

# Create necessary directories
mkdir -p /app/data \
         /app/logs

# Set proper permissions
chmod -R 755 /app

echo "Initializing Briefkasten..."

# Wait for database to be ready
echo "Checking database connection..."
MAX_RETRIES=30
RETRY_COUNT=0

until node -e "
  const db = require('./prisma/client.js');
  db.\$connect().then(() => process.exit(0)).catch(() => process.exit(1));
" 2>/dev/null; do
  RETRY_COUNT=$((RETRY_COUNT + 1))
  if [ $RETRY_COUNT -gt $MAX_RETRIES ]; then
    echo "Database not available after $MAX_RETRIES retries"
    exit 1
  fi
  echo "Waiting for database... (attempt $RETRY_COUNT/$MAX_RETRIES)"
  sleep 2
done

echo "Database is available!"

# Run database migrations
echo "Running database migrations..."
pnpm db:push || true

# Build Next.js application
echo "Building Briefkasten..."
pnpm build || true

echo "Briefkasten is starting..."
exec "$@"

Create a .env.example file:

# Briefkasten Configuration
APP_NAME=Briefkasten
APP_DESCRIPTION=Self-hosted bookmarking application

# Database Configuration
DATABASE_URL=postgresql://briefkasten:secure_password@postgres.internal:5432/briefkasten
SHADOW_DATABASE_URL=postgresql://briefkasten:secure_password@postgres.internal:5433/briefkasten_shadow

# NextAuth Configuration
NEXTAUTH_URL=https://bookmarks.yourdomain.com
NEXTAUTH_SECRET=your-secret-key-32-characters-long

# Authentication Providers (optional)
GOOGLE_ID=your-google-oauth-id
GOOGLE_SECRET=your-google-oauth-secret

GITHUB_ID=your-github-oauth-id
GITHUB_SECRET=your-github-oauth-secret

# Image Storage Configuration (optional)
# For Supabase
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_BUCKET_URL=https://your-project.supabase.co/storage/v1/object/public/briefkasten

# Application Settings
NEXT_PUBLIC_APP_URL=https://bookmarks.yourdomain.com

# Server Configuration
NODE_ENV=production

Create a .gitignore file:

.env
.env.local
node_modules/
.next/
build/
dist/
out/
*.log
logs/
data/
.DS_Store
.vercel/
.idea/
*.swp
*.swo

Commit and push to your GitHub repository:

git init
git add .
git commit -m "Initial Briefkasten bookmarking deployment"
git remote add origin https://github.com/yourusername/briefkasten-deploy.git
git push -u origin main

Create a New App
In the Klutch.sh dashboard:
- Click “Create New App”
- Select your GitHub repository containing the Dockerfile
- Choose the branch (typically main or master)
- Klutch.sh will automatically detect the Dockerfile in the root directory

Configure Environment Variables

Set up these essential environment variables in your Klutch.sh dashboard:

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection	`postgresql://user:password@host:5432/briefkasten`
`NEXTAUTH_URL`	Application URL	`https://bookmarks.yourdomain.com`
`NEXTAUTH_SECRET`	Session encryption key	`your-secret-key`
`NODE_ENV`	Environment	`production`
`NEXT_PUBLIC_APP_URL`	Public app URL	`https://bookmarks.yourdomain.com`

For OAuth authentication, add provider credentials:

Variable	Description
`GOOGLE_ID`	Google OAuth app ID
`GOOGLE_SECRET`	Google OAuth secret
`GITHUB_ID`	GitHub OAuth app ID
`GITHUB_SECRET`	GitHub OAuth secret

For image storage with Supabase:

Variable	Description
`SUPABASE_ANON_KEY`	Supabase anonymous key
`SUPABASE_BUCKET_URL`	Supabase storage bucket URL

Configure Persistent Storage
Briefkasten requires persistent storage for bookmark data. Add a persistent volume:

Mount Path Description Recommended Size
/app/data Bookmark data and cache 20GB
In the Klutch.sh dashboard:
- Navigate to your app settings
- Go to the “Volumes” section
- Click “Add Volume”
- Set mount path: /app/data
- Set size: 20GB (or appropriate for your needs)
- Ensure volume has adequate space for your bookmark collection
Set Network Configuration
Configure your app’s network settings:
- Select traffic type: HTTP
- Recommended internal port: 3000 (Next.js default)
- Klutch.sh will handle HTTPS termination via reverse proxy
- Application will be accessible via your custom domain
Configure Custom Domain
Briefkasten benefits from a custom domain:
- Navigate to your app’s “Domains” section in Klutch.sh
- Add custom domain (e.g., bookmarks.yourdomain.com)
- Configure DNS with CNAME record pointing to your Klutch.sh app
- Update NEXTAUTH_URL and NEXT_PUBLIC_APP_URL environment variables
- Klutch.sh will automatically provision SSL certificate
- Wait for DNS propagation (typically 5-15 minutes)
Deploy Your App
- Review all settings and environment variables carefully
- Verify database connection string is correct
- Ensure OAuth provider credentials are configured (if using OAuth)
- Verify custom domain is configured
- Click “Deploy”
- Klutch.sh will build the Docker image and start your Briefkasten instance
- Wait for deployment to complete (typically 10-20 minutes)
- Access your Briefkasten at your configured domain
- Log in with OAuth provider or email magic link

Mount Path	Description	Recommended Size
`/app/data`	Bookmark data and cache	20GB

Initial Setup and Configuration

After deployment completes, access your Briefkasten instance to configure your bookmarking system.

Accessing Briefkasten

Navigate to your domain: https://bookmarks.yourdomain.com

Choosing Authentication Method

OAuth Authentication

Click “Sign in with [Provider]” (Google, GitHub, etc.)
Complete provider authorization
Briefkasten creates account automatically
Access to bookmark vault granted

Email Magic Link

Click “Sign in with Email”
Enter your email address
Check email for magic link
Click link to sign in
No password required

Dashboard Overview

Explore the main interface:

Dashboard: Your bookmarks at a glance
Browse: All bookmarks with filters and search
Categories: Organize bookmarks by category
Tags: Filter bookmarks by tags
Collections: Group related bookmarks together
Settings: Configure your account

Creating Categories

Organize bookmarks by topic:

Go to “Settings” → “Categories”
Click “Add Category”
Enter category name and description
Optionally set category color
Click “Create”
Assign bookmarks to category when saving

Adding Bookmarks

Save bookmarks in multiple ways:

Using Browser Extension

Install Briefkasten browser extension
Click extension icon on any webpage
Edit title and description (pre-filled)
Select category and tags
Click “Save Bookmark”
Bookmark instantly added to vault

Using Drag and Drop

On Briefkasten dashboard, open a new tab
Keep Briefkasten window visible
Drag URL from address bar onto Briefkasten
Bookmark created with auto-extracted title

Using REST API

curl -X POST https://bookmarks.yourdomain.com/api/bookmarks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "url": "https://example.com/article",
    "title": "Example Article",
    "description": "A great article about...",
    "tags": ["article", "important"],
    "category": "Reading List"
  }'

Manual Addition

Click “Add Bookmark” in dashboard
Paste URL
Edit auto-extracted title and description
Select category
Add tags
Click “Save”

Managing Tags

Organize bookmarks with flexible tagging:

In bookmark details, click “Add Tag”
Type tag name
Select from existing tags or create new
Add multiple tags per bookmark
Filter bookmarks by tag in browse view
View tag cloud for popular tags

Searching Bookmarks

Find bookmarks quickly:

Use search box at top
Search by title, description, or URL
Fulltext search across all content
Filter by category
Filter by tags
Combine filters for precise results
Save searches as collections (optional)

Creating Collections

Group related bookmarks:

Go to “Collections”
Click “Create Collection”
Name your collection
Add description
Add bookmarks from browse view
Or drag bookmarks to collection
Share collection if desired (optional)

Import Bookmarks

Import from other services:

Go to “Settings” → “Import”
Export bookmarks from another service as HTML
Select HTML file
Choose how to organize imported bookmarks
Map categories if needed
Click “Import”
Wait for import to complete
Verify imported bookmarks

Export Bookmarks

Back up or migrate your bookmarks:

Go to “Settings” → “Export”
Choose export format:
- HTML (standard bookmark format)
- JSON (complete data export)
- CSV (spreadsheet format)
Select bookmarks to export or export all
Click “Export”
Download exported file
Keep backup in secure location

Viewing Bookmark Details

Access full bookmark information:

Click bookmark in list
View full title and description
See assigned category and tags
View bookmark image (if available)
Click URL to visit original page
Edit bookmark details
Delete bookmark if needed

Managing Multiple Views

Browse bookmarks different ways:

Grid View: Visual cards with images
List View: Compact list format
Table View: Detailed columns
Calendar View: Bookmarks by date
Switch between views for different tasks
Customize columns in table view
Save view preferences

Environment Variable Examples

Basic Configuration

DATABASE_URL=postgresql://briefkasten:password@postgres.internal:5432/briefkasten
NEXTAUTH_URL=https://bookmarks.yourdomain.com
NEXTAUTH_SECRET=your-secret-key-32-characters
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://bookmarks.yourdomain.com

Complete Production Configuration

# Application Settings
APP_NAME=Briefkasten
APP_DESCRIPTION=Self-hosted bookmarking application
NODE_ENV=production

# Database Configuration
DATABASE_URL=postgresql://briefkasten:very_secure_password@postgres.internal:5432/briefkasten
SHADOW_DATABASE_URL=postgresql://briefkasten:very_secure_password@postgres.internal:5433/briefkasten_shadow

# Authentication
NEXTAUTH_URL=https://bookmarks.yourdomain.com
NEXTAUTH_SECRET=your-secret-key-32-characters-long

# Application URLs
NEXT_PUBLIC_APP_URL=https://bookmarks.yourdomain.com
NEXTAUTH_URL_INTERNAL=http://localhost:3000

# OAuth Providers - Google
GOOGLE_ID=your-google-oauth-client-id.apps.googleusercontent.com
GOOGLE_SECRET=your-google-oauth-secret

# OAuth Providers - GitHub
GITHUB_ID=your-github-oauth-app-id
GITHUB_SECRET=your-github-oauth-app-secret

# OAuth Providers - Discord (optional)
DISCORD_ID=your-discord-app-id
DISCORD_SECRET=your-discord-app-secret

# Image Storage - Supabase (optional)
SUPABASE_ANON_KEY=your-supabase-anonymous-key
SUPABASE_BUCKET_URL=https://your-project.supabase.co/storage/v1/object/public/briefkasten

# Image Storage - Cloudinary (optional)
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key

# SMTP Configuration for Email (optional)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# Analytics (optional)
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_ENVIRONMENT=production

# Performance and Logging
LOG_LEVEL=info
DEBUG=false

Sample Code and Getting Started

TypeScript - Bookmark Management Integration

// Briefkasten Bookmark Management

import axios, { AxiosInstance } from 'axios';

interface Bookmark {
  id: string;
  url: string;
  title: string;
  description?: string;
  tags?: string[];
  category?: string;
  image?: string;
  createdAt: Date;
  updatedAt: Date;
}

interface CreateBookmarkRequest {
  url: string;
  title: string;
  description?: string;
  tags?: string[];
  category?: string;
}

interface BookmarkFilters {
  search?: string;
  category?: string;
  tags?: string[];
  limit?: number;
  offset?: number;
}

class BriefkastenClient {
  private client: AxiosInstance;
  private apiUrl: string;
  private apiToken: string;

  constructor(apiUrl: string, apiToken: string) {
    this.apiUrl = apiUrl;
    this.apiToken = apiToken;

    this.client = axios.create({
      baseURL: apiUrl,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiToken}`
      }
    });
  }

  async createBookmark(data: CreateBookmarkRequest): Promise<Bookmark> {
    try {
      const response = await this.client.post('/api/bookmarks', data);
      return response.data;
    } catch (error) {
      console.error('Error creating bookmark:', error);
      throw error;
    }
  }

  async getBookmarks(filters?: BookmarkFilters): Promise<Bookmark[]> {
    try {
      const params = {
        ...(filters?.search && { search: filters.search }),
        ...(filters?.category && { category: filters.category }),
        ...(filters?.tags && { tags: filters.tags.join(',') }),
        limit: filters?.limit || 50,
        offset: filters?.offset || 0
      };

      const response = await this.client.get('/api/bookmarks', { params });
      return response.data.bookmarks;
    } catch (error) {
      console.error('Error fetching bookmarks:', error);
      throw error;
    }
  }

  async getBookmark(id: string): Promise<Bookmark> {
    try {
      const response = await this.client.get(`/api/bookmarks/${id}`);
      return response.data;
    } catch (error) {
      console.error('Error fetching bookmark:', error);
      throw error;
    }
  }

  async updateBookmark(id: string, data: Partial<Bookmark>): Promise<Bookmark> {
    try {
      const response = await this.client.put(`/api/bookmarks/${id}`, data);
      return response.data;
    } catch (error) {
      console.error('Error updating bookmark:', error);
      throw error;
    }
  }

  async deleteBookmark(id: string): Promise<void> {
    try {
      await this.client.delete(`/api/bookmarks/${id}`);
    } catch (error) {
      console.error('Error deleting bookmark:', error);
      throw error;
    }
  }

  async searchBookmarks(query: string): Promise<Bookmark[]> {
    try {
      const response = await this.client.get('/api/bookmarks/search', {
        params: { q: query }
      });
      return response.data.results;
    } catch (error) {
      console.error('Error searching bookmarks:', error);
      throw error;
    }
  }

  async getCategories(): Promise<string[]> {
    try {
      const response = await this.client.get('/api/categories');
      return response.data.categories;
    } catch (error) {
      console.error('Error fetching categories:', error);
      throw error;
    }
  }

  async getTags(): Promise<string[]> {
    try {
      const response = await this.client.get('/api/tags');
      return response.data.tags;
    } catch (error) {
      console.error('Error fetching tags:', error);
      throw error;
    }
  }

  async addCategory(name: string, description?: string): Promise<string> {
    try {
      const response = await this.client.post('/api/categories', {
        name,
        ...(description && { description })
      });
      return response.data.id;
    } catch (error) {
      console.error('Error adding category:', error);
      throw error;
    }
  }

  async exportBookmarks(format: 'html' | 'json' | 'csv'): Promise<Blob> {
    try {
      const response = await this.client.get('/api/bookmarks/export', {
        params: { format },
        responseType: 'blob'
      });
      return response.data;
    } catch (error) {
      console.error('Error exporting bookmarks:', error);
      throw error;
    }
  }

  async importBookmarks(file: File): Promise<{ imported: number }> {
    try {
      const formData = new FormData();
      formData.append('file', file);

      const response = await this.client.post('/api/bookmarks/import', formData, {
        headers: {
          'Content-Type': 'multipart/form-data'
        }
      });
      return response.data;
    } catch (error) {
      console.error('Error importing bookmarks:', error);
      throw error;
    }
  }
}

// Usage example
const client = new BriefkastenClient(
  'https://bookmarks.yourdomain.com',
  'your-api-token'
);

// Create a bookmark
const newBookmark = await client.createBookmark({
  url: 'https://example.com/article',
  title: 'Great Article',
  description: 'An informative article',
  tags: ['article', 'read'],
  category: 'Learning'
});

// Search bookmarks
const results = await client.searchBookmarks('javascript');

// Get bookmarks with filters
const filtered = await client.getBookmarks({
  category: 'Learning',
  tags: ['javascript'],
  limit: 20
});

// Export bookmarks
const htmlExport = await client.exportBookmarks('html');

Bash - Bookmark Backup and Management Script

#!/bin/bash

# Briefkasten Backup and Maintenance Script
BACKUP_DIR="/backups/briefkasten"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=30

# Configuration
BRIEFKASTEN_URL="https://bookmarks.yourdomain.com"
API_TOKEN="your-api-token"

# Create backup directory
mkdir -p $BACKUP_DIR

echo "Starting Briefkasten backup..."

# Export bookmarks as JSON
echo "Exporting bookmarks..."
curl -s -X GET "$BRIEFKASTEN_URL/api/bookmarks/export?format=json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -o "$BACKUP_DIR/bookmarks_json_$TIMESTAMP.json"

# Export bookmarks as HTML
echo "Exporting bookmarks as HTML..."
curl -s -X GET "$BRIEFKASTEN_URL/api/bookmarks/export?format=html" \
  -H "Authorization: Bearer $API_TOKEN" \
  -o "$BACKUP_DIR/bookmarks_html_$TIMESTAMP.html"

# Export bookmarks as CSV
echo "Exporting bookmarks as CSV..."
curl -s -X GET "$BRIEFKASTEN_URL/api/bookmarks/export?format=csv" \
  -H "Authorization: Bearer $API_TOKEN" \
  -o "$BACKUP_DIR/bookmarks_csv_$TIMESTAMP.csv"

# Backup persistent data
echo "Backing up persistent data..."
tar -czf "$BACKUP_DIR/briefkasten_data_$TIMESTAMP.tar.gz" \
  /app/data 2>/dev/null || true

# Backup logs
echo "Backing up logs..."
tar -czf "$BACKUP_DIR/briefkasten_logs_$TIMESTAMP.tar.gz" \
  /app/logs 2>/dev/null || true

# Cleanup old backups
echo "Cleaning up old backups..."
find $BACKUP_DIR -type f -mtime +$RETENTION_DAYS -delete

# Verify backups
echo "Verifying backups..."
for file in $BACKUP_DIR/*_$TIMESTAMP.*; do
  if [ -f "$file" ]; then
    size=$(du -h "$file" | awk '{print $1}')
    echo "✓ Created: $(basename $file) ($size)"
  fi
done

# Calculate total backup size
TOTAL_SIZE=$(du -sh $BACKUP_DIR | awk '{print $1}')

echo ""
echo "Backup completed at: $TIMESTAMP"
echo "Total backup size: $TOTAL_SIZE"
echo "Backup location: $BACKUP_DIR"

# Optional: Upload to cloud storage
# aws s3 sync $BACKUP_DIR s3://your-bucket/briefkasten-backups/ \
#   --exclude "*" --include "bookmarks_*_$TIMESTAMP.*" \
#   --delete

# Optional: Send backup notification
# curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
#   -d "{\"text\":\"Briefkasten backup completed: $(du -sh $BACKUP_DIR | awk '{print $1}')\"}"

cURL - API Integration Examples

# Briefkasten API Examples

# Get all bookmarks
curl -X GET https://bookmarks.yourdomain.com/api/bookmarks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get bookmarks with search
curl -X GET "https://bookmarks.yourdomain.com/api/bookmarks?search=javascript&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get bookmarks by category
curl -X GET "https://bookmarks.yourdomain.com/api/bookmarks?category=Learning" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get bookmarks by tag
curl -X GET "https://bookmarks.yourdomain.com/api/bookmarks?tags=important,read" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Create a bookmark
curl -X POST https://bookmarks.yourdomain.com/api/bookmarks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "url": "https://example.com/article",
    "title": "Example Article",
    "description": "A useful article about web development",
    "tags": ["article", "webdev"],
    "category": "Learning"
  }'

# Get specific bookmark
curl -X GET https://bookmarks.yourdomain.com/api/bookmarks/bookmark-id \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Update bookmark
curl -X PUT https://bookmarks.yourdomain.com/api/bookmarks/bookmark-id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "title": "Updated Title",
    "description": "Updated description",
    "tags": ["updated", "important"]
  }'

# Delete bookmark
curl -X DELETE https://bookmarks.yourdomain.com/api/bookmarks/bookmark-id \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Search bookmarks
curl -X GET "https://bookmarks.yourdomain.com/api/bookmarks/search?q=react" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get all categories
curl -X GET https://bookmarks.yourdomain.com/api/categories \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get all tags
curl -X GET https://bookmarks.yourdomain.com/api/tags \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Export bookmarks as JSON
curl -X GET "https://bookmarks.yourdomain.com/api/bookmarks/export?format=json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o bookmarks.json

# Export bookmarks as HTML
curl -X GET "https://bookmarks.yourdomain.com/api/bookmarks/export?format=html" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o bookmarks.html

Bookmark Management Best Practices

Organization Strategy

Develop an effective bookmarking system:

Create Logical Categories: Use broad categories for main topics
Use Consistent Tags: Establish tag naming conventions
Regular Cleanup: Remove outdated bookmarks periodically
Description Notes: Add context when saving technical resources
Collection Groups: Use collections for project-related bookmarks
Archive Old Bookmarks: Move old bookmarks to archive collection
Consistent Naming: Use clear, descriptive bookmark titles

Workflow Tips

Optimize your bookmark workflow:

Keyboard Shortcuts: Learn keyboard shortcuts for quick saving
Browser Extension: Always use extension for fastest saving
Batch Operations: Update multiple bookmarks at once when needed
Regular Exports: Export bookmarks monthly as backup
Share Collections: Share relevant collections with team members
Review Bookmarks: Regularly review and organize new bookmarks
Use Search: Leverage fulltext search for discovering old bookmarks

Privacy and Security

Maintain bookmark vault security:

Strong Passwords: Use strong passwords for admin account
OAuth Security: Use trusted OAuth providers
Regular Backups: Export bookmarks regularly
Database Encryption: Enable encryption at database level
HTTPS Only: Always use HTTPS for accessing Briefkasten
Access Control: Limit who can access your bookmark vault
Audit Logs: Review access logs regularly

Troubleshooting

Common Issues and Solutions

Issue: Cannot access Briefkasten application

Solutions:

Verify Klutch.sh app is running
Check domain DNS resolution
Verify SSL certificate validity
Check network connectivity
Review Klutch.sh dashboard for errors

Issue: Database connection failed

Troubleshooting:

Verify database credentials are correct
Ensure database is accessible
Check DATABASE_URL environment variable
Verify database exists
Check firewall rules

Issue: OAuth login not working

Solutions:

Verify OAuth provider credentials
Check NEXTAUTH_URL matches domain
Verify redirect URI in OAuth provider settings
Check NEXTAUTH_SECRET is set
Review NextAuth logs

Issue: Bookmarks not saving

Troubleshooting:

Verify database connection
Check disk space on persistent volume
Review application logs
Try clearing browser cache
Test with manual bookmark addition

Issue: Slow performance or high memory usage

Solutions:

Increase persistent volume size
Check for database query performance
Optimize bookmark count
Review browser extension usage
Monitor server resources

Updating Briefkasten

To update Briefkasten to a newer version:

Backup your database and bookmarks
Update Dockerfile to latest version
Commit and push to GitHub
Klutch.sh will automatically rebuild
Test bookmark access after update
Verify all bookmarks still accessible
Monitor logs for any issues

Use Cases

Personal Knowledge Management

Organize research and articles
Save documentation links
Maintain learning resources
Archive useful references

Team Collaboration

Share bookmark collections
Organize team resources
Collaborate on research
Maintain shared knowledge base

Content Curation

Save articles to review
Organize by topic or project
Export collections for reports
Share curated content

Project Management

Link to relevant documentation
Organize project resources
Track useful references
Maintain project history

Browser Extension Guide

Installing the Extension

Visit Chrome Extension Store
Click “Add to Chrome”
Confirm permissions
Extension icon appears in toolbar
Configure extension settings
Enter Briefkasten URL
Test with a bookmark

Using the Extension

Click extension icon on any webpage
Pre-filled title and description appear
Edit if necessary
Select category from dropdown
Add tags if desired
Click “Save Bookmark”
Confirmation appears
View saved bookmarks in Briefkasten

Extension Settings

Click extension icon
Select “Options”
Configure Briefkasten server URL
Set default category
Enable/disable auto-detect
Configure keyboard shortcuts
Save settings

Additional Resources

Briefkasten GitHub Repository - Source code and releases
Briefkasten Official Documentation - Comprehensive guides
Briefkasten Demo Instance - Try before self-hosting
Briefkasten Community Discussions - Support and community
Briefkasten Browser Extension - Source code
Klutch.sh Getting Started Guide
Klutch.sh Volumes Documentation
Klutch.sh Custom Domains Guide

Conclusion

Deploying Briefkasten on Klutch.sh provides you with a powerful, self-hosted bookmarking application that helps you save, organize, and discover your web bookmarks with complete data ownership and privacy. With automatic metadata extraction, browser extension integration, powerful search capabilities, flexible organization with categories and tags, and support for multiple authentication methods, Briefkasten enables you to build a comprehensive personal knowledge management system. Klutch.sh’s managed infrastructure ensures your bookmark vault is always available, secure, and performant, allowing you to focus on curating and organizing your bookmarks.

Start managing your bookmarks today by deploying Briefkasten on Klutch.sh and experience the freedom of self-hosted bookmark management.

Deploying Briefkasten

Why Briefkasten?

Prerequisites

Important Considerations

Deploying Briefkasten

Create a New Project

Prepare Your Repository

Create a New App

Configure Environment Variables

Configure Persistent Storage

Set Network Configuration

Configure Custom Domain

Deploy Your App

Initial Setup and Configuration

Accessing Briefkasten

Choosing Authentication Method

OAuth Authentication

Email Magic Link

Dashboard Overview

Creating Categories

Adding Bookmarks

Using Browser Extension

Using Drag and Drop

Using REST API

Manual Addition

Managing Tags

Searching Bookmarks

Creating Collections

Import Bookmarks

Export Bookmarks

Viewing Bookmark Details

Managing Multiple Views

Environment Variable Examples

Basic Configuration

Complete Production Configuration

Sample Code and Getting Started

TypeScript - Bookmark Management Integration

Bash - Bookmark Backup and Management Script

cURL - API Integration Examples

Bookmark Management Best Practices

Organization Strategy

Workflow Tips

Privacy and Security

Troubleshooting

Common Issues and Solutions

Updating Briefkasten

Use Cases

Personal Knowledge Management

Team Collaboration

Content Curation

Project Management

Browser Extension Guide

Installing the Extension

Using the Extension

Extension Settings

Additional Resources

Conclusion