CMS Login Setup Guide

What this does and why it exists

The CMS admin panel at /admin lets editors update content on the site without touching code. To save changes, the CMS needs to log into GitHub on the editor's behalf — but GitHub's login process requires a secret key that cannot safely be stored in the browser.

The solution is to deploy a tiny relay service called an OAuth worker. It runs on Cloudflare's infrastructure (not on the website's hosting), receives the login request, exchanges it for a token using the secret, and hands the token back to the browser. The editor never sees any of this — they just click "Login with GitHub" and it works.

The setup has seven steps. Steps 1–3 are done once by whoever creates the Cloudflare account. Steps 4–7 are done by the developer (or together in a shared screen). Total time: about 20 minutes.

Step 1 — Create a Cloudflare account (client)

The OAuth worker lives in a Cloudflare account. The free tier is more than enough — there is no charge for this use.

1. Go to dash.cloudflare.com/sign-up.
2. Click "Continue with GitHub", or enter an email address and create a password. Either works — use whichever is easier to remember.
3. Complete email verification if prompted.
4. You will land on the Cloudflare dashboard. No domains or plans need to be added — skip any prompts to add a site.

If a Cloudflare account already exists for this business, skip to Step 2 and use that account instead of creating a new one.

Step 2 — Invite the developer as a collaborator (optional)

If the developer will be doing Steps 3–5 (recommended), invite them to the Cloudflare account so they can deploy and configure without needing the client's login credentials.

1. In the Cloudflare dashboard, click the account name in the top-left corner.
2. Go to Manage Account → Members.
3. Click Invite Member and enter the developer's email address.
4. Set the role to Administrator (needed to deploy Workers).
5. Send the invite. The developer will receive an email to accept it.

Once the worker is live and confirmed working, you can remove the developer from the account or reduce their role to read-only if preferred.

Step 3 — Deploy the OAuth worker (one click)

The worker code is open source and maintained by the Sveltia CMS project. Cloudflare provides a one-click deploy button that installs it directly into the account — no coding or command line required.

1. Open this URL in a browser where you are logged in to the Cloudflare account created in Step 1:
   deploy.workers.cloudflare.com/?url=https://github.com/sveltia/sveltia-cms-auth
2. Click Deploy. Cloudflare will ask you to authorize it to access your account — click Allow.
3. After a few seconds the worker is live. The page will show a Worker URL that looks like:
   https://sveltia-cms-auth.yourname.workers.dev
4. Copy this URL and save it. You will need it in Steps 4 and 6. Do not include a trailing slash.

Step 4 — Create a GitHub OAuth App

GitHub needs to know about this worker before it will let it handle logins. This is done by creating an OAuth App in GitHub — it takes about two minutes.

1. Log in to GitHub and go to:
   github.com/settings/applications/new
   This should be done under the finnick-dev organization account, or the GitHub account that owns the site repository.
2. Fill in the fields:

   Application name	TNF CMS Login
   Homepage URL	https://tahoeneurofeedback.com
   Authorization callback URL	https://sveltia-cms-auth.YOURNAME.workers.dev/callback

   Replace YOURNAME in the callback URL with the actual subdomain from your Worker URL in Step 3. The /callback path must be exact.

3. Click Register application.
4. On the next page, note the Client ID — you will need it shortly.
5. Click Generate a new client secret. Copy the secret immediately — GitHub only shows it once. Paste it somewhere temporary (a notes app) until Step 5 is done.

Step 5 — Add the secrets to the Worker

The worker needs the Client ID and Client Secret from Step 4 to complete the GitHub login exchange. These are stored as encrypted environment variables in Cloudflare — they are never visible in the browser.

1. In the Cloudflare dashboard, go to Workers & Pages → click sveltia-cms-auth → Settings → Variables and Secrets.
2. Add the following variables. For GITHUB_CLIENT_SECRET, use the Secret type so Cloudflare encrypts it at rest.

   Variable name	Value	Type
   GITHUB_CLIENT_ID	From Step 4	Text
   GITHUB_CLIENT_SECRET	From Step 4	Secret
   ALLOWED_DOMAINS	tahoeneurofeedback.com	Text

3. Click Save and deploy (or Deploy if prompted after saving). The worker redeploys with the secrets applied.

Once this step is done, you can safely delete the Client Secret from wherever you temporarily stored it. It is now encrypted inside Cloudflare.

Step 6 — Update the site config and deploy

The CMS configuration file needs to know the Worker URL so it knows where to send the login request. This is a one-line change made by the developer.

1. In the site repository, open public/admin/config.yml.
2. Find the line that reads base_url: PLACEHOLDER_WORKER_URL and replace it with the Worker URL from Step 3:

   backend:
     name: github
     repo: finnick-dev/tnf-web
     branch: main
     base_url: https://sveltia-cms-auth.YOURNAME.workers.dev

3. Commit the change and push to main. The CI/CD pipeline will build and deploy the site automatically, and the updated config.yml will go live at tahoeneurofeedback.com/admin/config.yml.

Step 7 — Test production login

1. Wait for the CI deploy from Step 6 to finish (usually under 2 minutes — check the GitHub Actions page).
2. Open tahoeneurofeedback.com/admin in a browser.
3. Click Login with GitHub. GitHub will ask you to authorize the OAuth App created in Step 4 — click Authorize.
4. The CMS should open. Make a small test edit (e.g. change one word in a FAQ answer) and click Save.
5. Confirm the commit appears on GitHub: github.com/finnick-dev/tnf-web/commits/main . A new commit from your GitHub username should appear within seconds of saving.

Troubleshooting