Skip to content

README hero, demo screenshots, and Docker self-hosting - #1

Merged
falkoro merged 2 commits into
mainfrom
fm/logbook-hero-docker
Oct 16, 2026
Merged

falkoro merged 2 commits into
mainfrom
fm/logbook-hero-docker

Conversation

@falkoro

@falkoro falkoro commented Oct 13, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Hero diagram at the top of the README: you and your agents on one tracker and one log, agents over Linear-compatible MCP, Cloudflare free tier or self-hosted. Hand-written SVG source in docs/hero.svg, rendered to docs/hero.png (2000×1000, 270 KB).
  • Screenshots of the seeded demo (bun run demo data only), in a "What it looks like" section: docs/screenshot-board.png, docs/screenshot-issue.png, docs/screenshot-decision.png. The decision in the third one was asked for real over MCP (tools/call ask_decision with an agent token against the running demo). The demo GIF stays, just below them.
  • Docker: Dockerfile (oven/bun:1, bun install --frozen-lockfile, UI built in a build stage, production deps only in the final image), docker-compose.yml (one logbook service, port published on 127.0.0.1:${LOGBOOK_PORT:-8796}, named volume logbook-data:/data, restart: unless-stopped, DEV_AUTH=${LOGBOOK_DEV_AUTH:-1}), .dockerignore, and a "Run it with Docker" quickstart in the README.

App code change

entry/server.ts already reads HOST/PORT (the Dockerfile sets HOST=0.0.0.0), but DEV_AUTH only trusts loopback peers, and inside a container a published port always arrives from the Docker bridge. Without a change nobody could sign in to the Docker instance. The smallest fix is a new env var, LOCAL_ANY_PEER=1, which treats every TCP peer as this machine. Only docker-compose.yml sets it, and it publishes the port on 127.0.0.1 only. DEV_AUTH still requires a localhost/127.0.0.1 Host header, and LOGBOOK_DEV_AUTH=0 turns it off for anything exposed (the README points to Tunnel + Access for that).

