How to Self-Host Shiori in 2026: Archives, Accounts and Persistent Storage

A failed Shiori deployment does not always crash. It may serve a login page while archiving fails because Chromium dependencies or filesystem permissions are wrong. Start with an end-to-end check instead: save a bookmark with archived content, search it, edit tags and verify the archive remains available after the source page changes.

That check matches the cataloged purpose of Shiori: bookmark manager that archives page content. It also exposes missing dependencies, wrong proxy assumptions and ephemeral data earlier than an uptime probe can.

Draw the Shiori runtime boundary

Process health and product health are separate for Shiori. Port 8080 may answer while the user-facing transaction still fails. The external requirement for Shiori is a writable data volume and outbound access to archived pages. Test outbound DNS, TLS and provider behavior without publishing another inbound service.

Use this readiness exercise after meaningful configuration changes: save a bookmark with archived content, search it, edit tags and verify the archive remains available after the source page changes. Keep expensive external checks out of liveness probes so a provider outage does not cause a restart loop. Capacity work should track browser-based page capture, archive size, thumbnails and outbound fetching, which is closer to Shiori's real pressure than page requests.

Restore Shiori on an empty host

List the state before the first real record is created: database, archived page content, thumbnails and configuration. Mount /shiori before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Confirm the mount by writing harmless data, replacing Shiori and reading it back.

Snapshots are valuable for quick rollback, but an independent backup is needed when the host or volume disappears. Restore into an empty environment with the pinned image and verify that bookmarks, tags, archive files and accounts return and a dead source link still opens its saved content. Use persistent volumes and snapshots to keep those two recovery mechanisms distinct.

Security decisions specific to Shiori

The application-specific security risk is keeping the initial account unchanged on a public instance. The operational answer is to replace the initial account, limit public sharing and treat archived private URLs as sensitive content. Finish bootstrap through a restricted route and remove temporary setup access immediately afterward.

SHIORI_DIR controls behavior rather than confidentiality; validate its type and value, and store genuine Shiori credentials separately. Give the Shiori process only its documented mounts and dependency routes; avoid host root and Docker socket access. Log failed authentication and configuration errors, but redact tokens, connection strings and user content.

A production acceptance run for Shiori

A release candidate for Shiori earns traffic by completing a fixed scenario: save a bookmark with archived content, search it, edit tags and verify the archive remains available after the source page changes. Capture the image digest, effective non-secret configuration, public origin and timestamps for that scenario. The test data should be disposable but realistic enough to exercise the same path as users.

Run it after replacing the runtime, then rebuild the service from database, archived page content, thumbnails and configuration. Recovery passes when bookmarks, tags, archive files and accounts return and a dead source link still opens its saved content. Compare resource measurements for browser-based page capture, archive size, thumbnails and outbound fetching with the prior release and investigate meaningful drift before promotion.

Finally, exercise this controlled failure: temporarily deny the test path used by a writable data volume and outbound access to archived pages. Verify that Shiori explains the failure, does not damage existing state and resumes after the valid condition returns. Save a redacted log excerpt and the recovery time. Together these checks cover behavior, durability and operability rather than just process uptime.

Launch Shiori with observable defaults

Keep the initial Shiori invocation reproducible enough to review in a pull request.

docker run -d \
  --name shiori \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v shiori-data:/shiori \
  -e SHIORI_DIR=/shiori \
  ghcr.io/go-shiori/shiori:latest

Do not rely on latest after real data exists. Capture the working digest, container user and mount ownership. Follow the application log through a complete test — save a bookmark with archived content, search it, edit tags and verify the archive remains available after the source page changes — and note any migrations before putting the route behind production traffic.

Domains, proxy headers and port 8080

Treat the external Shiori URL as configuration that survives redeploys. First route the UI and API through a stable HTTPS origin; then route the hostname to port 8080 with the original host and scheme intact.

The deployment reachability checklist can prove that requests enter the container. After that point, the known failure — archiving fails because Chromium dependencies or filesystem permissions are wrong — should be investigated in Shiori, its state or its workload rather than in certificate automation.

Upgrade Shiori without guessing

The first useful operational metric for Shiori is whether it can save a bookmark with archived content, search it, edit tags and verify the archive remains available after the source page changes. Pair that with saturation signals for browser-based page capture, archive size, thumbnails and outbound fetching. A process-only probe should not call expensive dependencies or restart the container because an upstream is briefly unavailable.

Treat upgrades as data changes because Shiori database migrations and page-capture dependencies can change archive behavior. Pin versions, rehearse on restored state and keep the previous image available until a rollback remains valid. When archiving fails because Chromium dependencies or filesystem permissions are wrong, preserve logs from before the restart; they usually contain the causal message.

What Dockup should automate for Shiori

The platform layer for Shiori consists of port 8080, ingress, TLS, runtime configuration, storage and dependency reachability. Dockup can reproduce those pieces for its own infrastructure or a server the customer connects.

Then the operator finishes the product layer: route the UI and API through a stable HTTPS origin; enforce this access rule — replace the initial account, limit public sharing and treat archived private URLs as sensitive content; and run “save a bookmark with archived content, search it, edit tags and verify the archive remains available after the source page changes”. Recording that test alongside the deployment avoids confusing automated provisioning with application readiness.

Frequently asked questions

What does Shiori need for a production deployment?

Route the Shiori container on port 8080 through one HTTPS origin. The external delivery requirement is a writable data volume and outbound access to archived pages. Do not call Shiori ready until you can save a bookmark with archived content, search it, edit tags and verify the archive remains available after the source page changes.

Which Shiori data belongs in a backup?

Persist /shiori and include database, archived page content, thumbnails and configuration in the same recovery manifest. A clean Shiori restore passes only when bookmarks, tags, archive files and accounts return and a dead source link still opens its saved content.

Does Shiori require HTTPS behind a reverse proxy?

Use HTTPS for the public Shiori origin and keep port 8080 on the internal route. Apply the Shiori setting correctly: route the UI and API through a stable HTTPS origin. For Shiori, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Shiori upgrade be tested?

Restore current Shiori state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because Shiori database migrations and page-capture dependencies can change archive behavior. Keep the previous Shiori image until its data-migration and rollback boundary are understood.