DOCSEARCHbyAlgolia
Submit Docs

Shiori Bookmark Manager

repository·master·Indexed 11 days ago

https://github.com/go-shiori/shiori

A lightweight, portable, self-hosted bookmark manager written in Go. Shiori provides a CLI and Web interface, supports multiple database backends (sqlite3, PostgreSQL, MariaDB, and MySQL), and offers offline content archiving. It includes a REST API (with a modern API v1 based on Gin and OpenAPI/Swagger) and supports import/export via Netscape formats and Pocket.

Tokens
19.7K
Snippets
90
Records
113
Agent score
94%

What's inside Shiori

  1. Overview of Shiori features

    master

    Shiori is a bookmark management application written in Go, designed as a self-hosted alternative to Pocket. It can be operated via a command line interface (CLI) or a web application.

    Key capabilities include:

    • Bookmark Management: Add, edit, delete, and search for bookmarks.
    • Data Portability: Import and export bookmarks using the Netscape Bookmark file format, and import directly from Pocket.
    • Web Archiving: Supports offline webpage archiving.
    • Database Support: Compatible with SQLite, PostgreSQL, and MySQL.

  2. Overview of Shiori

    master
    Shiori is a bookmark management application written in Go, designed as a simple alternative to Pocket. It can be used as either a command-line interface (CLI) or a web application. The application is distributed as a single binary, making it highly portable and easy to install.

  3. Understand the API v1 development status

    master

    API v1 is a modern replacement for the current API, built using the Gin framework and following the OpenAPI/Swagger specification. It utilizes JWT for authentication and sessions.

    Warning: This API is still in development. While finished endpoints are intended to remain stable, breaking changes may occur before the official release. If you require a stable API for production use, use the current API instead.

  4. Key features of Shiori

    master

    Shiori provides several core functionalities for managing bookmarks:

    • Bookmark Management: Add, edit, delete, and search bookmarks.
    • Import/Export: Supports Netscape Bookmark file formats and direct imports from Pocket.
    • Interfaces: Offers both a clean CLI and a web-based user interface.
    • Database Support: Compatible with sqlite3, PostgreSQL, MariaDB, and MySQL.
    • Content Archiving: Automatically parses readable content to create offline archives of webpages where possible.
    • Web Extensions: [BETA] support available for Firefox and Chrome via the shiori-web-ext project.

  8. Configure Shiori behind a reverse proxy

    master

    If you are serving Shiori behind a reverse proxy (like Nginx) at a subpath, you must set the SHIORI_HTTP_ROOT_PATH environment variable to that path (e.g., /shiori/).

    Important: Setting this variable does not make Shiori automatically accessible at that path; your reverse proxy must be configured to strip the webroot path before forwarding the request to Shiori.

    Nginx Configuration Example

    When using Nginx, ensure you include a trailing slash in the proxy_pass directive to correctly strip the prefix.

    location /shiori/ {
    proxy_pass http://localhost:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

  9. Run Shiori as a background service on macOS

    master

    To run Shiori on startup on macOS, create a LaunchAgent .plist file in ~/Library/LaunchAgents/.

    1. Create a file (e.g., local.app.shiori.plist).
    2. Use the template below, replacing the placeholder paths and your SHIORI_HTTP_SECRET_KEY.
    3. After creating the file, go to System Settings > General > Login Items & Extensions > Allow in the background and ensure Shiori is enabled.

    To remove the service, simply delete the .plist file.

    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>local.app.shiori</string>
  <key>EnvironmentVariables</key>
  <dict>
      <key>SHIORI_HTTP_SECRET_KEY</key>
      <string>somerandomvalue123489</string>
  </dict>
  <key>ProgramArguments</key>
  <array>
    <string>/absolute/path/to/shiori/binary</string>
    <string>server</string>
    <string>--storage-directory</string>
    <string>/absolute/path/to/shiori/storage/directory</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>ServiceDescription</key>
  <string>Shiori Bookmarking Service</string>
</dict>
</plist>

  10. Run the Shiori server with Docker

    master

    You can run the development server using the provided docker-compose.yaml. This setup includes PostgreSQL and MariaDB and enables hot-reloading (the server restarts automatically on code changes).

    Run the following command:

    docker compose up shiori
    • Port: The server runs on port 8080.
    • Database: By default, it uses SQLite (mounting the local dev-data folder). To use MariaDB or PostgreSQL, uncomment the SHIORI_DATABASE_URL line in docker-compose.yaml for your preferred engine.

  11. Add URLs to Shiori from Android via Termux

    master

    You can automate adding URLs to Shiori from an Android device using Termux and a custom shell script in the ~/bin directory. This script authenticates via the Shiori API and posts the URL.

    Setup Steps:

    1. Install Termux.
    2. Create a script at ~/bin/termux-url-opener.
    3. Replace Shiori_URL, Username, and Password in the script with your Shiori instance details.
    4. Make the script executable: chmod +x ~/bin/termux-url-opener.

    Once configured, you can use the Android 'Share' menu to send links directly to Shiori.

    #!/bin/bash

# shiori settings
Shiori_URL="http://127.0.0.1:8080"
Username="shiori"
Password="gopher"

token=$(curl -s -X POST -H "Content-Type: application/json" -d '{"username": "'"$Username"'" , "password": "'"$Password"'", "remember": true}' $Shiori_URL/api/v1/auth/login | grep -oP '(?<="token":")[^"]*')

curl -s -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $token" -d '{ "url": "'"$1"'", "createArchive": false, "public": 1, "tags": [], "title": "", "excerpt": "" }' $Shiori_URL/api/bookmarks
exit