Shaarli

Shaarli is a single‑user, database‑free bookmark manager written in PHP that runs on any LAMP stack or containerised environment. From a developer’s point of view, it is essentially a stateless web application that persists all data in the file system as JSON or XML, eliminating the need for a dedicated database server. This design choice makes it trivial to deploy on minimal hosts, CI pipelines, or Docker images while still providing a rich REST API and extensible plugin system.

Architecture

Shaarli is built on top of the Slim 4 micro‑framework, which supplies a lightweight routing layer and middleware support. The core logic is encapsulated in a set of PHP classes that handle CRUD operations, authentication (basic auth or cookie‑based sessions), and rendering via Twig templates. Data storage is handled by a simple FileStore component that serialises bookmarks to disk; the JSON format is human‑readable and versioned, allowing developers to script migrations or backups. The application also bundles a built‑in Sphinx‑style search engine that indexes titles, URLs, and tags in memory for fast lookup.

Core Capabilities

• RESTful API: Exposes endpoints (/api/shaarli) for creating, reading, updating, and deleting bookmarks. Authentication can be token‑based, making it easy to integrate with external services or CI scripts.
• Webhooks & RSS: Developers can subscribe to bookmark events via webhooks or consume the RSS feed for automated workflows.
• Tagging & Hashtags: Full support for both explicit tags and inline hashtags (#example), enabling flexible categorisation.
• Customizable UI: The Twig templates are fully overridable; CSS and JavaScript assets can be swapped out or extended with custom plugins.
• Authentication Plugins: Beyond the default cookie auth, Shaarli offers OAuth2 and LDAP plugins for environments that require enterprise single‑sign‑on.

Deployment & Infrastructure

Shaarli’s minimal footprint (≈ 5 MB of PHP code and assets) makes it ideal for Docker deployments. The official shaarli/shaarli image pulls the latest release and exposes a single container port. Because it writes to the local file system, mounting a persistent volume is sufficient for data durability. The application scales horizontally by running multiple container instances behind a load balancer; however, since it is single‑user, typical use cases involve a single instance per developer or team.

Integration & Extensibility

The plugin architecture is inspired by WordPress: plugins are PHP classes that hook into predefined events (onInit, onRender, etc.). This allows developers to add features such as custom authentication backends, third‑party analytics, or even embed Shaarli into larger PHP applications. The REST API can be consumed by mobile apps, browser extensions, or automation scripts (e.g., a CI job that posts release notes as bookmarks).

Developer Experience

Documentation is hosted on ReadTheDocs and covers installation, API usage, and plugin development. The community actively maintains the project on GitHub, with a clear issue tracker and a Gitter channel for real‑time support. Licensing is GPLv3, ensuring that any derivative work remains free and open source. The codebase follows PSR‑12 standards, making it comfortable for developers familiar with modern PHP practices.

Use Cases

• Personal Knowledge Base: A developer can host Shaarli on a Raspberry Pi to keep a searchable archive of useful links, code snippets, and tutorials.
• Team Knowledge Sharing: In a small team setting, each member runs their own instance; shared bookmarks can be exported/imported via the API.
• CI/CD Integration: Automated scripts can push release notes, documentation links, or build artifacts as bookmarks, which are then instantly searchable.
• Minimalist Web Service: Companies needing a lightweight link‑sharing tool for internal use can deploy Shaarli behind an Nginx reverse proxy without the overhead of a full CMS.

Advantages

Shaarli’s database‑free model removes operational complexity, while its PHP foundation ensures compatibility with virtually any hosting provider. The REST API and plugin system give developers the flexibility to integrate or extend functionality without touching core code. Its small attack surface, combined with a permissive license, makes it an attractive choice for privacy‑conscious developers who want a fast, self‑hosted bookmarking solution.