Repository navigation
Tell self-hosters to set APP_URL, because email and connected-app links use it #337
Description
Parent
What to build
The server builds public links from APP_URL. Today that covers digest and notice emails, the create_document link, and the MCP server's websiteUrl. A self-host that leaves APP_URL unset sends all of them to https://docs.plus. The self-hosting docs do not say this.
Already done in cdb222d40 and 0dacee392: one trimmed APP_URL with a fallback, and appUrl in the MCP deps. The shared link helpers move to #343, their first user.
Acceptance criteria
-
docs/self-hosting/configuration.md§Turn on the MCP connector says: "SetAPP_URLto your webapp address. Connected apps and emails build links from it. If it is unset, those links point athttps://docs.plus." - The
APP_URLrow indocs/self-hosting/install.mdreads "Your editor domain, used in email and connected-app links". The table stays aligned. - No code change.
Blocked by
None — can start now.
Agent brief
Type: AFK — docs only.
apps/hocuspocus.server/ENV.mdalready states the trim, the fallback and the link uses. It needs no change.- Prose follows
.cursor/skills/tech-writer/SKILL.md§Simplified English (house standard). - Verify:
bun run formatpasses at the repo root.
Out of scope
- The link helpers and the digest's
sectionUrl— Add links and Comment quotes to MCP reads #343. - The webapp link builder — Build stored heading and message links from the pad path, not the address bar #331.
- Landing a cold-opened
?id=link — Land a heading link on its heading, even when the heading is folded or filtered #338.
Activity
HMarzban commentedon Sep 28, 2026
Part of this issue is covered by two commits on
main. They are committed locally and go up with the next push.Done
APP_URL(cdb222d40, fix(hocuspocus): read APP_URL once, without a trailing slash).config/env.tsnow computes(env.APP_URL || 'https://docs.plus').replace(/\/+$/, '')once.config.email.appUrland the CORS fallback both use it. So a blankAPP_URL=no longer gives'', and a trailing/is removed.api/email.tsreadconfig.email.appUrlinstead ofprocess.env.APP_URL. So the digest path throughpgmqConsumer.tsgets the clean value too.apps/hocuspocus.server/ENV.mddescribes the trim and the fallback.0dacee392, feat(hocuspocus): add the create_document MCP tool).InitDepsandServerFactoryDepscarryappUrl, andsrc/index.tspassesconfig.email.appUrl.create_documentreturns<appUrl>/<slug>. No existing tool output changed.Still open in this issue
buildDocumentUrl/buildHeadingUrlhelper, and deleting the digest's privatesectionUrl. It is still indigestContentChanges.ts.docs/self-hosting/configuration.md: telling operators to setAPP_URL.docs/self-hosting/install.md:66: theAPP_URLrow still says "used in email links" only.So acceptance items 3 and 4 are met. Items 1, 2, 6 and 7 remain.
[-]Give the MCP module the app URL and one server heading-link helper[/-][+]Tell self-hosters to set APP_URL, because email and connected-app links use it[/+]HMarzban commentedon Oct 7, 2026
One more env value for this issue:
PUBLIC_RESTAPI_URLalso sets the MCPresourceURL (apps/hocuspocus.server/src/index.ts:134,src/modules/mcp/http/controller.ts:23-24). When it is unset, the URL falls back to the request origin, so a self-hoster behind a proxy must set it. Please document it inapps/hocuspocus.server/ENV.md(which today says only two conversion paths read it) and indocs/self-hosting/configuration.md.