Connect Firebase and Google Cloud

Do this when you are ready. You do not need any of it to run BuildItOmi locally.

This guide is for a person creating their first Firebase project. Console labels move around. If a button name differs, use the search box in the console.

Billing is already connected on the builditomi project. That does not approve new spend. Do not enable Vertex AI, Cloud Run, Cloud Build, or App Hosting until the cost is accepted. Firestore reads and writes already have a cost, and budget alerts do not stop it.

BuildItOmi will not turn those services on for you.

What you are connecting

| Piece | What it unlocks later | Billable? | | --- | --- | --- | | Firebase project | A home for Auth, Firestore, and Hosting | Spark plan exists. Confirm before you add billing. | | Web app config | Public keys in .env.local | The keys are not secret, but they identify your project. | | Authentication | Google and email sign-in | Free tier, then usage limits. | | Firestore | Projects and the credit ledger in the cloud | Free tier, then reads and writes cost money. | | Admin service account | The server can verify sign-in and write data | The key file is a secret. | | Vertex AI | Real Gemini generation | Billed. Leave it off until you approve it. | | Cloud Run / Cloud Build / Hosting | Previews and publishing | Often billed. Leave them off for now. |

1. Create the Firebase project

1. Open Firebase console.
2. Choose Create a project (or Add project).
3. Name it something you will recognize, such as builditomi. The project ID on the next screen is permanent. Copy it.
4. Google Analytics is optional. You can turn it off for a simpler first project.
5. Wait until the project finishes creating.
6. Stay on the Spark plan. If the console invites you to upgrade to Blaze, skip it for now.

2. Register a web app

1. In Project overview, choose the Web icon (</>).
2. Give the app a nickname, such as BuildItOmi web.
3. You can skip Firebase Hosting for now.
4. Firebase shows a firebaseConfig object. Copy these fields into .env.local (create that file from .env.example):

NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=

1. Restart npm run dev after saving the file.

These values let the browser SDK initialize. They do not switch storage by themselves. Set BIO_DATABASE=firestore after the Firestore database exists. A local Firebase CLI login is enough for development. A service account is the production identity.

3. Turn on Authentication

1. In the Firebase console, open Build → Authentication.
2. Choose Get started.
3. Open Sign-in method.
4. Enable Email/Password. You can leave email link (passwordless) off.
5. Enable Google. You will be asked for a support email. Use an address you control.
6. Save.

The server checks the Firebase ID token with Identity Toolkit before it creates a session. An Admin private key is not required for that check.

4. Create Firestore

1. Open Build → Firestore Database.
2. Choose Create database.
3. Start in production mode so the database is locked by default. You will add rules before real users exist. Test mode expires and is easy to leave open.
4. Pick a region close to you and leave it. Region changes are painful later.
5. In the Rules tab, keep access closed. A starting point that denies everyone is safer than open rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

The server uses the Admin SDK, which bypasses these rules. Client apps must not be given the Admin key. When you later let the browser read data, write rules that check request.auth.uid against the document’s userId. Do not ship allow read, write: if true.

The Firestore adapter has been run against builditomi. See docs/PRODUCTION_READINESS.md for the probe result. Local JSON remains the database for automated tests.

5. Create the Admin service account

1. Open Project settings (gear) → Service accounts.
2. Choose Generate new private key and confirm. Firebase downloads a JSON file.
3. That file is a password for your whole project. Do not commit it, do not paste it into chat, and do not put it in NEXT_PUBLIC_ variables.
4. From the JSON, copy into .env.local:

FIREBASE_ADMIN_PROJECT_ID=
FIREBASE_ADMIN_CLIENT_EMAIL=
FIREBASE_ADMIN_PRIVATE_KEY=

The private key includes line breaks. In .env.local, keep it on one line with \n where the breaks were, inside double quotes:

FIREBASE_ADMIN_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

1. Restart the dev server.

When BIO_DATABASE=firestore, or when all three Admin variables are set, BuildItOmi uses Firestore. A missing credential is an error. It is not replaced with a fake success.

Google sign-in verification is only partly wired: the server can check an ID token, and it will refuse to create a session until user mapping is finished and tested. Do not treat a 501 response as a successful login.

6. Leave Vertex AI off until you approve spend

Real generation uses the Gemini model on Vertex AI through @google/genai. It needs:

GOOGLE_CLOUD_PROJECT=
GOOGLE_CLOUD_LOCATION=us-central1
VERTEX_GEMINI_MODEL=gemini-2.5-flash

And Application Default Credentials, or a service account that can call Vertex, on the machine running the server. A typical role is Vertex AI User.

Before that works you must, in Google Cloud Console:

1. Link a billing account (Blaze / paid). This is the step that can cost money.
2. Enable the Vertex AI API for the project.
3. Confirm the model name still exists in your region. gemini-2.5-flash is the default in .env.example. Change it if Google has retired that id.

If VERTEX_GENERATION is not enabled, the local scaffold runs and the product says so. Setting GOOGLE_CLOUD_PROJECT alone does not call Gemini.

7. Do not enable these yet

These are the intended production pieces. None of them are activated by this repository:

• Firebase App Hosting for the Next.js app. It requires Blaze.
• Cloud Storage for source snapshots larger than a Firestore document.
• Cloud Run as an isolated build runner that does not receive BuildItOmi’s Admin key or Vertex key.
• Cloud Tasks to queue builds.
• Cloud Build if you choose it instead of a custom runner.
• Secret Manager for the Admin private key in production. Your laptop .env.local is only for development.
• Firebase Hosting for generated static sites.

Read docs/ARCHITECTURE.md before you pick a runner. Cloud Run is not, by itself, a perfect sandbox for untrusted code.

8. Check that local mode still tells the truth

After you add variables, open /api/health.

• mode: "local" means Firestore is not selected and data is on disk.
• firestore: true means the server is using Firestore. firebaseAdmin: false means that path is the CLI login or ADC, not a downloaded service-account key.
• mode: "cloud" means Admin credentials are present. It does not mean publishing or Gemini has been tested.
• vertex: true means GOOGLE_CLOUD_PROJECT is set. It does not mean a model call succeeded.

There is no step in this guide that marks those features as done. Test them yourself, with a project you can afford to delete, and only then tell users they work.