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.
  1. 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. In Google Admin Console, open Directory / Users / Add new user. Create a dedicated temporary installer account, enter a secondary delivery email, and assign it no Workspace administrator role. Give its initial sign-in information only to the installer and ask them to change the temporary password and enroll in 2-Step Verification. Follow Google’s user-creation instructions.
  3. As a Workspace administrator, open Apps / Additional Google services / Google Cloud Platform / Service status. First select All users in this account. If the service is ON for everyone, the temporary installer already inherits access; leave the setting unchanged and close or cancel the page. Otherwise, select the organizational unit containing the temporary installer. If its status is Inherited: On or On, no change is needed. If it is off, select On, then Override or Save. Google’s service-settings instructions explain inherited and overridden organizational-unit settings. Changes usually apply quickly but can take up to 24 hours. This does not make the installer a Workspace administrator or grant access to a Cloud project. The installer does not need permission to create projects because the business creates the empty project below.
  4. In the permanent Owner’s browser profile, open Google’s Google Cloud service-terms page and complete any agreement it presents for that account. Also open the Google Maps Platform terms page and accept those separate terms. Lagniappe uses the Places API for address autocomplete and location verification. Explicitly authorize the installer to acknowledge the same agreement later with the temporary, business-controlled Workspace account. Google records acceptance against the account that runs API activation, so this second acknowledgement is technically required; setup will enable Places API itself. Then open the Google Cloud console. A Google Workspace subscription does not automatically create a Google Cloud billing account. Follow Google’s create-project instructions: open Manage Resources / Create Project, select the business organization, name the project, and select Create. When creation finishes, select the new project in the project picker. On its Dashboard, use the Project info card to confirm the project name, project number, and project ID, and record the exact Project ID for the installer. If project creation is blocked, ask the business’s Workspace administrator to create it inside the business organization. With that project selected, open Navigation menu / Billing. If no Cloud Billing account exists, choose Manage billing accounts / Create account and add the business’s payment details. Link that billing account to the project and confirm on the Billing page that billing is enabled before the installer runs setup. Google’s billing-status instructions show the same check.
  5. With the new project still selected, use the search box at the top of Google Cloud console to search for IAM, then open the IAM page under IAM & Admin. If it does not appear in search, use Navigation menu / IAM & Admin / IAM. In View by principals, find the permanent Owner’s email and confirm it has Basic / Owner on this project directly, with no inherited source or condition. The table can show several roles for one person on separate lines: an inherited organization role is fine, but the Owner line itself must have no entry in Inheritance. If it does not, select Grant access, add the permanent Owner, assign Basic / Owner, and select Save. Then select Grant access again. Enter the temporary Workspace email under New principals, choose Basic / Owner under Assign roles, and select Save. This is broad access, but it is temporary and confined to a new, empty project. Google’s grant and revoke instructions cover both adding and later removing the binding.
  6. 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 truly requires it. Give the installer the exact Cloud Project ID and the permanent Lagniappe Owner’s exact Google account email. Never give the installer the Owner’s Google password.
  7. After deployment, sign in as the permanent Owner and download a secure configuration backup from Admin / Site Settings / Maintenance / Configuration. Remove the installer’s Lagniappe Administrator role and confirm the in-app Remove Administrator dialog, or permanently delete the installer’s application account from Users. Then ask the installer to complete the handoff command; if the installer is unavailable, the permanent Owner may run it instead. The normal path is for the installer to run ./setup.sh handoff, or .\setup.cmd handoff in Windows PowerShell, from the existing installation working copy. An Owner preparing a separate computer must 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.
  8. After handoff succeeds, open Admin / Site Settings / Installation Access. Confirm it reports Application handoff configured, then use its Review project IAM link to verify that the installer is absent from project IAM. The application state cannot prove that external cleanup finished. Revoke provider invitations and temporary access tokens, and confirm the installer removed local credentials and settings from their machine.
  9. Review the authentication-email dependency shown under Installation Access. If it says to keep the installer mailbox active, first run ./setup.sh email from the installation working copy with a durable business-controlled sender and deploy the change. Without a custom application domain, this command opens Google App Passwords, defaults to the permanent Owner’s Gmail or Workspace address, tests the replacement before saving, and then offers to deploy. With a custom domain it guides the configured SMTP-provider path instead. Also remove the installer’s account access from billing, Redis Cloud, Cloudflare or DNS, Resend, and any other provider where it was invited. Securely transfer or delete any installer-held copy of a configuration backup or exported archive stored outside Lagniappe’s managed Google Cloud buckets. Only then suspend and ultimately delete the temporary Workspace user. Rotate any provider secret that could not remain under direct business control during installation.
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 ending in a colon.

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.