How to Self-Host Shiori with Docker Compose

Bookmark Management That Fights Link Rot

At least 66% of web links eventually break. Shiori protects against this by saving offline copies of every page you bookmark — full HTML archives you can read even when the original disappears. Written in Go as a single binary, it uses ~25 MB of RAM, runs on a Raspberry Pi, and works with SQLite out of the box (no database server needed). If you want the absolute lightest self-hosted bookmark manager with archiving, this is it. github.com/go-shiori/shiori

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM (Shiori barely uses 30 MB)
• Storage for archived pages (1–5 GB for ~1,000 bookmarks with archives)

Docker Compose Configuration

SQLite (simplest — no database server):

services:
  shiori:
    image: ghcr.io/go-shiori/shiori:v1.8.0
    container_name: shiori
    environment:
      - SHIORI_DIR=/srv/shiori
      - SHIORI_HTTP_SECRET_KEY=change-this-to-a-random-string
    ports:
      - "8080:8080"
    volumes:
      - shiori-data:/srv/shiori
    tmpfs:
      - /tmp                    # Required for ebook generation
    restart: unless-stopped

volumes:
  shiori-data:

PostgreSQL (for multi-user or larger deployments):

services:
  shiori:
    image: ghcr.io/go-shiori/shiori:v1.8.0
    container_name: shiori
    environment:
      - SHIORI_DIR=/srv/shiori
      - SHIORI_DATABASE_URL=postgres://shiori:change-this-password@shiori-db:5432/shiori?sslmode=disable
      - SHIORI_HTTP_SECRET_KEY=change-this-to-a-random-string
    ports:
      - "8080:8080"
    volumes:
      - shiori-data:/srv/shiori
    tmpfs:
      - /tmp
    depends_on:
      shiori-db:
        condition: service_healthy
    restart: unless-stopped

  shiori-db:
    image: postgres:16-alpine
    container_name: shiori-db
    environment:
      POSTGRES_USER: shiori
      POSTGRES_PASSWORD: change-this-password
      POSTGRES_DB: shiori
    volumes:
      - shiori-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shiori"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  shiori-data:
  shiori-db-data:

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server:8080
2. Log in with the default credentials:
   • Username: shiori
   • Password: gopher
3. Change the password immediately — click the account icon and update it in Settings

Add your first bookmark using the ”+” button in the web UI. Shiori fetches the page title and description automatically, and saves an offline archive if the content is readable.

Configuration

Shiori uses environment variables for all configuration — no config files.

Setting	Env Var	Default	Notes
Data directory	SHIORI_DIR	/srv/shiori	Stores archives, thumbnails, ebooks, SQLite DB
Database	SHIORI_DATABASE_URL	SQLite in SHIORI_DIR	PostgreSQL or MySQL connection URL
HTTP port	SHIORI_HTTP_PORT	8080	Listening port
Bind address	SHIORI_HTTP_ADDRESS	: (all interfaces)	Restrict with 127.0.0.1 for local-only
Secret key	SHIORI_HTTP_SECRET_KEY	none	Required — session signing key
Root path	SHIORI_HTTP_ROOT_PATH	/	For sub-path reverse proxy hosting
Access log	SHIORI_HTTP_ACCESS_LOG	true	HTTP request logging
Web UI	SHIORI_HTTP_SERVE_WEB_UI	true	Set false for API-only mode

Database connection strings:

• PostgreSQL: postgres://user:pass@host:5432/dbname?sslmode=disable
• MySQL: mysql://user:pass@(host:3306)/dbname?charset=utf8mb4

The deprecated SHIORI_DBMS variable still works but SHIORI_DATABASE_URL is preferred.

Advanced Configuration

Browser Extensions

Shiori has browser extensions for Firefox and Chrome/Edge that let you bookmark the current page with one click. Install from the respective extension stores and configure with your Shiori instance URL.

SSO / Proxy Authentication

Shiori supports proxy header authentication for SSO setups with Authelia, Authentik, or similar:

SHIORI_SSO_PROXY_AUTH_ENABLED=true
SHIORI_SSO_PROXY_AUTH_HEADER_NAME=Remote-User
SHIORI_SSO_PROXY_AUTH_TRUSTED=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

The trusted CIDR list should include only your reverse proxy’s IP range.

CLI Access

Shiori includes a full CLI for managing bookmarks from the command line:

# Add a bookmark
docker compose exec shiori shiori add https://example.com

# Search bookmarks
docker compose exec shiori shiori search "docker compose"

# Export bookmarks (Netscape HTML format)
docker compose exec shiori shiori export > bookmarks.html

