Install

Install LancerLogin

Create a private deployment repository, connect your Cloudflare account, and run the installation workflow. Plan for about 30 minutes.

Before you start

1. Create your private repository

  1. Open Create a repository from the LancerLogin template. This page starts from the public isriah/LancerLogin template with Private already selected.
  2. Choose the owner and a repository name, keep Private selected, and select Create repository.
GitHub Create a new repository page starting from the isriah/LancerLogin template, with Include all branches off, a repository name entered, visibility set to Private, and the Create repository button.
Start from the template and keep the visibility on Private.

Keep it private and do not fork. The private repository holds your deployment history and secrets. The installation workflow refuses to run in a public repository, even when the secrets are present.

2. Create the production environment

  1. In your private repository, open Settings › Environments › New environment.
  2. Enter the exact name production and select Configure environment.
  3. Required reviewers are optional and depend on your GitHub plan. When they are set, each installation or update run waits for a reviewer to approve it. Leave the branch and tag rules unchanged.
GitHub repository settings at Environments / Add, with production entered in the Name field and the Configure environment button.
1

Use the exact name

Enter production. The installation and update workflows look for this environment.

2

Secrets go here

The secrets and variables in the next steps belong to this environment, not to the repository.

3. Create the Cloudflare API token

  1. Sign in to Cloudflare and select the account that will own this installation.
  2. Open Manage account › Account API tokens › Create Token. Cloudflare's account API token guide describes the same page.
  3. Give the token a name you will recognize, such as LancerLogin deployment. The name is only a label for you.
  4. Under Permission policies, select Start from scratch. The ready-made templates grant either more or less than LancerLogin needs.
Cloudflare Create token page with the token name LancerLogin deployment, permission policy choices including Start from scratch, Read all resources, Write all resources and Edit Cloudflare Workers, token expiration choices, and client IP address filtering.
Name the token, choose Start from scratch, and pick an expiration on the same page.
  1. Keep the scope on Entire Account. The token covers only the one account you selected. Then add exactly these four permissions, searching for each group by name:
Permission groupAccessWhy LancerLogin needs it
Workers ScriptsEditDeploy and update the API Worker. Cloudflare labels this permission group "Legacy". Use it anyway.
D1EditCreate the database and apply its migrations.
PagesEditCreate and update the dashboard project.
Account SettingsReadConfirm that the token belongs to the account you selected.
Cloudflare Edit policy panel scoped to Entire Account, searching for Workers Scripts. The newer Workers group with Metadata Read-only, Content Read-only, Editor and Admin options is unchecked, and the Workers Scripts group marked Legacy has Edit checked.
Search shows a newer Workers group above Workers Scripts. Leave the newer group unchecked and check Edit on Workers Scripts (Legacy).
  1. Choose an expiration that suits your organization. Leave IP filtering empty. When the token expires, create a new one and replace the GitHub secret before the next update.
  2. Continue to the Review token page. It lists the permissions as Workers Scripts Write, D1 Write, Pages Write, Account Settings Read. Cloudflare shows the level you chose as Edit as "Write" here; that is expected. Go back if anything else appears.
  3. Select Create token and copy the value immediately. Cloudflare shows it only once. The value starts with cfat_. Keep the page open until you have saved it in GitHub.
Cloudflare Review token summary for LancerLogin deployment with a 7-day expiration, permission policies Workers Scripts Write, D1 Write, Pages Write and Account Settings Read, all IP addresses allowed, and the Create token button.
The review page lists exactly four permissions.

Do not add zone, DNS, billing, or member permissions. LancerLogin does not need them.

4. Copy the Cloudflare Account ID

  1. On any Cloudflare dashboard page, press Ctrl+K (Command+K on macOS) to open quick search.
  2. Type Copy account ID and select that command. It copies the 32-character account ID. A zone ID will not work.
Cloudflare quick search showing the Copy account ID command without revealing the identifier.
1

Use the command

Quick search finds the account ID without hunting through account pages.

2

Account, not zone

The workflow checks the account ID against the token before it creates anything.

5. Add the environment secrets

Open Settings › Environments › production. Under Environment secrets, select Add environment secret once for each row. Enter the exact name and paste the value, then select Add secret.

GitHub Configure production page with the Add secret dialog open, the name CLOUDFLARE_ACCOUNT_ID entered, an empty Value field, and the Add secret button.
Add each secret to the production environment.
Secret name (exact)RequiredValue
CLOUDFLARE_API_TOKENYesThe token value from step 3 (starts with cfat_), not its name.
CLOUDFLARE_ACCOUNT_IDYesThe account ID from step 4.
LANCERLOGIN_SETUP_CODEYesA new random value of at least 16 characters from your password manager. You enter it once, when you create the first Admin.
LANCERLOGIN_WEB_UPDATE_TOKENOptionalA GitHub token that enables one-click dashboard updates. See Set up one-click updates. You can add it now or later.
GitHub Configure production page listing four environment secrets: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, LANCERLOGIN_SETUP_CODE and LANCERLOGIN_WEB_UPDATE_TOKEN, with no environment variables yet.
The production environment with the three required secrets and the optional update token.

Use secrets, not variables. GitHub never shows a saved secret again. You can replace one later. The setup code protects first-Admin creation only. It is not the Admin password.

You can change LANCERLOGIN_SETUP_CODE later while no Admin exists yet. Update the secret, then run the workflow again with operation resume and the same slug to apply it.

