Deploying Shiori

Introduction

Shiori is a simple, lightning-fast bookmark manager written in Go. Inspired by Pocket, Shiori allows you to save web pages for later reading, with the ability to create offline archives of the content so you can access it even if the original page disappears. Its clean, responsive interface works well on both desktop and mobile browsers.

Built as a single binary with minimal dependencies, Shiori is incredibly easy to deploy and maintain. The application supports SQLite, PostgreSQL, and MySQL databases, giving you flexibility in how you want to store your bookmarks. Browser extensions are available for quick bookmark saving.

Key highlights of Shiori:

• Offline Archives: Save page content locally for offline access
• Fast and Lightweight: Single Go binary with minimal resource usage
• Tag-Based Organization: Organize bookmarks with flexible tags
• Full-Text Search: Search across bookmarks and archived content
• Browser Extensions: Available for Chrome and Firefox
• Reader Mode: Clean reading view without distractions
• Multi-Database Support: SQLite, PostgreSQL, or MySQL
• Import/Export: Import from Netscape HTML bookmark files
• REST API: Programmatic access to your bookmarks
• 100% Open Source: Licensed under MIT

This guide walks through deploying Shiori on Klutch.sh using Docker, setting up your bookmark library, and archiving web content.

Why Deploy Shiori on Klutch.sh

Deploying Shiori on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles container orchestration with Shiori’s single-binary simplicity.

Persistent Storage: Attach persistent volumes for your bookmark database and archives.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure bookmark access.

Lightweight: Minimal resource requirements due to Go’s efficiency.

Custom Domains: Use your own domain for a personalized bookmark manager.

Prerequisites

Before deploying Shiori on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Shiori configuration
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with your Shiori configuration.

Repository Structure

shiori-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/go-shiori/shiori:latest

# Environment variables
ENV SHIORI_DIR=/data
ENV SHIORI_DBMS=${SHIORI_DBMS:-sqlite}

# For PostgreSQL (optional)
ENV SHIORI_PG_HOST=${SHIORI_PG_HOST:-}
ENV SHIORI_PG_PORT=${SHIORI_PG_PORT:-5432}
ENV SHIORI_PG_USER=${SHIORI_PG_USER:-}
ENV SHIORI_PG_PASS=${SHIORI_PG_PASS:-}
ENV SHIORI_PG_NAME=${SHIORI_PG_NAME:-shiori}

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 8080

# Start Shiori server
CMD ["serve", "--address", "0.0.0.0", "--port", "8080"]

Environment Variables Reference

Variable	Required	Default	Description
SHIORI_DIR	No	/data	Directory for database and archives
SHIORI_DBMS	No	sqlite	Database type: sqlite, postgresql, mysql
SHIORI_PG_HOST	No	-	PostgreSQL host (if using postgresql)
SHIORI_PG_PORT	No	5432	PostgreSQL port
SHIORI_PG_USER	No	-	PostgreSQL username
SHIORI_PG_PASS	No	-	PostgreSQL password
SHIORI_PG_NAME	No	shiori	PostgreSQL database name
SHIORI_MYSQL_HOST	No	-	MySQL host (if using mysql)
SHIORI_MYSQL_PORT	No	3306	MySQL port
SHIORI_MYSQL_USER	No	-	MySQL username
SHIORI_MYSQL_PASS	No	-	MySQL password
SHIORI_MYSQL_NAME	No	shiori	MySQL database name

Deploying Shiori on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Shiori deployment configuration"
git remote add origin https://github.com/yourusername/shiori-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project with a descriptive name like “shiori” or “bookmarks”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Shiori repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

Add optional environment variables:

Variable	Value
SHIORI_DBMS	sqlite (or postgresql/mysql)

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
/data	20 GB	Database and archived pages

Deploy Your Application

Click Deploy to start the build process.

Access Shiori

Once deployment completes, access your Shiori instance at https://your-app-name.klutch.sh.

Create Admin Account

The default credentials are:

• Username: shiori
• Password: gopher

Change these immediately after first login.

Initial Configuration

Changing Default Password

1. Log in with default credentials
2. Click your username in the top right
3. Go to Settings
4. Change your password
5. Optionally create new accounts

Creating Additional Accounts

1. Log in as admin
2. Go to Settings > Accounts
3. Click New Account
4. Enter username and password
5. Set as owner (admin) or regular user

Adding Bookmarks

Via Web Interface

1. Click the + button
2. Enter the URL
3. Shiori fetches the page
4. Add tags (comma separated)
5. Click Save

Via Browser Extension

1. Install the Shiori extension:
   • Chrome Extension
   • Firefox Extension
2. Configure the extension with your Shiori URL
3. Enter your credentials
4. Click the extension icon on any page to save it

Via API

curl -X POST https://your-app-name.klutch.sh/api/bookmarks \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "tags": ["tech", "reading"]}'

Managing Bookmarks

Organizing with Tags

• Add tags when saving bookmarks
• Click tags in the sidebar to filter
• Edit bookmarks to modify tags

Search

Use the search bar to find bookmarks by:

• Title
• URL
• Tags
• Archived content (full-text search)

Creating Archives

1. Open a bookmark
2. Click Update Cache to refresh the archive
3. View the archived version with Archive button
4. Access offline even if original site is down

Reader Mode

Click the Reader button to view archived content in a clean, distraction-free format without ads and navigation.

Importing Bookmarks

From Browser

1. Export bookmarks from your browser as HTML
2. Log in to Shiori
3. Click Import
4. Select the HTML file
5. Bookmarks are imported with folder names as tags

From Pocket

1. Export from Pocket as HTML
2. Import using the same process
3. Tags are preserved

Troubleshooting

Cannot Log In

Symptoms: Login fails with correct credentials.

Solutions:

• Reset to default credentials using CLI if locked out
• Clear browser cookies
• Check database connectivity
• Verify the data volume is mounted

Archives Not Creating

Symptoms: Archive button shows no content.

Solutions:

• Verify the URL is accessible
• Check available disk space
• Some sites block archiving (try manually)
• Review server logs for errors

Slow Performance

Symptoms: Interface is sluggish with many bookmarks.

Solutions:

• Consider switching to PostgreSQL for large collections
• Ensure adequate storage I/O
• Archive pages asynchronously

Extension Not Connecting

Symptoms: Browser extension can’t reach server.

Solutions:

• Verify the server URL in extension settings
• Check HTTPS is working
• Ensure credentials are correct
• Clear extension storage and reconfigure

Additional Resources

• Shiori GitHub Repository
• Shiori Wiki

Conclusion

Deploying Shiori on Klutch.sh gives you a fast, lightweight bookmark manager with offline archiving capabilities. With browser extensions for quick saving and full-text search across your archived pages, Shiori helps you build a personal archive of the web while keeping all your data under your control.