Shiori

Overview and Core Architecture

Shiori functions as a self-hosted bookmark manager built with the Go language and distributed as a single portable binary. Designed as an independent, privacy-conscious alternative to proprietary bookmark services, it enables individuals to catalog URLs, organize topics, and access reading material through both a web interface and a terminal CLI. Official design details and architecture principles are documented in the Shiori README and maintained on the GitHub repository.

The application supports multiple backend engines including sqlite3, PostgreSQL, MariaDB, and MySQL for bookmark metadata storage. Users can run lightweight embedded storage for personal instances or connect enterprise relational databases when scaling across multi-user environments. Full database capabilities and driver support are detailed in the Shiori README.

Shiori parses readable page content by default and creates an offline archive of saved web articles. When saving a URL, the internal parser extracts the core article text, strips extraneous scripts, and caches images locally, protecting reading lists against page drift and link rot as described in the Shiori README.

Users can import and export bookmark collections using standard Netscape Bookmark HTML formatting. This format ensures compatibility across major web browsers and third-party read-it-later utilities, facilitating data migration without vendor lock-in according to the Shiori README.

Installation and Binary Setup

Precompiled binary installations require placing the executable in the system PATH and updating shell profiles. Executable packages for various operating system architectures are distributed through GitHub Releases. For Linux and macOS environments, administrators append the binary path to their environment profile as detailed in the official Installation Guide:

Automated container builds can be pulled directly from the container registry for rapid containerized deployment. Containerized workflows simplify dependency isolation and lifecycle operations across container hosts according to the Installation Guide:

Users wishing to build custom images can utilize the repository Dockerfile directly. Custom container compilation allows integrating specialized database drivers or system-level customizations before deployment as documented in the Installation Guide:

Data Persistence and Container Execution

By default Shiori stores its database, thumbnails, and archives in the user data directory unless overridden with SHIORI_DIR. Overriding this environment variable allows operators to direct database files and cached assets to dedicated storage volumes, network shares, or backup mount points as described in the Usage Guide.

Persistent container execution binds the host working directory to preserve the internal database and archives across restarts. Exposing web port 8080 allows users to access the clean web dashboard while keeping sqlite files mounted safely on the host system according to the Usage Guide:

Executing commands inside a running container requires using the alpine-prefixed image variant. Operators managing users or executing CLI administrative commands within containerized environments can attach interactive shells directly as outlined in the Usage Guide:

Operators can cleanly terminate the running container instance whenever maintenance or system updates are required using standard container control commands documented in the Usage Guide:

Command-Line Search and Organization

The print command supports keyword searching across URLs, page titles, excerpts, and cached content via the search flag. Terminal users can query indexed content with precise terms, filter through assigned tags, and retrieve article IDs directly from the shell according to the Usage Guide.

Project Governance, Licensing, and Release History

Release v1.8.0 introduced tag API refactoring, improved SQLite performance, and proxy forward authentication headers. These improvements enhance system responsiveness on low-power hardware and enable integration behind reverse proxies with forward authentication as noted in the v1.8.0 Release Notes.

Shiori is distributed under the MIT license granting permission for unrestricted modification, distribution, and commercial use. This permissive licensing structure ensures that developers, system administrators, and teams can adopt, inspect, and customize the software freely as published in the official MIT License.