Shiori

Shiori is a lightweight, self‑hosted bookmark manager built entirely in Go. It exposes both a RESTful API and an interactive web UI, making it suitable for integration into existing developer workflows or as a standalone service. The core idea is to provide an offline‑first, searchable collection of URLs with minimal operational overhead.

Key Features

• Cross‑platform binary – compiled to a single executable, eliminating runtime dependencies.
• Multiple storage backends – supports SQLite3 for local development and PostgreSQL, MariaDB, or MySQL for production workloads.
• Content extraction – automatically parses the readable text from a URL and stores an offline archive, enabling fast retrieval without external network calls.
• Import/export – seamless migration via Netscape bookmark XML and Pocket’s JSON format.
• CLI + Web UI – developers can script operations or use the browser‑based interface, both powered by the same codebase.

Technical Stack

Shiori’s codebase is intentionally small; the core logic resides in cmd/shiori/main.go, with the API handlers and UI routes split into dedicated packages. This structure allows developers to fork, modify, or extend functionality without wrestling with a monolithic framework.

Core Capabilities & APIs

• REST endpoints (/api/v1/bookmarks) expose CRUD operations, search, and bulk import/export.
• Webhooks – optional event hooks that fire on bookmark creation or deletion, enabling external services (e.g., CI pipelines) to react.
• Web Extension – a companion Firefox/Chrome extension forwards URLs directly to the Shiori API, allowing quick bookmarking from any site.
• CLI Commands – shiori add, shiori list, shiori delete provide a programmatic interface for scripts and CI jobs.

The API follows conventional REST patterns, returning JSON payloads with HTTP status codes that developers can consume in any language. Authentication is optional; when enabled, it uses token‑based headers (Authorization: Bearer <token>).

Deployment & Infrastructure

• Containerization – official Docker images are published on GitHub Packages, simplifying CI/CD pipelines. A single docker run command can spin up a PostgreSQL instance and Shiori, with environment variables for DB credentials.
• Scalability – because the application is stateless, horizontal scaling is trivial. Multiple instances can share a common database; load balancing can be achieved with any reverse proxy (NGINX, Traefik).
• Resource Footprint – the binary is under 10 MB (compressed), and SQLite mode runs with <5 MiB RAM, making it ideal for Raspberry Pi or edge devices.
• Self‑hosting – no external services required. The only prerequisites are a Go runtime for building or Docker for running containers, and the chosen database engine.

Integration & Extensibility

• Plugin hooks – developers can register custom handlers in the plugins package; for example, a plugin that enriches bookmarks with OpenGraph metadata.
• Webhooks – external services can subscribe to bookmark events via HTTP callbacks, facilitating automation (e.g., pushing new bookmarks to a Slack channel).
• API Client Libraries – while not bundled, the straightforward REST interface makes it easy to generate clients in TypeScript (openapi-generator), Python (httpx), or Go (net/http).
• Custom UI – the templating system is minimal; swapping to a SPA framework or serving the API behind a custom frontend poses no architectural friction.

Developer Experience

• Documentation – comprehensive guides reside in the docs/ folder, including architecture diagrams, migration steps, and API reference. The docs are written in Markdown, making them easy to read on GitHub or generate into a static site.
• Community & Support – active issue tracker, Matrix channel for real‑time help, and a pull‑request friendly workflow encourage contributions.
• Licensing – MIT license allows unrestricted modification and redistribution, which is attractive for enterprise use or internal tooling.

Use Cases

Advantages Over Alternatives

• Zero‑runtime overhead – a single static binary eliminates dependency hell.
• Offline-first design – automatic archiving removes the need for external caching services.
• Lightweight database support – SQLite suffices for most use cases; full‑featured SQL engines available when scaling.
• Open source & permissive license – no licensing constraints, unlike