6. Run the installation workflow

  1. In your private repository, open Actions › Install or upgrade LancerLogin › Run workflow.
  2. For operation, choose create.
  3. For release, keep latest stable, the only choice. The workflow installs the newest public LancerLogin release.
  4. For installation_slug, enter a name for this installation, such as example-robotics-team. It must start with a lowercase letter and be 3 to 41 characters of lowercase letters, numbers, and hyphens.
  5. Select Run workflow. If the environment has required reviewers, approve the pending production deployment.
GitHub Actions page for Install or upgrade LancerLogin with the Run workflow panel open: branch main, operation create, release latest stable, and installation slug example-robotics-team.
Run the workflow with operation create.

Before it creates anything, the run checks your inputs and secrets with read-only requests: the token's permissions, that the account has a workers.dev subdomain, and that the dashboard address is free. It then builds LancerLogin and creates the Cloudflare resources only after the builds succeed. If a check fails, the run stops with an error that names the problem and the fix; see Troubleshoot the installation workflow.

The slug names the three Cloudflare resources the workflow creates:

ResourceName
API Worker<slug>-api
D1 database<slug>-data
Pages dashboard<slug>-dashboard, served at https://<slug>-dashboard.pages.dev

Pages addresses are global across Cloudflare. If another account already uses <slug>-dashboard.pages.dev, the run stops and asks for another slug. If a run is interrupted, run the workflow again with operation resume and the same slug; it finishes the interrupted installation.

7. Save the installation variables

When the run succeeds, its summary shows the release, the dashboard and Worker API links, and a table of Environment variables for future updates. The workflow cannot set these itself, so save them now:

GitHub run summary titled LancerLogin create complete, showing Release v2.0.0, the Dashboard and Worker API links, and an Environment variables for future updates table with LANCERLOGIN_INSTALLATION_SLUG, LANCERLOGIN_DATABASE_ID and LANCERLOGIN_API_URL values.
The run summary lists the three variables to add.
  1. Open Settings › Environments › production and select Add environment variable.
  2. Add each variable with the value from the run summary:
Variable name (exact)Value
LANCERLOGIN_INSTALLATION_SLUGThe installation slug.
LANCERLOGIN_DATABASE_IDThe D1 database ID.
LANCERLOGIN_API_URLThe API Worker address.

Then open the dashboard link and continue with First sign-in and setup.

Optional: Google sign-in

Admins and Operators can sign in with a username and password, with Google, or with either. You only need this section if you plan to choose Google OAuth or Both methods when you create the installation, or to add Google sign-in later in Settings › Integrations. Google Calendar is set up separately; see Connect Google Calendar. Google calls the configuration area Google Auth Platform. Its sections are Branding, Audience, Clients, Data Access, and Verification Center. Google's Google Auth Platform overview describes the same flow.

Choose the project, branding, and audience

  1. Open Google Auth Platform. Select a project your organization owns, or create one and choose Get started.
  2. Under Branding, use a recognizable app name, select a support email, and add a monitored developer contact email. Google's branding guide explains when a logo, homepage, privacy policy, or brand verification is required.
  3. Under Audience, choose Internal only when every dashboard user belongs to the project's Google Workspace or Cloud Identity organization. Otherwise choose External.
  4. For an External audience, Testing is for a trial and In production publishes the app for ongoing use. Review Google's audience and publishing status guide before deciding. Workspace administrator policy can still block access.
  5. For an External audience in Testing, add each Admin and Operator Google account under Audience › Test users. Otherwise Google shows "Access blocked" when they sign in.

Keep Data Access limited to sign-in

Under Data Access, keep only openid, email, and profile. Do not add Drive, Calendar, Gmail, or other scopes to the sign-in client. Google Calendar uses its own client, ideally in its own project. Google's Data Access guide explains scope management.

Create the Web application client

  1. Under Clients, choose Create client and select Web application. Do not create a Desktop client and do not add an Authorized JavaScript origin.
  2. Under Authorized redirect URIs, add your installation's callback address. It has this form:

Callback address › https://<slug>-dashboard.pages.dev/api/auth/google/callback

The Create your installation form and Settings › Integrations show the exact value the API uses, with a copy button. Google compares it exactly, including the trailing slash. The address must use https. Only a localhost or 127.0.0.1 preview may use http.

  1. Create the client and save the client ID and client secret in your password manager. Google shows a new secret only once. Google's Clients guide covers creating and rotating secrets.
  2. Enter the client ID, the client secret, and the first Admin's Google email in the Create your installation form. To add Google sign-in later, enter the client ID and secret in Settings › Integrations, and add each person's Google email in Settings › Access. LancerLogin encrypts the secret and never displays it again.
Google Auth Platform Create OAuth client ID page with Application type Web application, the name LancerLogin dashboard, no Authorized JavaScript origins, and an Authorized redirect URI beginning https://example-robotics-team-dashboard.pages.dev/api/auth/google/.
A Web application client with the installation's callback address as the only redirect URI.

Finish verification

Google's Verification Center and LancerLogin's integration verification are separate. An External app in production may need Google brand verification before its name or logo appears. LancerLogin's basic sign-in scopes do not need sensitive-scope review. After you save credentials in Settings, choose Verify with Google and sign in with the Google account of an active Admin. That Google email must match the Admin's LancerLogin email. If you created the installation with Username and password, first add the Admin's Google email in Settings › Access. LancerLogin marks Google sign-in as configured only after that sign-in succeeds. If it fails, the card in Settings › Integrations explains why.

Google sign-in can be turned off or removed only while at least one active Admin can sign in with a password.