Deploying Grimoire

Introduction

Grimoire is a modern, self-hosted bookmark manager that transforms how you save and organize web content. With its sleek user interface, automatic metadata extraction, and powerful organization features, Grimoire makes it easy to build a personal knowledge library from your web discoveries.

Built with SvelteKit and featuring a fully documented REST API, Grimoire offers a unique combination of simplicity and power. The platform includes innovative features like “Flows” - session-like bookmark collections for research and learning - along with traditional organization via tags and groups.

Key highlights of Grimoire:

• Beautiful Interface: Modern, responsive design that works on any device
• Automatic Extraction: Automatically fetches titles, descriptions, and images
• Tags and Groups: Organize bookmarks with flexible categorization
• Flows: Session-based bookmark collections for research and learning
• Multi-User Support: Share your instance with family or team members
• Two-Factor Authentication: Secure accounts with TOTP-based 2FA
• Browser Extensions: Quick saving from Firefox and Chrome
• REST API: Full API for automation and integrations
• Import/Export: Import from browsers and other bookmark managers
• 100% Open Source: Licensed under MIT

This guide walks through deploying Grimoire on Klutch.sh using Docker, configuring your bookmark library, and organizing your web discoveries.

Why Deploy Grimoire on Klutch.sh

Deploying Grimoire on Klutch.sh provides several advantages for bookmark management:

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

Persistent Storage: Attach persistent volumes for your database and bookmark data. Your library survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your bookmarks.

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

Scalable Resources: Allocate CPU and memory based on your library size.

Custom Domains: Assign a custom domain for your bookmark manager.

Always-On Availability: Your bookmark library remains accessible 24/7 from any device.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Grimoire configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) Browser extension installation access

Understanding Grimoire Architecture

Grimoire is built with modern web technologies:

SvelteKit Frontend: Fast, reactive user interface with server-side rendering.

SQLite Database: Lightweight database storing bookmarks, users, and metadata.

Metadata Extractor: Automatically fetches page information when bookmarks are added.

REST API: Full API for programmatic access and browser extensions.

Image Cache: Stores favicon and preview images locally.

Preparing Your Repository

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

Repository Structure

grimoire-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM goniszewski/grimoire:latest

# Set environment variables
ENV ORIGIN=${ORIGIN}
ENV PUBLIC_HTTPS_ONLY=${PUBLIC_HTTPS_ONLY:-true}
ENV PUBLIC_SIGNUP_DISABLED=${PUBLIC_SIGNUP_DISABLED:-false}

# Create data directory
RUN mkdir -p /app/data

# Expose the web interface port
EXPOSE 5173

# The base image includes the default entrypoint

Advanced Dockerfile

For more configuration:

FROM goniszewski/grimoire:latest

# Application URL (required)
ENV ORIGIN=${ORIGIN}

# Security settings
ENV PUBLIC_HTTPS_ONLY=${PUBLIC_HTTPS_ONLY:-true}
ENV PUBLIC_SIGNUP_DISABLED=${PUBLIC_SIGNUP_DISABLED:-false}

# Database location
ENV DATABASE_URL=file:/app/data/grimoire.db

# Create data directory
RUN mkdir -p /app/data

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:5173/ || exit 1

EXPOSE 5173

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
ORIGIN	Yes	-	Full URL of your instance (e.g., https://bookmarks.example.com)
PUBLIC_HTTPS_ONLY	No	true	Require HTTPS connections
PUBLIC_SIGNUP_DISABLED	No	false	Disable new user registration
DATABASE_URL	No	file:./data/grimoire.db	SQLite database path

Deploying Grimoire on Klutch.sh

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

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Grimoire deployment configuration"
git remote add origin https://github.com/yourusername/grimoire-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 “grimoire” 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 Grimoire Dockerfile.

Configure HTTP Traffic

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

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
ORIGIN	https://your-app-name.klutch.sh
PUBLIC_HTTPS_ONLY	true
PUBLIC_SIGNUP_DISABLED	false (set to true after creating your account)

Attach Persistent Volumes

Persistent storage is essential for Grimoire. Add the following volume:

Mount Path	Recommended Size	Purpose
/app/data	5 GB	SQLite database and cached images

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Grimoire container
• Provision an HTTPS certificate

Create Your Account

After deployment, access your Grimoire instance and create your user account:

1. Navigate to https://your-app-name.klutch.sh
2. Click Sign Up
3. Create your account with email and password
4. (Optional) Disable signups after creating your account

Access Grimoire

Once your account is created, log in and start adding bookmarks.

Using Grimoire

Adding Bookmarks

Add bookmarks through multiple methods:

Manual Entry:

1. Click the Add Bookmark button
2. Enter or paste the URL
3. Grimoire automatically fetches the title, description, and image
4. Add tags and select a group
5. Click Save

Browser Extension:

1. Install the extension from the Firefox Add-ons or Chrome Web Store
2. Configure it with your Grimoire URL
3. Click the extension icon on any page to save

REST API:

curl -X POST "https://your-app-name.klutch.sh/api/bookmarks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "url": "https://example.com",
    "tags": ["example", "test"]
  }'

