Lagniappe installs into your own Google Cloud project. The setup script guides you through connecting the services it needs and deploying the app.

Setup is the most hands-on part of using Lagniappe, but the installer explains each choice and opens the right provider pages along the way. The steps below cover what to have ready before you begin.

Services Used

  • App Engine for hosting the app.
  • Datastore for app data.
  • Cloud Storage for uploaded files and documents.
  • Cloud Tasks for background work.
  • Document AI for OCR when enabled.
  • Vertex AI for optional AI features.
  • Google Identity Platform for sign-in and adaptive polling for live updates.
  • Google Places for address autocomplete and verified location details in location fields.
  • Email through Gmail, Google Workspace, or an email provider for your custom domain.
  • Redis for search, filters, and live collaboration.
  • Cloudflare optionally, to help connect a custom domain automatically.

Prerequisites

Accounts

  • Google Cloud: a regular Gmail address is enough; you do not need to create a separate Google Cloud identity, project, service account, or App Engine application beforehand. Sign in to Manage billing accounts with that Gmail address. If Google presents its first-time Cloud setup, accept the terms and follow it; otherwise choose Create account. Enter the requested country and payments-profile details, add a payment method, then choose Submit and enable billing.
    You are ready when the Billing page lists an active Cloud Billing account. A free-trial or paid billing account can be linked to a project; even Google services with free usage allowances require an active billing account. Stop there—the Lagniappe installer creates the project, links this billing account, enables its APIs, and creates the cloud resources in the right order. Google’s billing-account guide has screenshots and country-specific details if your screen differs.
  • Email, if you are not using a custom domain: a Gmail or Google Workspace mailbox that Lagniappe can use to send account verification and password-reset messages. Before running setup, open Google's 2-Step Verification instructions, go to Security & sign-in, then How you sign in to Google, choose Turn on 2-Step Verification, and follow Google’s prompts.
    Why: a second sign-in step protects the mailbox if its password is stolen, and Google only allows you to create the separate 16-character App Password that Lagniappe needs after 2-Step Verification is enabled. During setup, you create an App Password named Lagniappe; the installer tests and saves that dedicated password, never your normal Google password. Work or school administrators can disable App Passwords, in which case use a custom-domain email provider or ask the administrator to enable them.
  • Redis Cloud: you do not need to create this account before starting. When setup reaches Redis, it opens the Redis Cloud console and walks you through creating or signing in to an account, creating or choosing a database, and locating its public endpoint and default-user password. You copy those two values back into the terminal, and setup tests the connection before saving anything. The Redis Cloud quick start shows the same account and database screens if you want to preview them.
  • Cloudflare, optional: an account and temporary API token if you want automatic custom-domain setup

Install Git and Google Cloud CLI

Git downloads the Lagniappe source code. Google Cloud CLI lets the setup script work in your Google Cloud account. Install both before continuing; you do not need to know Git beyond the commands in this guide.

Windows

  1. Download and run Git for Windows. The installer has several screens; its default choices are fine for Lagniappe. Finish the installer, then close and reopen PowerShell.
  2. Download and run the Google Cloud CLI installer. Keep the bundled Python option selected. The other default choices are fine. Finish the installer, then close and reopen PowerShell.
  3. Verify both tools in the new PowerShell window:
git --version
gcloud.cmd --version

macOS

  1. Open Terminal and check whether Git is installed:
git --version

On a new Mac, this opens Apple’s Install Command Line Developer Tools app, which includes Git. If its window does not appear, click its icon in the Dock. Choose Install, accept the license, and wait for the installation to finish. Then run the same command again. If it displays a Git version immediately, Git is already installed.

  1. Check whether the installed Python version is ready for Lagniappe:
python3

Python displays its version and then a >>> prompt. Type exit() and press Enter to return to the normal Terminal prompt. If the displayed version is 3.12 or newer, continue. If it is 3.11 or older, or the command is not found, download and run Python.org's current macOS installer, then close and reopen Terminal and run the check again.

  1. Run Google’s interactive Cloud CLI installer. Accept the default install folder and answer Y when it asks to add gcloud to your PATH. When installation finishes, close and reopen Terminal, then verify the command. This works from macOS’s standard zsh Terminal; /bin/bash runs only Google’s installer and does not change your shell: 
curl https://sdk.cloud.google.com | /bin/bash
gcloud --version

On Linux, use your distribution’s package manager for Git and follow the Google Cloud CLI package instructions for your distribution.