Docker test (real run, docker compose with a project name so it didn't clash with other stacks)

$ LOGBOOK_PORT=18797 docker compose -p logbook-hero-test up -d --build
 Container logbook-hero-test-logbook-1 Started
$ curl -sf http://127.0.0.1:18797/healthz
ok
$ docker compose logs
logbook on http://0.0.0.0:8796 (data in /data)
$ docker compose port logbook 8796
127.0.0.1:18797
$ curl -s -o /dev/null -w '%{http_code}' -X POST http://127.0.0.1:18797/mcp          # no token
403

# as Settings does it (DEV_AUTH from localhost)
$ curl -s -X POST http://localhost:18797/api/save_team -H 'x-logbook: 1' -d '{"key":"OPS","name":"Self-hosted"}'
{"id":"bb4c3f74-…","key":"OPS","name":"Self-hosted",…}
$ curl -s -X POST http://localhost:18797/api/create_token -H 'x-logbook: 1' -d '{"name":"docker-test","actor":"claude"}'
{"id": "a70e7bec-…", "name": "docker-test", "actor": "claude", "token": "lb_59r…"}

# real MCP with the agent token
$ curl -s -X POST http://127.0.0.1:18797/mcp -H 'Authorization: Bearer $TOKEN' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"logbook","version":"0.1.0"},"instructions":"Logbook is the issue tracker for every app …
$ curl … '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
26 tools: list_issues, get_issue, save_issue, save_comment, list_comments, list_teams, list_issue_statuses, list_issue_labels, save_issue_label, list_users, me, list_documents, get_document, save_document, overview, list_releases, save_release, set_release_status, ask_decision, list_decisions, withdraw_decision, search, list_changes, upload_file, link_pr, list_activity
$ curl … '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"save_issue","arguments":{"team":"OPS","title":"Created over MCP inside Docker"}}}'
{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"{\n  \"id\": \"OPS-1\",\n  …\n  \"title\": \"Created over MCP inside Docker\",\n  … \"status\": \"Backlog\" …
$ curl … '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"list_issues","arguments":{"team":"OPS"}}}'
{"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"{\n  \"issues\": [\n    {\n      \"id\": \"OPS-1\",\n      …\"title\": \"Created over MCP inside Docker\" …

# persistence
$ docker compose restart
 Container logbook-hero-test-logbook-1 Started
$ curl … list_issues {"team":"OPS"}
{"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"{\n  \"issues\": [\n    {\n      \"id\": \"OPS-1\",\n      …\"title\": \"Created over MCP inside Docker\" …

# DEV_AUTH refuses a non-localhost Host header
$ curl -s -o /dev/null -w '%{http_code}' -X POST http://127.0.0.1:18797/api/me -H 'Host: example.com' -H 'x-logbook: 1'
401

$ docker compose down -v
 Volume logbook-hero-test_logbook-data Removed
 Network logbook-hero-test_default Removed

Result: pass. The image is 351 MB. bun run check is clean and bun test passes 40/40.

Origin sync

Both commits cherry-picked cleanly onto cursor/main (c192e78), and bun test passes 48/48 there. Pushed as fm/logbook-hero-docker at 9007f4b93e2c2ad0d229c27ac4a51adbe6c3de73. No PR was opened on Origin.


Note

Medium Risk
LOCAL_ANY_PEER widens which TCP peers satisfy dev auto-login when enabled; mitigated by compose binding to 127.0.0.1 and unchanged localhost Host requirement for DEV_AUTH.

Overview
Adds Docker-based self-hosting with a multi-stage Dockerfile (Bun build + production image on port 8796, data in /data), docker-compose.yml (127.0.0.1-only port bind, named volume, default DEV_AUTH), and .dockerignore. The README gains a hero image, a What it looks like screenshot table, and a Run it with Docker quickstart (docs/hero.svg is the new diagram source).

entry/server.ts introduces LOCAL_ANY_PEER=1 so requests through the Docker bridge count as local for DEV_AUTH (compose sets this while still publishing only on loopback); non-localhost Host headers remain rejected per existing auth rules.

Reviewed by Cursor Bugbot for commit a554675. Bugbot is set up for automated code reviews on this repo. Configure here.

The self-host server learns LOCAL_ANY_PEER: in Docker a published port
arrives from the bridge, never loopback, so DEV_AUTH could not sign anyone
in. Compose sets it and publishes the port on 127.0.0.1 only.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: medium. Approved. Cursor Bugbot completed successfully with no findings that need human review; the Docker and LOCAL_ANY_PEER changes stay within the medium-risk approval threshold.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Approver

@falkoro

falkoro commented Oct 13, 2026

Copy link
Copy Markdown
Owner Author

CI: test passed, and so did the Cursor Approval Agent and Cursor Bugbot (3/3).

Security note on LOCAL_ANY_PEER (an automated review flagged it as an auth bypass): with LOCAL_ANY_PEER=1 and DEV_AUTH=1, every request that reaches the container with a localhost/127.0.0.1 Host header acts as the owner. That is the same trust bun run demo gives every loopback caller. It is safe only because docker-compose.yml publishes the port on 127.0.0.1. If someone changes the publish to 0.0.0.0 and leaves DEV_AUTH on, anyone on their network gets owner access by sending Host: localhost. The compose comments and the README say to set LOGBOOK_DEV_AUTH=0 and use Access for anything beyond localhost. The variable is off by default and only compose sets it, so bun run serve and the Worker are unchanged. If the reviewer wants it tighter, the next step is to trust only the bridge gateway's IP, or to have the server refuse to start when DEV_AUTH is on and it isn't bound to loopback. I left both out to keep the change minimal.

@falkoro
falkoro merged commit 9c3e69a into main Oct 16, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant