Skip to main content

​
Local Setup Reference

This page is a complete reference for local development configuration. For the step-by-step setup guide, see Getting Started.

​
Environment Variables Reference

All variables are sourced from .env.example. Copy to .env.local before running: 
cp .env.example .env.local

​
Core Settings

VariableDefaultDescription
CGO_ENABLED1Must be 1 — enables native Go bindings for bd (Beads CLI)

​
Firebase Configuration

VariableDescription
NEXT_PUBLIC_FIREBASE_API_KEYFirebase Web API key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAINFirebase auth domain
NEXT_PUBLIC_FIREBASE_PROJECT_IDFirebase project ID
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKETFirebase Storage bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_IDFirebase Messaging sender ID
NEXT_PUBLIC_FIREBASE_APP_IDFirebase App ID
NEXT_PUBLIC_FIREBASE_DATABASE_IDFirestore database ID

​
Firebase Emulator (Optional)

Uncomment in .env.local for fully offline development:
VariableDescription
NEXT_PUBLIC_FIREBASE_USE_EMULATORSet to true to use local Firebase emulator
NEXT_PUBLIC_FIREBASE_EMULATOR_HOSTEmulator host (default: localhost)
NEXT_PUBLIC_FIREBASE_EMULATOR_PORTEmulator port (default: 8080)

​
External Service Tokens

VariableDescription
GITHUB_TOKENGitHub personal access token
ERASER_API_TOKENEraser MCP API token (diagram generation)
BASEHUB_TOKENBaseHub CMS token
LIVEBLOCKS_SECRET_KEYLiveblocks real-time collaboration key

​
Docs MFE

VariableDefaultDescription
DOCS_MODEplaceholderControls /docs route behavior: placeholder | redirect | embed
DOCS_URLhttps://docs.shokunin.appExternal Mintlify docs URL

​
Production / Cloud Run

VariableDescription
GOOGLE_SERVICE_ACCOUNT_KEYGCP service account JSON key (single line) for Cloud Run OIDC auth

​
Terraform (Local Applies Only)

VariableDescription
TF_VAR_dolt_db_passwordDolt DB password for ./terraform/scripts/tf apply
TF_VAR_beads_api_keyBeads API key for Terraform applies

​
Docker Compose Services

docker-compose.yml defines three services:

​
beads-backend

Dolt SQL Server — the persistent data store for Beads (task tracking).
  • Image: Custom (./infrastructure/beads-backend)
  • Host port: 3307 → container port 3306
  • Volume: beads-data (persists Dolt data across container restarts)
  • Environment:
    • DOLT_ROOT_PASSWORD=beads (local dev password)
docker-compose up -d beads-backend

​
beads-api

Beads HTTP API — consumed by the bd CLI and (in future) the platform web app.
  • Image: Custom (./infrastructure/beads-api)
  • Host port: 8080
  • Database: beads_v0-shokunin-ai-platform on beads-backend
  • Auth: Open/dev mode locally (BEADS_API_KEY not set)
docker-compose up -d beads-api

​
platform-web

The Next.js frontend (Shokunin Platform web app).
  • Host port: 3000
  • Command: bun run dev (hot reload enabled)
  • Note: For active development, run bun run dev directly instead
docker-compose up -d platform-web

​
Beads CLI Configuration

After starting the Docker services, configure bd to connect to your local Dolt backend: 
bd dolt set mode server
bd dolt set host 127.0.0.1
bd dolt set port 3307
bd dolt set user root

# Verify connection
bd dolt show
bd status
For detailed Dolt backend setup, see infrastructure/beads-backend/README.md.

​
Troubleshooting

bd fails with native binding errors
  • Set CGO_ENABLED=1 in your shell or .env.local
Port 3307 conflict
  • Another MySQL/Dolt instance is running. Stop it or edit the port mapping in docker-compose.yml
Port 3000 conflict 
lsof -ti:3000 | xargs kill -9
Firebase auth errors
  • Check .env.local has valid Firebase credentials
  • For local dev: use Firebase emulator (uncomment emulator vars)
Dolt database not initialized
  • See infrastructure/beads-backend/README.md for initializing the Dolt database schema