Lagniappe keeps its Python software isolated. The setup launcher creates a venv folder inside the Lagniappe checkout and installs all Lagniappe Python packages there. It does not install those packages globally or alter another virtual environment. Git and Google Cloud CLI remain normal system tools.
Lagniappe needs Python 3.12 or newer. The macOS steps above check Python before installing Google Cloud CLI. On Windows, setup can offer to install a supported standalone Python with WinGet if one is not already available.

Delegated Installation

When a consultant, developer, or other outside installer deploys Lagniappe, the business keeps permanent ownership and the installer receives broad access only to a new, empty project. Use the two checklists below separately: each person should open only the list for their role.

Google Workspace and Google Cloud are separate services. Workspace owns the business email accounts; Google Cloud owns the project, billing, and access controls used to run Lagniappe. No prior Google Cloud experience is required—the checklist names each page and button.
Business / permanent Owner Create and fund the project, create the installer account, grant temporary access, and close the handoff.

Complete steps 1–8 before the installer begins. Return to steps 9–13 after the app is deployed to take over and close temporary access. You will need help from your Workspace administrator for steps 2–3 if you do not manage the business’s Google accounts yourself.

Before the installer starts

  1. Choose the permanent Owner account

    Choose one permanent, business-controlled Google account to be both the Lagniappe primary Owner and a Google Cloud Project Owner. These are separate roles, but the same durable business identity should hold both.

  2. Create a temporary account for the installer

    In Google Admin Console / Directory / Users / Add new user, create a dedicated temporary installer account.

    • Enter a secondary delivery email and assign no Workspace administrator role.
    • Give the initial sign-in information only to the installer.
    • Ask them to change the temporary password and enroll in 2-Step Verification.

    See Google’s user-creation instructions.

  3. Allow the installer account to use Google Cloud

    As a Workspace administrator, open Apps / Additional Google services / Google Cloud Platform / Service status. Select All users in this account, then check:

    • ON for everyone: the installer already inherits access. Leave the setting unchanged and close or cancel the page.
    • Otherwise: select the organizational unit containing the installer. Inherited: On or On needs no change. If it is off, select On, then Override or Save.

    Changes usually apply quickly but can take up to 24 hours. Google’s service-settings instructions explain inherited and overridden settings. This does not grant Workspace administrator or Cloud project access. The installer does not need permission to create projects; the business creates the empty project in step 5.

  4. Accept the Google Cloud and Maps terms

    Use the permanent Owner’s browser profile for both pages:

    Lagniappe uses Places for address autocomplete and location verification. Google records acceptance against the account that activates the API, so the installer’s second acknowledgement is required; setup will enable Places API itself.

  5. Create an empty project and record its ID

    In the Owner’s browser profile, open the Google Cloud console.

    • Open Manage Resources / Create Project, select the business organization, name the project, and select Create.
    • Select the new project in the project picker. On its Dashboard, use Project info to confirm the name, project number, and project ID. Then record the exact Project ID for the installer.

    If creation is blocked, ask the business’s Workspace administrator to create the project inside the business organization. Google’s create-project instructions show these screens.

  6. Enable billing on the new project

    With that project selected, open Navigation menu / Billing. A Workspace subscription does not automatically create a Cloud Billing account.

    • If no Cloud Billing account exists, choose Manage billing accounts / Create account and add the business’s payment details.
    • Link the billing account to the project and confirm on the Billing page that billing is enabled before the installer runs setup.

    See Google’s billing-status instructions.

  7. Give both accounts direct Project Owner access

    With the new project still selected, use the search box at the top of Google Cloud console to search for IAM. Open IAM under IAM & Admin. If search does not find it, use Navigation menu / IAM & Admin / IAM.

    • Permanent Owner: in View by principals, find the Owner’s email. Confirm it has Basic / Owner on this project directly, with no inherited source or condition. An inherited organization role on another line is fine, but the Owner line itself must have no entry in Inheritance. If needed, select Grant access, add the permanent Owner, assign Basic / Owner, and Save.
    • Temporary installer: select Grant access. Enter the temporary Workspace email under New principals, choose Basic / Owner under Assign roles, and Save.

    This gives the installer broad access, confined to the new, empty project and removed at handoff. Google’s grant and revoke instructions cover adding and removing these roles.

  8. Send the installer the project and Owner details

    Give them the exact Cloud Project ID and the permanent Lagniappe Owner’s exact Google account email. Never give the installer the Owner’s Google password.

    Keep billing, the authentication-email mailbox, Redis, Cloudflare or domain control, and recovery ownership in permanent business accounts. Invite the installer only where a setup step requires it.

After the app is deployed

  1. Save your configuration and remove in-app installer access

    Sign in to Lagniappe as the permanent Owner:

    • Download a secure configuration backup from Admin / Site Settings / Maintenance / Configuration.
    • Remove the installer’s Lagniappe Administrator role and confirm the Remove Administrator dialog, or permanently delete their application account from Users.

  2. Have the installer complete the handoff

    Ask the installer to run the handoff command from the existing installation working copy:

    macOS / Linux

    ./setup.sh handoff

    Windows PowerShell

    .\setup.cmd handoff

    If the installer is unavailable: the permanent Owner can run handoff instead. On a separate computer, first follow Recover an Existing Installation below with the downloaded lagniappe_settings.yaml. Complete recovery setup while authenticated as the permanent Owner, then run the same handoff command.

    Handoff accepts either the saved Installer or permanent Owner identity; it never requires the installer’s password.

After handoff succeeds

  1. Verify the handoff and project access

    Open Admin / Site Settings / Installation Access:

    • Confirm it reports Application handoff configured.
    • Use Review project IAM to verify that the installer is absent from project IAM. The application’s saved state cannot prove that external cleanup finished.

  2. Check whether email still uses the installer mailbox

    Review the authentication-email dependency under Installation Access. If email already uses a permanent business account, continue to step 13.

    If it says to keep the installer mailbox active: replace that sender before suspending or deleting the Workspace account. Run the email command from the installation working copy, choose a durable business-controlled sender, and deploy the change:

    macOS / Linux

    ./setup.sh email

    Windows PowerShell

    .\setup.cmd email

    Without a custom application domain, this opens Google App Passwords and defaults to the permanent Owner’s Gmail or Workspace address. It tests the replacement before saving and offers to deploy. With a custom domain, it guides the configured SMTP-provider path instead.

  3. Remove remaining access and retire the temporary account

    • Remove the installer’s account access and invitations from billing, Redis Cloud, Cloudflare or DNS, Resend, and any other provider where they were invited. Revoke temporary access tokens.
    • Confirm the installer removed local credentials and settings from their machine.
    • Securely transfer or delete installer-held configuration backups and exported archives stored outside Lagniappe’s managed Google Cloud buckets.
    • Rotate any provider secret that could not stay under direct business control during installation.
    • Only after email and access cleanup: suspend and ultimately delete the temporary Workspace user.
The business remains responsible for Workspace users, billing IAM, organization-level access, and provider accounts. The handoff command deliberately does not change or delete them, and the deployed application is not authorized to remove human Google Cloud IAM.
Installation Access is shown only for delegated installations where the saved Installer and permanent Owner are different accounts. Owner-installed sites do not display that section or return its identity payload.
Installer Activate the temporary account, run setup, verify the deployment, and return access.
  1. Sign in with the dedicated temporary Workspace account, change its temporary password, and enroll it in 2-Step Verification. Use a separate browser profile containing only this account; never ask for or use the permanent Owner’s password.
  2. In that installer-only browser profile, open the Google Cloud console. If Google displays a welcome agreement, confirm the account shown is the temporary installer, select the business’s country, select the agreement checkbox, and choose Agree and continue. You do not need to select Start free; the business has already linked billing to its project. Do not create a project or manually enable any APIs. If setup later finds another account-specific agreement, it opens the exact terms page, tells you which account must be active, waits for you to complete it, and then retries API activation itself. Complete the Maps acknowledgement only after the permanent Owner has reviewed the agreement and explicitly authorized you to do so.
  3. Clone Lagniappe and follow Authenticate with Google Cloud below using the temporary account. Before setup asks about installation type, it displays the active gcloud CLI email. Confirm it only if it is the temporary installer address. If it is wrong, answer N, rerun gcloud auth login, choose the temporary account, and restart setup. Setup verifies that account’s CLI token before showing any project choices.
  4. When setup asks Are you installing Lagniappe for a different permanent Owner?, answer Y. Setup lists only active projects where the authenticated installer has a direct, unconditional Project Owner role. Select the business’s project by number. Setup uses the project’s name as the installation name and never offers project creation in delegated mode. If the project is missing, ask the business to verify your direct Basic / Owner role in project IAM, then rerun setup.
  5. Enter the permanent Owner’s exact Google account email. Setup verifies the existing direct Owner binding, automatically enables Google Sign-In, and gives the confirmed installer temporary Lagniappe Administrator access. These are required parts of the delegated flow, so setup does not ask additional yes-or-no questions for them.
  6. Complete the remaining guided provider and deployment steps. Use business-controlled accounts or temporary invitations supplied by the business. After deployment, sign in to Lagniappe with the temporary installer account. The initial setup screen says that either the configured application Owner or delegated installer may continue with Google. The temporary installer bootstrap is Google-only, while the permanent Owner may instead choose the separate-password path. Verify the app, then ask the permanent Owner to sign in and take their configuration backup.
  7. After the Owner confirms application control and removes your Lagniappe Administrator access, authenticate the installation working copy as the saved installer and run ./setup.sh handoff, or .\setup.cmd handoff in Windows PowerShell. The command previews the Owner, installer, project, service account, buckets, and IAM changes, then asks for default-no confirmation. It grants managed-resource access to the permanent Owner, deploys the closed bootstrap configuration, and removes your direct project IAM only as its final cloud change. When it succeeds, securely remove the checkout’s local credentials and settings as directed by the business.

