Add Globus set up documentation#3125

Open

whwjiang wants to merge 4 commits intoPelicanPlatform:mainfrom

whwjiang:ls_new

Contributor

whwjiang commented Feb 16, 2026

I have added a page for setting up Globus from scratch, now that the integration project is merged into main.


          globus changes

a2083e2

whwjiang requested review from CannonLock and jhiemstrawisc

February 16, 2026 16:56

whwjiang added the documentation label

whwjiang linked an issue

that may be closed by this pull request

Globus integration needs documentation #3126

Open

Member

jhiemstrawisc commented Feb 17, 2026

@whwjiang before I get around to reviewing this, can you take care of the failing linter items? If you haven't, you should install pre-commit and then initialize it in the root of the Pelican repo, e.g.

$ python3 -m pip install pre-commit

# From root of pelican repo
$ pre-commit install

Pre-commit should help with these types of linter items in the future because it runs all the same cleanup hooks at commit time.

jhiemstrawisc requested a review from turetske

February 17, 2026 16:16

Member

jhiemstrawisc commented Feb 17, 2026

@turetske is also going to run through the docs to try them out as someone who hasn't set up these types of Globus Origins before.

jhiemstrawisc mentioned this pull request

Globus Origins _require_ functioning Web UI but don't check for it #3139

Closed

jhiemstrawisc requested changes

View reviewed changes

Member

jhiemstrawisc left a comment

Very solid first draft! Most of my nits are pretty small, but I think this would go a long way if it were merged as is.

docs/app/federating-your-data/globus-backend/page.mdx Outdated

Comment on lines 19 to 21

+              - The Collection UUID
+              - A Globus confidential OAuth client (client ID and client secret)
+              - A correct callback URL registered in Globus for your Origin web UI

Member

jhiemstrawisc Feb 18, 2026

I think it's a bit confusing to call these prerequisites and then cover how to get each one. It feels more correct to say that the only prerequisites are a working Pelican installation and a globus collection -- the rest you explain as part of the setup.

Contributor Author

whwjiang Feb 23, 2026

I left only the "Globus Collection" prereq, as someone doesn't necessarily need a Pelican installation to do this setup

docs/app/federating-your-data/globus-backend/page.mdx Outdated

