Firebase

Firebase is the recommended way to run Localess in production. It uses Google Cloud infrastructure — Firebase Hosting, Firestore, Cloud Functions, and Cloud Storage — provisioned and deployed from your own checkout with the Localess setup CLI.

For local exploration or personal use without a Google Cloud account, see the Docker or Local setup instead.

Prerequisites

A checkout of the Localess repository.
Node.js 24.

Firebase CLI 15.29.0 or later, logged in once per machine:

npm install -g firebase-tools@latest
npx firebase login

A Google Cloud billing account. Localess needs the Blaze (pay-as-you-go) plan — Cloud Functions, Identity Platform, the Storage bucket and Cloud Translation are all unavailable on the free Spark plan.

Provision the project

From the repository root:

npm install
npm run localess:setup -- --project my-localess   # or omit --project to pick or create one

Flag	Purpose
`--project <id>`	Adopt an existing project. Omit it to pick from your projects or create a new one
`--display-name <name>`	Display name when creating a project (default `Localess`)
`--region <region>`	Region for Firestore, Storage and Cloud Functions — asked when omitted
`--billing-account <id>`	Billing account to link
`--yes`	Never prompt. Requires `--project`, and `--billing-account` when billing is not linked yet

Setup creates or adopts the project, links billing, enables the required Google Cloud APIs, and creates the Firestore database, the Storage bucket (with its CORS policy), the Hosting site and the web app. Every step is idempotent — if a run fails, fix the cause and run it again; completed work is skipped.

--region is permanent. Neither the Firestore database nor the Storage bucket can be moved after creation, and Cloud Functions must run in the same region. Changing your mind later means a new project.

Setup never deploys. It offers to run the first deploy when it finishes, but only if you say yes.

Configure the build

Build-time settings live in .env.<project-id> at the repository root, which setup generates. They are compiled into the app, so a change takes effect on the next deploy.

Setting	Default	Purpose
`LOCALESS_AUTH_PROVIDERS`	empty — Email/Password only	Extra sign-in buttons on the login page, comma-separated: `GOOGLE`, `MICROSOFT`
`LOCALESS_AUTH_CUSTOM_DOMAIN`	empty — no restriction	Restrict Google and Microsoft sign-in to one organisation (e.g. `example.com`)
`LOCALESS_LOGIN_MESSAGE`	empty	Message displayed on the login screen
`LOCALESS_UNSPLASH_ENABLE`	empty — disabled	`true` enables the Unsplash integration for assets

The file also holds LOCALESS_REGION. Don't edit it: the CLI rewrites it from the live Firestore location on every deploy.

Deploy

npm run localess:deploy -- --project my-localess

By default this builds the app and deploys hosting, functions, storage, firestore and auth — the last one enables Identity Platform with Email/Password sign-in.

Flag	Purpose
`--project <id>`	Skip the project picker
`--only <targets>`	Deploy only these targets, e.g. `hosting` or `functions`
`--skip-install`	Reuse the installed `node_modules`
`--skip-build`	Reuse the existing build output
`--dry-run`	Print the build and deploy commands without running them
`--yes`	Skip the confirmation. Requires `--project`

Deploy only touches projects that localess:setup has labelled as Localess-managed, so a mistyped project ID cannot overwrite something unrelated. The first deploy is the slowest — Cloud Build has to build an image for every function — and is retried automatically if the new project's services are not ready yet.

First start

After the first successful deployment, create your first admin with the health check:

npm run localess:check -- --project <firebase-project-id> --fix

It prompts for an email, password and display name, grants the admin role, and seeds a "Hello World" space. For scripted runs, pass --admin-email and --admin-name and set the password in the LOCALESS_ADMIN_PASSWORD environment variable — there is deliberately no password flag.

Then sign in at https://<firebase-project-id>.web.app.

Email/Password sign-in is enabled by the deploy. Google and Microsoft are configured in the Firebase console, and then added to LOCALESS_AUTH_PROVIDERS so the login page shows their buttons — enabling a provider in the console alone is not enough. Redeploy after changing that setting.

Google Identity Provider

In the Firebase console, open the Auth section.
On the Sign-in method tab, enable the Google sign-in method.
Click Save.
Add GOOGLE to LOCALESS_AUTH_PROVIDERS and redeploy.

Microsoft Identity Provider

In the Firebase console, open the Auth section.
On the Sign-in method tab, enable the Microsoft provider.
Add the Client ID and Client Secret from the Azure portal:
- Register a new app following the Azure AD v2.0 quickstart.
- Add *.firebaseapp.com as a redirect URI for your Firebase project.
Click Save.
Add MICROSOFT to LOCALESS_AUTH_PROVIDERS and redeploy.

Updating

To update an existing installation:

git pull
npm install
npm run localess:deploy -- --project my-localess

A full deploy rebuilds every function image. Narrow it to what changed:

Changed	Command
Admin app only	`npm run localess:deploy -- --only hosting`
Cloud Functions only	`npm run localess:deploy -- --only functions`
Security rules only	`npm run localess:deploy -- --only firestore:rules,storage`

Health check

npm run localess:check -- --project my-localess

Reports what the project is still missing — APIs, resources, deployed functions, an admin user — and exits non-zero if anything is. Add --fix to repair what it can.

Alternative: Cloud Build

cloudbuild.yaml at the repository root runs the same build and deploy in CI on every push. It replaces localess:deploy, not localess:setup — provision the project with localess:setup first. The pipeline enables the required Google Cloud APIs itself.

Service account

Create a service account named build-deploy to assign to Cloud Builder. Follow the official guide.

The service account requires the following IAM roles:

Role	Purpose
Cloud Build Service Account	Run builds
Firebase Admin	Full access to Firebase products
Service Account User	Act as the service account
Storage Usage Admin	Manage storage service state
Storage Object Admin	Full control over storage objects

Trigger

To automatically deploy on every push, create a Cloud Build trigger:

Open Cloud Build Triggers
Click Create trigger and configure:
- Name — a name for your trigger
- Event — Push to a branch
- Repository — your fork of https://github.com/Lessify/localess
- Branch — main
- Configuration type — Cloud Build configuration file (YAML or JSON)
- Location — Repository
Under Substitution variables, add:

Variable	Default	Description
`_REGION`	`europe-west6`	Cloud Functions region. Must match the region chosen at setup
`_LOCALESS_AUTH_PROVIDERS`	—	Same as `LOCALESS_AUTH_PROVIDERS` in Configure the build
`_LOCALESS_AUTH_CUSTOM_DOMAIN`	—	Same as `LOCALESS_AUTH_CUSTOM_DOMAIN`
`_LOCALESS_LOGIN_MESSAGE`	—	Same as `LOCALESS_LOGIN_MESSAGE`
`_LOCALESS_UNSPLASH_ENABLE`	—	Same as `LOCALESS_UNSPLASH_ENABLE`

Click Create.

Troubleshooting

Project is not a Localess project

<project-id> is not a Localess project - it carries no localess-managed label.

Deploy only touches projects that setup has labelled. Run localess:setup on the project first, or npm run localess:check -- --project <project-id> --fix to add the markers to an existing installation.

Firebase CLI is too old

firebase-tools <version> is too old (need >= 15.29.0).

Upgrade with npm install -g firebase-tools@latest.

Cloud billing quota exceeded

Your billing account has hit its limit on linked projects. Unlink a project you no longer need, or request an increase.

The caller does not have permission (creating the bucket)

Almost always the free Spark plan — a new project needs Blaze for its default Storage bucket. Confirm billing is active, then run setup again.

Functions could not be deployed

<n> function(s) could not be deployed after 3 attempts: ...

The first deploy races the provisioning before it, and deploy already retried three times. Wait a few minutes and run the same command again.

Admin UI loads, but every action fails with 403

A function created during a deploy that failed partway can miss its public invoker binding, while later deploys keep reporting success. Run:

npm run localess:check -- --project <project-id> --fix

Missing permissions

Missing permissions required for functions deploy. You must have permission iam.serviceAccounts.ActAs on service account project-id@appspot.gserviceaccount.com.

Assign the Service Account User role to project-id@appspot.gserviceaccount.com. Changes may take a few minutes to propagate.

IAM Roles verification failed

functions: Failed to verify the project has the correct IAM bindings for a successful deployment.

Run the gcloud projects add-iam-policy-binding commands shown in the error output. You can execute them directly in Cloud Shell.

Function requires manual deletion

Error: The following functions are found in your project but do not exist in your local source code:
importLocaleJson(us-central1)

Delete the orphaned function from one of:

Google Cloud Console → Cloud Functions
Google Cloud Console → Cloud Run
Firebase Console → Functions

On this page