Skip to main content

Quickstart

Get Soku running locally in about 15 minutes. This guide covers installing dependencies, configuring environment variables, and starting the development server.

Prerequisites​

ToolVersionNotes
Node.js22Enforced in root package.json via engines
pnpm9.12.2+Specified in packageManager field
Firebase CLILatestFor Functions emulators and deployment
gcloud CLILatestFor Cloud Tasks queue creation

1. Clone and install​

git clone https://github.com/chasegarsee/sokuho.git
cd sokuho
pnpm install

This installs dependencies for all workspace packages: apps/web, apps/functions, apps/docs, apps/cypress, packages/schema, and packages/shared.

2. Configure environment variables​

Web app (apps/web/.env.local)​

Create this file with your Firebase and Stripe credentials:

# Firebase (client-side — NEXT_PUBLIC_ prefix exposes to browser)
NEXT_PUBLIC_FIREBASE_API_KEY=...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=...
NEXT_PUBLIC_FIREBASE_PROJECT_ID=...
NEXT_PUBLIC_FIREBASE_APP_ID=...
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=...

# Firebase Admin (server-side only)
FIREBASE_SERVICE_ACCOUNT_BASE64=...

# Stripe
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_STARTER_PRICE_ID=price_...
STRIPE_PRO_PRICE_ID=price_...

FIREBASE_SERVICE_ACCOUNT_BASE64 is the base64-encoded service account JSON downloaded from Firebase Console. Generate it with: base64 -i service-account.json

Functions backend​

Cloud Functions read credentials from their runtime environment. For local emulator development, set these in apps/functions/.env or via firebase functions:config:set. See Environment & Tooling for the full list of social platform credentials.

3. Set up Firebase​

  1. Create a Firebase project (or use an existing one)
  2. Enable Authentication (Google provider + Email link)
  3. Create a Firestore database in Native mode
  4. Create a Cloud Storage bucket
  5. Install and authenticate the Firebase CLI:
npm install -g firebase-tools
firebase login
firebase use --add  # Select your project

See Firebase Setup for detailed instructions including security rules and CORS configuration.

4. Create Cloud Tasks queues​

Cloud Tasks queues are required for the publish orchestration system. Create them once per project:

REGION=us-central1

# Orchestrator queue (dispatches per-platform publish tasks)
gcloud tasks queues create orchestrate-posts --location="$REGION"

# Platform publish queues (create only the ones 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"

Add more platform queues as you onboard providers. See Cloud Tasks Topology for tuning options.

5. Start development​

pnpm dev

This uses Turborepo to run the web app and functions emulator in parallel:

ServiceURL
Web apphttp://localhost:3000
Functions emulatorhttp://localhost:5001
Firestore emulatorhttp://localhost:8080
Storage emulatorhttp://localhost:9199

You can also start services independently:

pnpm dev:web        # Next.js only (port 3000)
pnpm dev:functions  # Firebase emulators only

6. Verify the setup​

  1. Open http://localhost:3000
  2. Sign up using the pricing page (use Stripe test card 4242 4242 4242 4242)
  3. After checkout, you should land on the dashboard with an active trial
  4. Navigate to Settings to connect a social integration
  5. Try creating a post from the Create page

Common scripts​

ScriptDescription
pnpm devRun web + functions in parallel
pnpm dev:webRun web app only
pnpm dev:functionsRun Functions emulator only
pnpm buildBuild all apps
pnpm testRun all tests with coverage
pnpm lintRun ESLint across monorepo
pnpm typecheckTypeScript type checking
pnpm checkRun lint + typecheck + test
pnpm deploy:functionsDeploy functions to Firebase
pnpm sync:schemaBuild and sync @soku/schema to functions

Next steps​