# Import from Pocket
docker compose exec shiori shiori pocket import pocket-export.html

PWA Support

Shiori v1.8.0 added Progressive Web App support. Access the web UI on mobile and use the “Add to Home Screen” option for an app-like experience with share functionality.

Reverse Proxy

Shiori’s web UI works cleanly behind a reverse proxy. Proxy to shiori:8080. If hosting under a sub-path (e.g., example.com/shiori/), set SHIORI_HTTP_ROOT_PATH=/shiori/. See Reverse Proxy Setup.

Backup

SQLite setup: The entire application state lives in the shiori-data volume. Back it up:

# Stop writes during backup for consistency
docker compose stop shiori
tar czf shiori-backup.tar.gz $(docker volume inspect shiori-data --format '{{ .Mountpoint }}')
docker compose start shiori

PostgreSQL setup: Back up the database separately:

docker compose exec shiori-db pg_dump -U shiori shiori > shiori-db-backup.sql

Also back up shiori-data — it contains the archived pages, thumbnails, and ebooks regardless of database backend.

See Backup Strategy.

Troubleshooting

Default login doesn’t work

Symptom: Username shiori with password gopher is rejected. Fix: If upgrading from an older version, the default account may not exist. Check if a migration is needed: docker compose exec shiori shiori migrate. If the database was initialized by a previous version, log in with whatever credentials you set previously.

Ebook generation fails silently

Symptom: Clicking “Create ebook” does nothing. Fix: Ebook generation requires a writable /tmp directory. Add tmpfs: ["/tmp"] to your compose file. Without this, the ebook creation process fails without an error message.

Archived pages are blank

Symptom: The offline archive shows an empty page. Fix: Not all websites allow archiving — JavaScript-heavy single-page apps often produce blank archives. Shiori extracts readable content using a readability parser. Sites that block bots or require JavaScript rendering won’t archive well. This is a fundamental limitation.

”Account table missing” error after upgrade

Symptom: Errors about missing database tables after upgrading. Fix: Run the migration command: docker compose exec shiori shiori migrate. This is particularly common when upgrading from v1.5.x to later versions due to database schema changes.

Old accounts have limited permissions

Symptom: After upgrading from v1.0.x, existing accounts can’t manage bookmarks fully. Fix: v1.5.0 introduced owner/visitor permission levels. Log in with the default account (shiori/gopher), go to Settings, delete old accounts, and recreate them with owner permissions.

Resource Requirements

Resource	Value
RAM (idle)	~20–30 MB
RAM (archiving)	~50–100 MB
CPU	Negligible
Disk (image)	~30 MB (scratch-based container)
Disk (data)	0.5–5 MB per archived bookmark

Shiori is one of the lightest self-hosted applications you can run. The scratch-based Docker image contains only the Go binary and TLS certificates — no OS, no shell, no package manager.

Verdict

Shiori is the right bookmark manager if you value simplicity and offline archiving above all else. A single container with SQLite, 25 MB of RAM, and your bookmarks survive even when the original pages die.

The trade-off: Shiori’s feature set is minimal compared to alternatives. No collaboration features, no screenshot previews, limited organizational tools beyond tags. Development pace is measured — updates come slowly.

For most people, Linkding is the better all-around bookmark manager — it’s similarly lightweight, more actively developed, and has a more polished UI. Choose Shiori specifically for offline page archiving. Choose Linkwarden if you want screenshots, collaboration, and a modern UI. Choose Hoarder if you want AI-powered organization.

FAQ

How much storage do archived pages use?

Each archived page is typically 0.5–5 MB depending on complexity. A collection of 1,000 bookmarks with full archives might use 1–5 GB. Plain text extractions are much smaller.

Can I import bookmarks from my browser?

Yes. Export your browser bookmarks as an HTML file (Netscape format) and import via the CLI: docker compose exec shiori shiori import bookmarks.html. Pocket exports are also supported natively.

Is Shiori still actively maintained?

Development is ongoing but slow. The current maintainer is @fmartingr, with occasional contributions from the original creator. v1.8.0 (September 2024) added PWA support and SQLite performance improvements. It’s stable but don’t expect frequent feature additions.

Can multiple users share one Shiori instance?

Yes. Shiori supports multiple user accounts with owner and visitor permission levels. Owners can manage all bookmarks; visitors have read-only access. For multi-user setups, consider using PostgreSQL instead of SQLite.

Related

• How to Self-Host Linkding
• How to Self-Host Linkwarden
• How to Self-Host Wallabag
• How to Self-Host Hoarder
• How to Self-Host LinkAce
• LinkAce vs Linkding
• Best Self-Hosted Bookmark Managers
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy