Espial

Espial is a self‑hosted, web‑based bookmarking service written in Haskell using the Yesod web framework. Its primary purpose is to provide a lightweight, single‑file deployment that stores all data in an embedded SQLite3 database. The design philosophy emphasizes minimal external dependencies, making it ideal for developers who need a quick, secure bookmarking backend without the overhead of a full‑blown relational database server. Espial exposes a RESTful API for CRUD operations on bookmarks, user accounts, and tags, while also offering a client‑side bookmarklet and an Android share intent for seamless data ingestion.

• Language & Framework: Haskell (GHC), Yesod, Persistent (ORM) for SQLite interaction.
• Database: SQLite3; migrations are managed via a standalone migration executable built with Stack.
• Frontend: PureScript (purs/ directory) for a type‑safe, functional UI that compiles to JavaScript. The compiled assets are bundled into the Yesod application.
• Deployment: A single static binary (espial) that can be run directly or containerized. Docker support is provided via an official Dockerfile and a separate repo (espial-docker) with best‑practice Compose files.

• Multi‑user support: Accounts are stored in the same SQLite file; authentication is handled by Yesod’s session middleware.
• Bookmark import/export: Scripts (importbookmarks, importfirefoxbookmarks) ingest JSON files in Pinboard or Firefox format, enabling bulk migration.
• Bookmarklet & Android integration: The bookmarklet injects a small script into any page, while the Android app forwards a Share intent to Espial’s API.
• Tagging & metadata: Each bookmark can carry arbitrary tags, a description, extended notes, and read‑status flags.
• API hooks: Customizable via environment variables (_env: syntax) in config/settings.yml, allowing integration with reverse proxies, OAuth providers, or custom middleware.

Espial’s single‑file binary removes the need for a separate database server, making it trivial to run on a Raspberry Pi, VPS, or within a Docker container. The application listens on a configurable port (default 3000) and expects TLS termination at the reverse proxy level. For scaling, multiple replicas can share a common SQLite file over NFS or use a lightweight PostgreSQL backend by swapping the Persistent backend, though this is not officially supported. The Docker image is built from scratch and exposes only the necessary ports, keeping the attack surface minimal.

While Espial’s core is intentionally lean, its Haskell codebase exposes several extension points:

• Yesod plugins: Developers can add middleware or route handlers by extending the Application module.
• Webhooks: By configuring environment variables, Espial can emit events (e.g., on bookmark creation) to external services.
• API clients: The documented JSON schema allows developers to build custom clients in any language; the PureScript front‑end serves as a reference implementation.
• Customization: The config/settings.yml file can be overridden by environment variables, enabling dynamic configuration without recompilation for most settings.

The project’s structure follows standard Yesod conventions, making it approachable for Haskell developers familiar with stack. Documentation is concise yet covers all critical paths—from migration scripts to environment variable overrides. Community support is modest but active; issues are triaged quickly, and the Docker repository offers ready‑to‑run examples. The lack of a separate database server reduces operational complexity, which is a significant advantage for developers looking to prototype or deploy personal bookmarking solutions.

• Personal Knowledge Management: A solo developer can run Espial on a home server to collect research links, with the bookmarklet for quick capture.
• Team Collaboration: Small teams can share a single Espial instance, using tags to organize resources per project.
• Developer Tooling: Integrate Espial’s API into CI pipelines or IDE extensions to programmatically add documentation links.
• Education: Instructors can host a shared bookmarking service for course materials, controlling access via user accounts.

Espial offers a compelling mix of performance, simplicity, and open‑source freedom. Its Haskell foundation ensures type safety across the stack, reducing runtime errors. The SQLite backend eliminates external dependencies, while Docker support guarantees consistent deployments. Compared to heavier bookmark managers (e.g., Pinboard, Raindrop), Espial’s licensing is permissive (MIT), and its minimal resource footprint makes it ideal for low‑power devices or self‑hosted environments where privacy and control are paramount.