Organizing with Tags

Create and apply tags to categorize bookmarks:

1. Add tags when creating bookmarks
2. Click on tags to filter your library
3. Manage tags from the Tags section
4. Combine multiple tags for precise filtering

Using Groups

Organize bookmarks into groups (like folders):

1. Create groups from the sidebar
2. Move bookmarks into groups
3. Nest groups for hierarchical organization
4. Use groups for broad categories (Work, Personal, Research)

Creating Flows

Flows are session-like bookmark collections for research:

1. Click Create Flow
2. Name your flow (e.g., “React Hooks Research”)
3. Add bookmarks to the flow as you research
4. Add notes to bookmarks within the flow
5. Review your research journey later

Flows are perfect for:

• Learning a new topic
• Research projects
• Planning trips
• Comparing products

Searching and Filtering

Find bookmarks quickly:

• Search: Full-text search across titles, descriptions, and URLs
• Tags: Click tags to filter
• Groups: Browse by group
• Unread: Find bookmarks you haven’t visited
• Favorites: Quick access to starred bookmarks

Browser Extensions

Installing the Extension

Firefox:

1. Visit the Firefox Add-ons page for Grimoire
2. Click Add to Firefox
3. Configure with your Grimoire URL and API token

Chrome:

1. Visit the Chrome Web Store page for Grimoire
2. Click Add to Chrome
3. Configure with your Grimoire URL and API token

Getting an API Token

1. Log in to Grimoire
2. Navigate to Settings > API
3. Generate a new API token
4. Copy the token to your extension settings

Using the Extension

1. Navigate to a page you want to save
2. Click the Grimoire extension icon
3. Edit tags and group if needed
4. Click Save

Multi-User Setup

Inviting Users

If signups are enabled:

1. Share your Grimoire URL with others
2. They can create their own accounts
3. Each user has a separate bookmark library

Disabling Signups

After creating necessary accounts:

1. Set PUBLIC_SIGNUP_DISABLED=true in environment variables
2. Redeploy the application
3. No new accounts can be created

User Management

Each user has:

• Separate bookmark library
• Personal tags and groups
• Individual settings and preferences
• Optional 2FA protection

Importing and Exporting

Importing Bookmarks

Import from various sources:

1. Go to Settings > Import
2. Select your source:
   • Browser export (HTML)
   • Other bookmark managers
   • JSON format
3. Upload your file
4. Review and confirm the import

Exporting Bookmarks

Back up or transfer your bookmarks:

1. Go to Settings > Export
2. Choose format (HTML or JSON)
3. Download your bookmarks

Security Best Practices

Account Security

• Strong Passwords: Use unique, strong passwords
• Two-Factor Authentication: Enable TOTP-based 2FA
• API Token Security: Treat API tokens like passwords

Instance Security

• HTTPS Only: Keep PUBLIC_HTTPS_ONLY=true
• Disable Signups: Disable after creating accounts
• Regular Backups: Back up the data directory

Troubleshooting Common Issues

Metadata Not Loading

Symptoms: Bookmark titles and images don’t auto-populate.

Solutions:

• Verify the URL is accessible
• Check if the site blocks bots
• Try saving manually and editing metadata
• Review application logs for errors

Extension Not Connecting

Symptoms: Browser extension can’t save bookmarks.

Solutions:

• Verify the Grimoire URL is correct (include https://)
• Check API token is valid
• Ensure CORS isn’t blocking requests
• Try regenerating the API token

Login Issues

Symptoms: Cannot log in to account.

Solutions:

• Verify credentials are correct
• Check ORIGIN matches your actual URL
• Clear browser cache and cookies
• Reset password if available

Additional Resources

• Official Grimoire Website
• Grimoire GitHub Repository
• Grimoire Wiki
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Grimoire on Klutch.sh gives you a beautiful, powerful bookmark manager with full control over your data. The combination of Grimoire’s modern interface and Klutch.sh’s deployment simplicity means you can organize your web discoveries without complex infrastructure.

With features like automatic metadata extraction, Flows for research sessions, and browser extensions for quick saving, Grimoire transforms bookmark management from a chore into a pleasure. Whether you’re curating resources for work, organizing personal interests, or building a knowledge library, Grimoire on Klutch.sh provides the foundation for managing your digital discoveries.