Running the Commands

Use Copy in any dark command box, paste the command into your terminal, and press Enter. You can still select and copy the text manually if you prefer.

On Windows, use PowerShell. On macOS or Linux, use your usual terminal.

Windows installation and recovery use setup.cmd. macOS and Linux use setup.sh.
If a command says “not found” or “not recognized”, check that the named tool is installed, then open a fresh terminal and try again.

What the Setup Script Does

Here is the order to expect. Setup is safe to rerun after an interruption: it discovers existing resources before creating or updating them.

  1. Prepare the local environment. The launcher creates or reuses the checkout’s private venv, verifies Python and Google Cloud CLI, and installs the Python packages setup needs.
  2. Choose and verify the Google Cloud target. Setup first displays the active gcloud CLI account, requires you to confirm its exact email, and verifies its login. It then asks whether this is a delegated installation. A delegated installer chooses from active projects they own directly; setup never offers to create one for them. For your own installation, setup asks whether the project already exists. Answering yes opens a picker of active projects visible to your account; answering no asks for an installation name and allows setup to create a project. It then checks billing, opens the Application Default Credentials browser sign-in, and verifies that the CLI and local Google clients use the same account and project.
  3. Show the plan before cloud changes. Setup writes a local draft, displays the selected identities and project, and asks you to continue. New cloud resources are not created until you approve this summary.
  4. Build the cloud foundation. Setup creates or verifies the project and billing link, enables the required APIs, creates the keyless runtime service account, and provisions App Engine. It then creates Storage buckets, the background task queue, and the OCR processor. App Engine comes first because its permanent location and hostname are needed by later authentication settings.
  5. Connect application services. Setup walks through authentication email, Identity Platform, the administrator and Google OAuth client, Redis, and optional monitoring and AI settings. Provider pages open only when a browser step is required.
  6. Save and optionally deploy. Setup writes the private settings files, then can deploy the database indexes and application and configure background-job recovery.
Keep the terminal visible while setup runs. Longer operations announce an estimated maximum time. When setup needs you, it stops progress output and displays a question beginning with ?, followed by any answer choices or instructions. In yes/no choices, the capital letter shows what pressing Enter will select.

Installation

1

Clone the repository

In Windows PowerShell, use:

$lagniappePath = Join-Path $env:USERPROFILE "Lagniappe"
git clone https://github.com/windmillionaire/lagniappe.git $lagniappePath
Set-Location $lagniappePath

On macOS or Linux, use:

git clone https://github.com/windmillionaire/lagniappe.git lagniappe
cd lagniappe
2

Authenticate with Google Cloud

On macOS or Linux, this connects the terminal to your Google account:

gcloud auth login

In Windows PowerShell, use:

gcloud.cmd auth login

The command opens a browser. Later, setup opens a second Google sign-in for Application Default Credentials; the first authorizes the gcloud command, while the second authorizes the local Google client libraries used by setup.

