Skip to content

Document the HTTPS service proxy and the per-app opt-out - #25

Open
krokicki wants to merge 1 commit into
mainfrom
document-service-proxy
Open

Document the HTTPS service proxy and the per-app opt-out#25
krokicki wants to merge 1 commit into
mainfrom
document-service-proxy

Conversation

@krokicki

@krokicki krokicki commented Sep 4, 2026

Copy link
Copy Markdown
Member

The docs never mentioned that a Fileglancer server can republish running services at a per-job HTTPS subdomain. An app author testing against a configured server had no explanation for why the URL their job wrote to SERVICE_URL_PATH was not the URL the user's browser opened, and no page told an administrator the setting exists.

Application half: JaneliaSciComp/fileglancer#445, which adds the service_proxy: false opt-out documented here. Independent — each is useful without the other, and everything except the opt-out row describes behavior that already shipped.

What changed

authoring/services.mdx — new "Access Over HTTPS" section covering the rewrite (path and query carried across unchanged, so a service_url_suffix token still works), the Host header an app sees behind the proxy and what to do if a WebSocket origin check rejects it, and an "Opting out of the proxy" subsection for the new flag. The opt-out carries a caution aside: it gives up encryption on every hop including the browser's, so it is not a preference switch. Step 4 of "How It Works" now points at the new section.

authoring/server-config.mdx — a ## Service Proxy (service_proxy_domain) section in the existing ## Name (key) house style, covering the setting, the session_secret_key requirement and why the labels are signed, and pointing at docs/ServiceProxy.md in the application repo for the DNS, certificate, and reverse-proxy steps rather than duplicating them here.

authoring/manifest-reference.mdx — a service_proxy row after service_url_suffix.

workflows/apps-and-jobs.mdx — two lines for end users under "Services": what the per-job address looks like, that it dies with the service, and that a server without the proxy opens services over plain HTTP at the compute node, which needs direct network access to the cluster.

Notes

I did not touch the existing statements that the published URL is http://$FG_HOSTNAME:$FG_SERVICE_PORT — those describe what gets written to SERVICE_URL_PATH, which is still exactly right. The rewrite happens at display time, and the new section is what draws that distinction.

No sidebar change; no new pages.

Verified

npm run build passes, 23 pages built. Both new anchors (#access-over-https, #opting-out-of-the-proxy) are generated in the output, and the two cross-links pointing at #opting-out-of-the-proxy from the manifest reference and server config pages resolve against them. Checked in the built HTML, since the repo has no link-check gate.

@StephanPreibisch @JaneliaSciComp/fileglancer

Nothing in the docs mentioned that a server can republish running services
at a per-job HTTPS subdomain, so an app author testing against a configured
server had no explanation for why the URL their job published was not the
URL the user opened.

Adds an "Access Over HTTPS" section to the Services page covering the
rewrite, the Host header an app sees behind the proxy, and the new
`service_proxy: false` opt-out for a service that cannot work at a
rewritten address. The opt-out carries a caution: it gives up encryption on
every hop, including the browser's, so it is not a preference switch.

Also documents `service_proxy_domain` for administrators on the Server
Configuration page, adds the manifest reference row, and tells end users on
the Apps and Jobs page what the per-job address is and that it dies with
the service.
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