個人用ブックマーク管理アプリ(Go + SQLite)
  • Go 69.4%
  • JavaScript 20.9%
  • CSS 6.3%
  • HTML 2.2%
  • Shell 1.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
littleisland e08f5eb23a
All checks were successful
release / build-and-release (push) Successful in 1m16s
Merge pull request 'release: prepare v1.4.0' (#13) from refactor/reduce-duplication into main
2026-11-18 19:07:28 +00:00
.forgejo ci: run tests only for main pull requests 2026-08-26 19:38:43 +09:00
.handoff docs: record v1.2.1 release evidence 2026-08-19 18:44:52 +09:00
_refs fix: isolate login failures behind trusted proxies 2026-10-09 12:43:26 +09:00
docs docs: record v1.4.0 pre-tag verification 2026-11-19 04:00:55 +09:00
e2e chore: update SQLite and Playwright 2026-11-19 03:56:37 +09:00
scripts feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
static refactor: reuse bookmark and tag processing 2026-11-19 03:56:37 +09:00
.gitignore feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
AGENTS.md docs: remove outdated agent delegation guide 2026-11-19 03:25:01 +09:00
auth.go fix: isolate login failures behind trusted proxies 2026-10-09 12:43:26 +09:00
auth_proxy_test.go fix: isolate login failures behind trusted proxies 2026-10-09 12:43:26 +09:00
bookmark.go refactor: reuse bookmark and tag processing 2026-11-19 03:56:37 +09:00
bookmark_status.go release: v1.2.1 2026-08-19 18:41:52 +09:00
CHANGELOG.ja.md docs: prepare v1.4.0 release notes 2026-11-19 03:56:37 +09:00
CHANGELOG.md docs: prepare v1.4.0 release notes 2026-11-19 03:56:37 +09:00
db.go release: v1.2.0 2026-08-19 17:47:41 +09:00
go.mod chore: update SQLite and Playwright 2026-11-19 03:56:37 +09:00
go.sum chore: update SQLite and Playwright 2026-11-19 03:56:37 +09:00
henji_runner.go fix(ci): keep static analysis local 2026-08-26 18:16:22 +09:00
henji_runner_test.go release: v1.0.0 2026-07-26 20:58:09 +09:00
importexport.go fix(ci): keep static analysis local 2026-08-26 18:16:22 +09:00
LICENSE docs: update copyright holder 2026-07-26 00:44:53 +09:00
main.go feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
main_test.go refactor: reuse bookmark and tag processing 2026-11-19 03:56:37 +09:00
metadata.go refactor: reuse bookmark and tag processing 2026-11-19 03:56:37 +09:00
migration_test.go release: v1.2.0 2026-08-19 17:47:41 +09:00
model.go feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
package-lock.json chore: update SQLite and Playwright 2026-11-19 03:56:37 +09:00
package.json test(e2e): automate bookmark 404 release check 2026-08-26 17:20:33 +09:00
playwright.config.js test: add Playwright visual regression setup 2026-08-26 13:27:53 +09:00
README.ja.md feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
README.md feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
schema.go feat: add schema integrity test and CI test workflow 2026-06-25 13:42:06 +09:00
summary.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_budget.go refactor: reuse bookmark and tag processing 2026-11-19 03:56:37 +09:00
summary_budget_test.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_config.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_config_test.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_job.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_job_test.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_live_test.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_model_comparison_test.go release: v1.0.0 2026-07-26 20:58:09 +09:00
summary_test.go release: v1.0.0 2026-07-26 20:58:09 +09:00
tag.go refactor: reuse bookmark and tag processing 2026-11-19 03:56:37 +09:00
thumbnail.go feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
thumbnail_test.go feat: cache resized bookmark thumbnails 2026-11-19 03:22:54 +09:00
util.go fix: apply security and robustness improvements from code review 2026-06-25 10:24:41 +09:00

Shirushi

Shirushi is a personal bookmark manager. Beyond saving URLs, organizing tags, and searching, it emphasizes the flow of search → multi-select → bulk tagging to help you cultivate a record of your interests.

It is a Go + SQLite single binary that can run on a home server (Proxmox / Alpine Linux) and be accessed remotely through Caddy.

Inspired by: Shiori. Shirushi is rebuilt for bulk operations, tag management, and personal research records, without archiving or multi-user management.

日本語版: README.ja.md


Features

  • Add, edit, and delete bookmarks
  • Automatically fetch OGP metadata (title, description, and thumbnail)
  • Create, edit, and delete tags, then attach them to bookmarks
  • Keyword search, tag filters, and date search (for example, 202507 for July 2025)
  • Choose 50, 100, or 200 items per page, with pagination above and below the list
  • Multi-select bookmarks to add or remove tags in bulk, or delete them in bulk
  • Import and export Netscape Bookmark files (the format exported by Chrome and Firefox)
  • Password authentication for one user, with optional 30-day persistent login
  • Bearer token authentication for API clients such as browser extensions
  • Asynchronous 404 checks for saved URLs, with a bundled replacement thumbnail
  • Optional Japanese article summaries for saved bookmarks through Henji
  • A fixed dark theme

Main screen


Build

# Build for the current machine
go build -o shirushi .

# Static binary for Alpine Linux / Proxmox LXC; no CGO required
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o shirushi .

Go 1.26.4 or later is required. Shirushi uses modernc.org/sqlite for SQLite and golang.org/x/image for thumbnail resizing. Both work without CGO.


Run

SHIRUSHI_PASSWORD='yourpassword' ./shirushi

Then open http://localhost:8181 in a browser.

Shirushi exits with an error if SHIRUSHI_PASSWORD is not set.

Optional: article summaries with Henji

Shirushi v1.0.0 can summarize the static HTML of a saved bookmark in Japanese with a generative AI model through Henji. Henji is an optional external command: configure its provider credentials separately, then Shirushi uses henji on PATH (or a path supplied with --henji-path). If it is unavailable, the AI button is hidden and the rest of Shirushi works normally.

For setup, startup options, security boundaries, limits, and the asynchronous UI behavior, see Henji article summaries. Shirushi never stores Henji API keys or provides a provider settings screen.

# Use henji on PATH
SHIRUSHI_PASSWORD='yourpassword' ./shirushi

Environment variables

Variable Default Description
SHIRUSHI_PASSWORD (required) Login password. Shirushi will not start without it.
SHIRUSHI_API_TOKEN (unset) Bearer token for API authentication. When unset, only cookie authentication is enabled.
SHIRUSHI_ADDR :8181 Listen address. Use 127.0.0.1:8181 when Caddy runs on the same host.
SHIRUSHI_COOKIE_SECURE (unset) Set to 1 to add the Secure attribute to session cookies. Set this for HTTPS deployments.
SHIRUSHI_TRUSTED_PROXIES (unset) Comma-separated proxy IP addresses whose forwarded client IPs are trusted. Supports IPv4/IPv6. Loopback is always trusted.
SHIRUSHI_ALLOW_PRIVATE_FETCH (unset) Set to 1 to disable SSRF protection while fetching metadata. Only for restricted use cases such as internal tools.

HTTPS deployment with Caddy

The intended setup runs Caddy in one LXC container and Shirushi in another.

Internet
  → Caddy LXC (HTTPS termination)
  → Proxmox bridge
  → Shirushi LXC (:8181)

Caddyfile (on the Caddy LXC):

shirushi.example.com {
    reverse_proxy <Shirushi LXC LAN IP>:8181
}

Start Shirushi (on the Shirushi LXC):

SHIRUSHI_PASSWORD='a-long-random-password' \
SHIRUSHI_COOKIE_SECURE=1 \
SHIRUSHI_TRUSTED_PROXIES='<Caddy LXC LAN IP>' \
./shirushi

You may keep the default listen address, :8181 (all interfaces). If only ports 80 and 443 are publicly exposed and routed through Caddy, port 8181 is not exposed to the Internet.

Set SHIRUSHI_TRUSTED_PROXIES to the Caddy LXC's LAN IP. Shirushi uses X-Forwarded-For from that peer to count failed logins per original client IP. For example: SHIRUSHI_TRUSTED_PROXIES=192.168.1.10. Separate multiple IPs with commas. Hostnames, CIDRs, and addresses with ports are not accepted; invalid values cause a startup error.

Note

: Caddy's reverse_proxy adds XFF by default; do not remove it with header_up -X-Forwarded-For. Without the trust setting for a separate LXC, or without forwarded client IP headers, failed-login counts use the Caddy IP and are shared by all clients.


Backup and restore

The database is stored as shirushi.db in the same directory as the binary.

Resized thumbnails are stored in thumbnail-cache/ under the server's working directory. Thumbnails for existing bookmarks are generated as they are displayed and can be regenerated after clearing the cache.

# Backup (the server does not need to be stopped)
cp shirushi.db shirushi.db.backup-$(date +%Y%m%d)

# Restore
cp shirushi.db.backup-20260614 shirushi.db

WAL mode also creates the auxiliary files shirushi.db-wal and shirushi.db-shm. Copy them together with the database when backing up, or first consolidate the WAL with VACUUM and then copy the database.

# Consolidate the WAL before backing up
sqlite3 shirushi.db "VACUUM;"
cp shirushi.db shirushi.db.backup-$(date +%Y%m%d)

Test

go test -v -cover ./...

Known limitations

  • Single user only: Multiple accounts are not supported.
  • Sessions are kept in memory: Restarting the server signs users out.
  • Thumbnail fetching after imports is asynchronous: After importing a Netscape Bookmark file, OGP images are fetched in the background. For large imports, wait a while and reload the page.
  • Henji summaries are asynchronous and silent: The UI does not show progress or completion. Reload the list later to see a completed summary.
  • No archiving: Shirushi does not make offline copies of pages.

API

For endpoint, request, response, and error-code details, see docs/api.md.


Mirrors

This repository is mirrored on Codeberg. The canonical repository is forge.harakara.site/littleisland/shirushi.


License

MIT

Changelog

CHANGELOG.md