Provider service terms are separate from both sign-ins. In the same browser profile as the installation account, open the Google Cloud console and complete any welcome agreement it presents. A new Cloud user can otherwise reach part of setup before API activation reports UREQ_TOS_NOT_ACCEPTED. Some services have an additional agreement; Lagniappe uses Google Places, which is governed by the Maps Platform terms. When setup encounters one, it opens the exact terms page, names the required account, waits for acceptance, and retries API activation itself. In a delegated installation, the permanent Owner first reviews and authorizes the Maps agreement as described above; the installer then completes Google’s account-specific acknowledgement with the temporary business account. Neither person manually enables Places API.

The second sign-in requests your basic Google account identity and access to manage Google Cloud resources. Lagniappe does not use Cloud SQL, and its setup command explicitly excludes Google Cloud CLI’s otherwise-default Cloud SQL login permission.

At the start of a fresh installation, setup displays the exact account marked active by this gcloud login and asks whether it is correct. Read the email rather than assuming the browser changed it. If it is wrong, answer N, rerun the command above, choose the intended installation account, and restart setup. Setup verifies the confirmed account before asking about installation type or listing projects.

If Google shows permission checkboxes or a Select all option during either sign-in, choose Select all before clicking Continue or Allow. Do not deselect individual permissions: Google supports partial approval, but every permission requested here is needed to configure, verify, or deploy your installation. The list should not include permission to connect to Cloud SQL instances.

In practical terms, you are granting these permissions to yourself: they let Google Cloud CLI and the setup code on your own computer act for you in your project. They do not give the Lagniappe maintainer access to your account, project, or credentials.
3

Run setup

This starts the guided installer. It asks a few questions, opens any provider pages you need, and explains what to copy or approve. You can review each step before setup deploys the app. 

./setup.sh

In Windows PowerShell, use:

.\setup.cmd

Setup guides you through the cloud project, sign-in, email, Redis, optional features, and deployment. If a provider requires a manual step, setup opens the right page and tells you exactly what to do.

Throughout setup, a value in brackets is the suggested default: pressing Enter accepts that exact value. In choice prompts such as [Y/n], the capitalized choice is the Enter default. App Engine creation can take up to five minutes, and the final deployment can take up to ten minutes; setup prints those estimates before it begins waiting.
A new deployment can become available before Google finishes building its Datastore indexes. If Lagniappe says database setup is still finishing, wait a few minutes and refresh; no repair or redeployment is normally required.

Settings File

Setup writes your installation settings to config/files/lagniappe_settings.yaml inside your Lagniappe checkout. This file contains secrets and provider configuration, so keep it private and do not commit it to a public repository. Git ignores it, but you should still keep a secure backup.

Alongside a fresh copy of the Lagniappe source code, this is the one local file you need to recreate the same installation. It does not contain your records or uploaded files. Once the app is running, the primary Owner can also view or download the current settings from Admin, Settings, Maintenance, then Configuration.

Recover an Existing Installation

The owner download is always named lagniappe_settings.yaml, even when the installation has a custom name. On macOS or Linux, use a clean checkout and save it at the exact path below: 

git clone <lagniappe-source>
cd <lagniappe-source>
mkdir -p config/files
# Save the owner download as:
# config/files/lagniappe_settings.yaml
./setup.sh

In Windows PowerShell, use a fresh Lagniappe checkout directly under your Windows user profile, matching the location used by a fresh installation: 

$lagniappePath = Join-Path $env:USERPROFILE "Lagniappe"
git clone <lagniappe-source> $lagniappePath
Set-Location $lagniappePath
New-Item -ItemType Directory -Force config/files
# Save the owner download as:
# config/files/lagniappe_settings.yaml
.\setup.cmd

Setup recognizes the downloaded settings file and uses it to rebuild the app without deleting or replacing its cloud data.

Check or Repair Setup

The doctor command checks the installation without changing anything. It reports any files, account settings, or cloud services that need attention. 

./setup.sh doctor

In Windows PowerShell, use:

.\setup.cmd doctor

The repair command reruns setup and fixes what it can: 

./setup.sh repair
.\setup.cmd repair

Cost and Maintenance

Light personal or small-team usage is usually inexpensive, though there is no fixed price. Cost depends on traffic, App Engine instance settings, your Redis plan, file storage, OCR, AI usage, and any changes in provider pricing.

A couple of habits keep things predictable: set Google Cloud budget alerts when you install, and check in on your Redis plan occasionally as your data grows.

Day to day, the app aims to stay out of your way. Every so often, cloud APIs, auth rules, or dependencies do shift in ways that ask for a small bit of attention, so it is worth keeping an eye on update notes.