Google Cloud & Firebase Setup - lasswellt/playbook-library GitHub Wiki

This guide assumes you are starting from scratch. We will cover creating a new Google Cloud project, linking it to Firebase, enabling all necessary APIs, setting up a service account, and storing its credentials securely.

Note: Do not remove any content. The goal is to organize and establish better cohesion.

1.1. Create or Select a Google Cloud Project

  1. Sign in to the Google Cloud Console with an account that has permissions to create or manage projects.
  2. Open the Project Selector:
    • Click on the drop-down menu at the top-left, to the right of the "Google Cloud" logo.
    • It might say "Select a project" or display an existing project name.
  3. Create a New Project (if you want a fresh environment):
    1. Click New Project.
    2. Provide a Project name (e.g., "example-system").
    3. (Optional) Select an Organization or No organization, depending on your workspace setup.
    4. (Optional) Specify a Location if needed.
    5. Click Create and wait for the project to finish provisioning.
  4. Note the Project ID (e.g., example-system-12345):
    • This ID is often auto-generated, but you can set a custom one if available and not already in use.
  5. Enable Billing for the new project if prompted:
    • Without billing enabled, some Firebase and Google Cloud services will be restricted.

CLI Alternative:

If you prefer using the command line:

gcloud projects create example-system-12345
gcloud config set project example-system-12345

Ensure you have the Google Cloud SDK installed and configured on your local machine.

1.2. Initialize Firebase in the Google Cloud Project

Next, we associate the newly created Google Cloud project with Firebase services.

  1. Install Firebase CLI (if you don’t have it):

    npm install -g firebase-tools

    or

    npm update -g firebase-tools

  2. Log in to Firebase:

    firebase login

  3. Link the GCP Project to Firebase:

    firebase projects:addfirebase example-system-12345
    • This step will upgrade your Google Cloud project to a Firebase project, enabling access to Firebase-specific features.

Alternatively, you can perform these steps via the Firebase Console:

  1. Go to Firebase Console.
  2. Click Create a project.
  3. Select Add Firebase to Google Cloud project.
  4. Choose your Google Cloud Project (example-system-12345).
  5. Confirm the Firebase pricing plan.
  6. Click Continue on the "A few things to remember" page.
  7. (Optional) Enable Google Analytics and click Continue.
  8. (Optional) Choose your Google Analytics account (create one if you don't have one).
  9. Click Add Firebase to set up Firebase on the selected project.

1.3. Enable Required APIs

A variety of APIs must be enabled for the system, including:

  • Secret Manager: For storing sensitive configurations such as Firebase keys.
  • Cloud Functions: (Optional) If you plan to use serverless functions for back-end logic.
  • Firestore: For the database (recommended "Native mode" for most use cases).
  • App Engine: Required for certain Firebase or GCP features (e.g., enabling certain background functions or hosting features).
  • Firebase Management: For deeper integration with the CLI and project administration.

Enabling APIs via Cloud Console

  1. Navigate to APIs & Services > Library in the Cloud Console.
  2. In the search bar, type each API name (e.g., "Secret Manager API") and click Enable.

Enabling APIs via CLI (Recommended for Speed)

gcloud services enable \
  secretmanager.googleapis.com \
  cloudfunctions.googleapis.com \
  firestore.googleapis.com \
  appengine.googleapis.com \
  firebase.googleapis.com

1.4. Configure Firestore

  1. Access Firestore in Firebase Console:
  2. Click Create Database.
  3. Choose a Database ID (usually leave as default).
  4. Select a Cloud Firestore location close to your main user base.
  5. Choose Start in production mode (recommended):
    • Test mode allows open access, which is not secure for production.
  6. Click Create.

CLI Note:

firebase firestore:enable

This command configures Firestore in your project. You might still need to finalize settings in the console, especially for region selection.

1.5. Create a Service Account for CI/CD

To automate deployments (e.g., using GitHub Actions), create a dedicated service account with limited permissions.

  1. Navigate to Service Accounts:
  2. Select your project if not already selected.
  3. Click Create Service Account.
    • Name: e.g., github-actions-sa
    • ID: e.g., [email protected] (usually auto-generated)
    • Description: e.g., Service account for GitHub Actions automations
  4. Click Create and Continue.
  5. Grant This Service Account Access to Project:
    • Roles to assign:
      • Secret Manager Secret Accessor: To read secrets from Secret Manager.
      • Firebase Hosting Admin or Owner: Depending on deployment needs.
      • (Optional) Storage Admin: If handling files in Cloud Storage.
      • (Optional) Cloud Functions Developer: If deploying functions.
    • Click Continue.
  6. Grant Users Access to This Service Account (Optional):
    • Only necessary if other users need access.
    • Click Done.
  7. Create a Key for the Service Account:
    1. Click on the newly created service account.
    2. Navigate to the Keys tab.
    3. Click Add Key > Create a new key.
    4. Choose JSON and click Create.
    5. The key file (.json) will download automatically.

CLI Alternative:

# Create Service Account
gcloud iam service-accounts create github-actions-sa \
    --display-name="GitHub Actions Service Account"

# Grant Roles
gcloud projects add-iam-policy-binding example-system-12345 \
    --member="serviceAccount:[email protected]" \
    --role="roles/secretmanager.secretAccessor"

# Add additional roles as needed
# Example:
# gcloud projects add-iam-policy-binding example-system-12345 \
#     --member="serviceAccount:[email protected]" \
#     --role="roles/firebasehosting.admin"

# Create a Key for the Service Account
gcloud iam service-accounts keys create ./gcloud-key.json \
    --iam-account=github-actions-sa@example-system-12345.iam.gserviceaccount.com

1.6. Store the Service Account Key Securely

Never commit the key to your repository. Instead, add it as a secret in GitHub:

  1. Navigate to Repository Settings:
    • Go to your GitHub repository.
    • Click on Settings > Security > Secrets and variables > Actions.
    • Alternatively, visit: https://github.com/{username}/{repository}/settings/secrets/actions
  2. Add a New Secret:
    • Click New repository secret.
    • Name the secret, for example: GCLOUD_SERVICE_ACCOUNT_KEY.
    • Paste the entire JSON content of gcloud-key.json into the secret value.
  3. Reference the Secret in GitHub Actions:

    • In your GitHub Actions workflow, reference the secret to authenticate with Google Cloud:

      - name: Authenticate to Google Cloud
  env:
    GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.GCLOUD_SERVICE_ACCOUNT_KEY }}
  run: echo "${{ secrets.GCLOUD_SERVICE_ACCOUNT_KEY }}" > $GOOGLE_APPLICATION_CREDENTIALS

1.7. Optional: Configure App Engine

If your system or Firebase project requires App Engine (e.g., for certain features like region-bound tasks or older real-time DB triggers), set it up as follows:

gcloud app create --region=us-central

This step is optional unless your architecture demands it.

1.8. Verification & Housekeeping

  1. Check IAM Roles:

  2. Review Billing:

    • Go to the Billing page in the Cloud Console.
    • Ensure you have a valid billing account attached.

  3. Confirm Project via CLI:

    gcloud config get-value project

    • If it doesn’t match your intended project, set it:

      gcloud config set project example-system-12345

  4. Manage Projects in CLI:

    • Change Projects:

      gcloud config set project [PROJECT_ID]

      Example:

      gcloud config set project my-cool-project

    • Verify Current Project:

      gcloud config get-value project

    • List Available Projects:

      gcloud projects list

These commands ensure you're working in the correct project context for subsequent gcloud commands.

1.9. Summarized Command List

For reference, here’s a condensed version of the CLI commands used in Step 1:

# 1. Install necessary CLI tools:
npm install -g firebase-tools
gcloud components install app-engine-java # if needed for some App Engine features

# 2. Create/Select a GCP project:
gcloud projects create example-system-12345
gcloud config set project example-system-12345

# 3. Link GCP project to Firebase:
firebase login
firebase projects:addfirebase example-system-12345

# 4. Enable Required APIs:
gcloud services enable \
  secretmanager.googleapis.com \
  cloudfunctions.googleapis.com \
  firestore.googleapis.com \
  appengine.googleapis.com \
  firebase.googleapis.com

# 5. Initialize Firestore (also can do via console):
firebase firestore:enable

# 6. Create a Service Account:
gcloud iam service-accounts create github-actions-sa \
  --display-name="GitHub Actions Service Account"

# 7. Grant Roles:
gcloud projects add-iam-policy-binding example-system-12345 \
  --member="serviceAccount:[email protected]" \
  --role="roles/secretmanager.secretAccessor"

# Add other roles as needed for hosting, etc.
# Example:
# gcloud projects add-iam-policy-binding example-system-12345 \
#   --member="serviceAccount:[email protected]" \
#   --role="roles/firebasehosting.admin"

# 8. Create a key for the Service Account:
gcloud iam service-accounts keys create ./gcloud-key.json \
  --iam-account=github-actions-sa@example-system-12345.iam.gserviceaccount.com

# 9. (Optional) Create App Engine (if needed):
gcloud app create --region=us-central

1.10. Next Steps

With Step 1 complete, you have:

  • A Google Cloud project with Firebase integration.
  • Firestore enabled in native mode.
  • A service account with appropriate IAM roles to handle secrets and (optionally) deployments.
  • APIs enabled for Secret Manager, Cloud Functions, Firestore, App Engine, and Firebase Management.

You’re now ready to proceed to Step 2: Multi-Repository Structure & Project Initialization, where you’ll set up your Vue/Quasar projects in separate GitHub repositories, configure them for Module Federation, and eventually tie them together with GitHub Actions for CI/CD.

End of Step 1: Google Cloud & Firebase Setup

This completes the detailed breakdown for preparing your Google Cloud and Firebase environment. Proceed with confidence, knowing your project is now properly staged for development, security, and future deployment.