Grimoire

Grimoire is a lightweight, self‑hosted bookmark and link sharing platform written in Rust with a modern frontend powered by SvelteKit. The core of the application is a single binary that serves both API endpoints and static assets, making it trivial to deploy via Docker or directly on a Linux host. The backend uses the sqlx crate for asynchronous database access and ships with support for SQLite, PostgreSQL and MySQL, giving developers the flexibility to choose a lightweight embedded store for small deployments or a robust relational database for larger teams.

Architecture

• Backend: Actix‑web based RESTful API, written in Rust. It handles user authentication (JWT), bookmark CRUD, metadata extraction, and fuzzy search via the meilisearch crate. The API is versioned and documented with OpenAPI, enabling automated client generation.
• Frontend: SvelteKit SPA consuming the API. It implements dark‑mode, tag/category filtering, and a browser extension companion for instant bookmark capture.
• Data Layer: Configurable through environment variables. The migration tool introduced in v0.4 allows zero‑downtime schema evolution and data format changes.
• Containerization: A single Dockerfile builds the binary and serves static assets. Docker Compose examples are provided, but the image can run directly with a --env-file for production.

Core Capabilities

• Bookmark CRUD: Full REST endpoints (/api/bookmarks) with pagination, filtering by tags/categories, and support for notes.
• Metadata Extraction: A background worker fetches title, description, image and main content from URLs using reqwest + scraper. Extracted data is cached locally and refreshed on demand.
• Search: Powered by meilisearch, enabling fuzzy search across titles, URLs, tags, and notes.
• User Management: JWT‑based auth with role support; admins can manage users, view analytics, and trigger migrations.
• API Extension: Webhooks for external services (e.g., Slack, email) and a public integration endpoint (/api/integrations) for adding bookmarks programmatically.

Deployment & Infrastructure

Grimoire is designed to run in a container‑native environment. A single container exposes the web interface and API on configurable ports. The data directory is persisted via a Docker volume (grimoire_data), ensuring bookmarks survive restarts. For high‑availability, the stateless binary can be scaled behind a load balancer; the database layer must remain consistent (PostgreSQL is recommended for multi‑node deployments). The application monitors health through a simple HTTP endpoint and can be orchestrated with Kubernetes using the provided helm chart (available in the repo).

Integration & Extensibility

• Plugins: The architecture exposes a hook system; developers can write Rust modules that register new API routes or background jobs, compiled into the binary.
• Webhooks: Out‑of‑the‑box support for triggering external services on bookmark events.
• Browser Extension: The companion extension communicates with the API over HTTPS, allowing instant capture of the current tab. This can be customized by embedding your own UI components via SvelteKit.
• Customization: Themes, color schemes and layout can be tweaked by editing the Svelte components; no recompilation is needed for simple CSS overrides.

Developer Experience

The project follows idiomatic Rust conventions, with a comprehensive Cargo.toml and unit tests covering core logic. Documentation is hosted under /docs, detailing the migration tool, API usage and deployment guides. Community support is active on GitHub Discussions; contributors are encouraged to submit PRs for new database backends or feature requests. The open‑source license (MIT) removes any vendor lock‑in, allowing full control over the codebase.

Use Cases

• Personal Knowledge Base: A solo developer can run Grimoire locally to collect research links, notes and code snippets.
• Team Bookmarking: Small teams can share a PostgreSQL instance, leveraging role‑based access to maintain shared resources.
• Educational Platforms: Instructors can provide students with a self‑hosted bookmark hub for course materials, integrating with LMS via webhooks.
• API Integration: Service providers can embed Grimoire’s API into their own tooling, creating custom bookmark dashboards or analytics.

Advantages

Grimoire offers a high‑performance Rust backend with minimal runtime overhead, making it suitable for low‑resource environments. Its modular architecture allows developers to swap out storage engines or extend functionality without touching the core. The inclusion of a built‑in migration tool reduces operational friction when upgrading, while the open‑source license ensures total freedom to modify or redistribute. Compared to cloud‑based bookmark services, Grimoire gives developers full control over data privacy, compliance and customization—all within a single, easy‑to‑deploy container.