Stackpane Stackpane
Download

Firebase Setup & Prerequisites

Connect Stackpane to your Firebase project with Google Sign-In, service accounts, or the local emulator.

Overview

Stackpane connects to Firebase projects using Google OAuth or a service account key. For local development, the Firebase Emulator Suite requires no authentication at all. Once connected, you can browse Firestore collections, manage Auth users, work with Cloud Storage, configure security rules, and more — all from a native macOS interface.

Authentication Methods

Firebase connections support three authentication methods depending on your environment.

The easiest way to connect to a production Firebase project:

  1. Click the + button in the sidebar or choose New Connection.
  2. Select Firebase as the provider.
  3. Enter your Firebase Project ID (found in your Firebase Console under Project Settings > General).
  4. Select Production as the environment and Google Sign-In as the authentication method.
  5. Click Sign in with Google to open the OAuth flow in your browser.
  6. Authorize Stackpane to access your Firebase project.

Your credentials are stored securely in the macOS Keychain and automatically refresh.

Required Permissions

Your Google account must have IAM permissions on the Firebase project. Common roles that work:

RoleAccess Level
Owner or EditorFull read/write access to all services
ViewerRead-only access to all services
Cloud Datastore UserRead/write access to Firestore only

Custom roles work as long as they include the necessary permissions for the services you want to use.

Service Account

For automated workflows, CI/CD-adjacent usage, or when Google Sign-In is not suitable:

  1. Open the Firebase Console and select your project.
  2. Navigate to Project Settings > Service accounts.
  3. Click Generate new private key to download a JSON key file.
  4. In Stackpane, select Service Account as the authentication method.
  5. Click Choose File and select the downloaded JSON key file.

Stackpane reads the credentials and stores them securely in the Keychain. The original file can be deleted after import.

The service account must have roles for the Firebase services you want to access:

ServiceMinimum Role
FirestoreCloud Datastore User
AuthFirebase Authentication Admin
StorageStorage Admin
Security RulesFirebase Rules Admin
Cloud FunctionsCloud Functions Viewer
Remote ConfigFirebase Remote Config Admin

For full access to all services, assign the Editor role to the service account.

Emulator (No Auth Required)

When connecting to the Firebase Emulator Suite, no authentication is needed:

  1. Select Emulator as the environment type.
  2. Configure the emulator host (default: localhost) and ports for each service.
  3. Optionally select Manage Project to have Stackpane start and stop the emulator for you.

See the Emulator Suite guide for detailed configuration options including managed mode, snapshot management, and port customization.

Finding Your Project ID

Your Firebase Project ID is a unique identifier like my-app-12345. To find it:

  1. Open the Firebase Console.
  2. Click the gear icon next to Project Overview.
  3. Select Project settings.
  4. The Project ID is displayed under the General tab.

The Project ID is lowercase letters, numbers, and hyphens. It is not the same as the project name or project number.

Multiple Connections

You can create separate connections for different environments or auth configurations:

  • Production (Google Sign-In) — for interactive development with your Google account
  • Production (Service Account) — for consistent, user-independent access
  • Emulator — for local development and testing without touching production data

Each connection maintains its own bookmarks, tabs, and settings.

Firebase Plan Requirements

Stackpane uses the standard Firebase REST APIs. All features work with the Spark (free) plan with the following exceptions:

  • Cloud Functions — requires the Blaze (pay-as-you-go) plan to deploy functions
  • Cloud Logging — log access requires the Blaze plan
  • Analytics — GA4 data export requires linking a Google Analytics property

Firestore, Auth, Storage, Security Rules, Remote Config, and Firestore Indexes all work on the free plan.

Troubleshooting

”Permission denied” on Firestore or Storage

Your Google account or service account lacks the required IAM roles. Check the role tables above and verify permissions in the Firebase Console under Project Settings > Users and permissions.

”Project not found”

Verify the Project ID is correct — it must match exactly as shown in the Firebase Console. The Project ID is case-sensitive and uses hyphens, not underscores.

Google Sign-In fails or token expires

Stackpane automatically refreshes OAuth tokens. If sign-in fails, try signing out and back in from the connection settings. Ensure your browser is not blocking the OAuth popup.

Service account errors

  • Verify the JSON key file was generated for the correct project
  • Check that the service account has not been deleted or disabled in the IAM Console
  • Ensure the key file is valid JSON and was not truncated during download

Emulator connection refused

Make sure the Firebase Emulator Suite is running before connecting. The default ports are:

ServiceDefault Port
Firestore8080
Auth9099
Storage9199
Functions5001
Emulator UI4000

If you changed ports in firebase.json, update the connection settings to match.

Tips

  • Google Sign-In is the fastest way to get started — no key files to manage
  • Service accounts are better for shared team setups where you don’t want access tied to a personal Google account
  • Credentials are stored in the macOS Keychain and never written to disk
  • Create separate emulator and production connections to avoid accidental data changes