+              Each Globus Collection has a UUID shown on its Collection overview page.
+              You will use this value `Origin.GlobusCollectionID` for single-export config.
+              This can be found by going to the  "File Manager - Collection Search" tab in the Globus web UI (https://app.globus.org/file-manager/collections), searching for your collection, going to the collection overview, and copying the UUID listed at the very bottom.

Member

jhiemstrawisc Feb 18, 2026

A picture is worth a thousand words -- can you provide a few screen grabs that show how to navigate these pages in the Globus web app?

Contributor Author

whwjiang Feb 23, 2026

I didn't include screenshots for this, but I did link the setup documentation from Globus about it

docs/app/federating-your-data/globus-backend/page.mdx Outdated

+              When registering the client:
+              - Choose or create a Globus project
+              - Use any app name

Member

jhiemstrawisc Feb 18, 2026

They should probably use an app name that says something descriptive about the Globus Origin they're trying to set up.

docs/app/federating-your-data/globus-backend/page.mdx Outdated

+              - Use any app name
+              - Add a redirect URL matching your Origin web UI callback path:
+                - `https://<origin-hostname>:<web-port>/view/origin/globus/callback`
+                - Example with defaults: `https://localhost:8444/view/origin/globus/callback`

Member

jhiemstrawisc Feb 18, 2026

I don't think this example with localhost is all that helpful because no real user will ever wind up generating something against localhost like this. In the past we've generated confusion by doing this. If you want to provide an example here, make up a hostname like https://my-osdf-globus-origin:8444/view/origin/globus/callback.

Additionally, can you reference the various Pelican config knobs that correspond to <origin-hostname> and <web-port> with links to their documentation? They should be:

Server.WebPort: https://docs.pelicanplatform.org/parameters#Server-WebPort
Server.Hostname: https://docs.pelicanplatform.org/parameters#Server-Hostname
OR Server.ExternalWebUrl: https://docs.pelicanplatform.org/parameters#Server-ExternalWebUrl

If you need an explanation of how/why the webport/hostname knobs are used slightly differently than the external web URL, let me know -- some of that nuance may be important here for containerized deployments.

docs/app/federating-your-data/globus-backend/page.mdx


		- https://app.globus.org/settings/developers/registration/confidential_client/select-project

		When registering the client:

Member

jhiemstrawisc Feb 18, 2026

Can you also provide a few screenshots of what these steps look like?

Contributor Author

whwjiang Feb 23, 2026

Yes

docs/app/federating-your-data/globus-backend/page.mdx Outdated

+. Complete Globus login and consent.
+. Return to Pelican and confirm the collection shows as active.
+              Activation authorizes the Pelican origin's client to access the collection on behalf of whoever is doing the setup.

Member

jhiemstrawisc Feb 18, 2026

Can you capitalize "origin"?

docs/app/federating-your-data/globus-backend/page.mdx Outdated


		## 4. Verify Data Access

		Note that it may take a few minutes for the Pelican origin to reboot after activation. After this occurs, test core operations from the exported namespace using a Pelican client:

Member

jhiemstrawisc Feb 18, 2026

Can you stick to one sentence per line outside of lists/enumerations and capitalize origin?

docs/app/federating-your-data/globus-backend/page.mdx Outdated

+              For operators troubleshooting production setup, this is the backend flow:
+              - Pelican authenticates the admin through Globus OAuth and stores tokens for collection access.
+              - Pelican persists token material under `Origin.GlobusConfigLocation/tokens`.

Member

jhiemstrawisc Feb 18, 2026

How about ${Origin.GlobusConfigLocation}/tokens?

docs/app/federating-your-data/globus-backend/page.mdx Outdated

+              ## Troubleshooting Checklist
+              - Callback mismatch:
+                - Ensure the registered Globus redirect exactly matches `https://<host>:<web-port>/view/origin/globus/callback`.

Member

jhiemstrawisc Feb 18, 2026

Small nit: however you end up modifying what's currently line 43 to include the Pelican params that set these values, can you make this URL consistent with that URL? Right now the former has <origin-hostname> while this one has <host>, but both should probably be something like https://${Server.Hostname}:${Server.WebPort}/blah or https://${Server.ExternalWebUrl}/blah

docs/app/federating-your-data/globus-backend/page.mdx

+              - Callback mismatch:
+                - Ensure the registered Globus redirect exactly matches `https://<host>:<web-port>/view/origin/globus/callback`.
+              - Inactive collection after restart:
+                - Verify `Origin.GlobusConfigLocation` is writable and persistent enough for runtime tokens.

Member

jhiemstrawisc Feb 18, 2026

We should check in with @h2zh after he gets back from vacation to see what "writable" means in the context of his "drop privs" mode.

Member

jhiemstrawisc commented Feb 18, 2026

@CannonLock, @whwjiang has asked that this be back-versioned into the v7.24 releases at some point since that's when all these features were technically made available. With our versioned docs, do we have a way to update a specific version's documentation without having to create a new release? That is, all the stuff William describes here will be available as of v7.24.0, but I'm not sure whether the documentation will cross the finish line before I cut that release. Do we have an override mechanism that would allow me to update the v7.24.0 docs without having to create a v7.24.1 solely for documentation?


          fix linter issue

3dc5c03

turetske requested changes

View reviewed changes

Collaborator

turetske left a comment

@whwjiang @jhiemstrawisc I agree with Justin's remarks. Most of my hangups were more my lack of familiarity with Globus rather than the documentation itself.

Contributor

CannonLock commented Feb 19, 2026

Do we have an override mechanism that would allow me to update the v7.24.0 docs without having to create a v7.24.1 solely for documentation?

No, you will have to make a release.


          first round of feedback

b0a7587

whwjiang requested a review from jhiemstrawisc

February 23, 2026 15:33


          fail-stop multiple origin config for globus (for now)

1e53021

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels