Skip to main content

Firebase Setup

This guide walks through setting up a Firebase project for Soku, including Authentication, Firestore, Cloud Storage, Cloud Functions, and Cloud Tasks.

1. Create a Firebase project​

  1. Go to the Firebase Console and create a new project (or use an existing one).
  2. Enable Google Analytics if desired (optional).
  3. Note your Project ID — you'll need it for environment variables.

2. Enable Authentication​

  1. In Firebase Console, go to Authentication > Sign-in method.
  2. Enable the following providers:
    • Google — Primary OAuth sign-in
    • Email/Password — Enable Email link (passwordless sign-in) for magic link support
  3. Under Authorized domains, add your production domain (e.g., mysoku.io) and any staging URLs.

3. Create a service account​

  1. Go to Project Settings > Service accounts.
  2. Click Generate new private key and download the JSON file.
  3. Base64-encode it and set as FIREBASE_SERVICE_ACCOUNT_BASE64:
base64 -i path/to/service-account.json
  1. Store this in apps/web/.env.local (never commit it to version control).

4. Set up Firestore​

  1. Go to Firestore Database > Create database.
  2. Select Native mode (not Datastore mode).
  3. Choose your preferred region (should match your Functions region).
  4. Deploy security rules:
firebase deploy --only firestore:rules

The security rules in firestore.rules enforce user-scoped access. Key principles:

  • Users can read/update their own documents (request.auth.uid == uid)
  • Subscription, integration tokens, and credits are written by Admin SDK only
  • Staff members can access the logs collection for debugging

Composite indexes are defined in firestore.indexes.json and deployed alongside rules. These support complex queries for distributed tracing, metrics, and workflow execution.

5. Set up Cloud Storage​

  1. Go to Storage in Firebase Console and create the default bucket.
  2. Choose the same region as your Firestore database.
  3. Configure CORS for your web origins. Create a local cors.json (do not commit it):
[
  {
    "origin": [
      "http://localhost:3000",
      "http://127.0.0.1:3000",
      "https://your-vercel-domain.vercel.app",
      "https://mysoku.io"
    ],
    "method": ["GET", "HEAD", "PUT", "POST", "DELETE"],
    "responseHeader": [
      "Content-Type",
      "Authorization",
      "x-goog-meta-*",
      "x-goog-resumable",
      "x-goog-upload-*"
    ],
    "maxAgeSeconds": 3600
  }
]
  1. Apply CORS configuration:
gsutil cors set cors.json gs://your-bucket-name
gsutil cors get gs://your-bucket-name   # Verify
  1. Deploy storage security rules:
firebase deploy --only storage

The rules in storage.rules restrict per-user reads/writes for media uploads and library assets.

6. Set up Cloud Functions​

Cloud Functions use Node.js 22 runtime and are configured in firebase.json. Key settings:

{
  "functions": {
    "source": "apps/functions",
    "runtime": "nodejs22"
  }
}

Install the Firebase CLI and set your project:

npm install -g firebase-tools
firebase login
firebase use --add

Deploy functions​

pnpm deploy:functions
# Or deploy a single function:
firebase deploy --only functions:publishOrchestrator

Schema sync​

Before deploying functions, sync the shared schema package:

pnpm sync:schema

This builds @soku/schema and copies the output into apps/functions/.schema/ for the Functions runtime.

7. Create Cloud Tasks queues​

Cloud Tasks queues must exist before the orchestrator can enqueue publish jobs. Create them in the same region as your Functions:

REGION=us-central1

# Core orchestrator queue
gcloud tasks queues create orchestrate-posts --location="$REGION"

# Platform publish queues (create only what you need)
gcloud tasks queues create publish-facebook   --location="$REGION"
gcloud tasks queues create publish-instagram  --location="$REGION"
gcloud tasks queues create publish-threads    --location="$REGION"
gcloud tasks queues create publish-x          --location="$REGION"
gcloud tasks queues create publish-tiktok     --location="$REGION"
gcloud tasks queues create publish-youtube    --location="$REGION"
gcloud tasks queues create publish-linkedin   --location="$REGION"

# Metrics queues (for platform analytics polling)
gcloud tasks queues create tiktok-metrics     --location="$REGION"

Optional: tune queue settings​

Align dispatch rates with platform API limits:

gcloud tasks queues update publish-x \
  --location="$REGION" \
  --max-dispatches-per-second=10 \
  --max-concurrent-dispatches=5 \
  --max-attempts=5 \
  --min-backoff=10s \
  --max-backoff=600s

Verify queues​

gcloud tasks queues describe orchestrate-posts --location="$REGION"
gcloud tasks queues list --location="$REGION"

Queue names are platform-agnostic. For any new provider, create a publish-<provider> queue and wire it in the orchestrator.

8. Configure emulators (local development)​

The firebase.json file configures emulator ports:

EmulatorPort
Functions5001
Firestore8080
Storage9199

Start emulators with:

pnpm dev:functions