Getting Started
This guide walks you through setting up the Shokunin Platform on your local machine. All steps are derived from actual repo files — any step based on inference is labeled [based on repo evidence].
Recommended Path: Dev Container
The fastest way to start is with the pre-configured dev container. It eliminates manual toolchain setup.
What the dev container provides (from .devcontainer/README.md):
- Node.js 20
- Docker-in-Docker (so you can run
docker-compose inside the container)
- GitHub CLI
Option A: GitHub Codespaces
- Open the repository on GitHub.
- Click Code → Codespaces → Create codespace on main.
- Wait for the container to build (first time ~2–3 minutes).
- Once inside, jump directly to Step 3: Configure Environment Variables.
Option B: VS Code Dev Container
- Install the Dev Containers extension.
- Clone the repository locally:
git clone <repo-url>
cd v0-shokunin-ai-platform
- Open in VS Code, then click Reopen in Container when prompted.
- Once inside, jump to Step 3.
Manual Setup (Without Dev Container)
If you prefer to run locally without the dev container:
Step 1: Prerequisites
Ensure you have the following installed:
- Node.js 20 (check:
node --version)
- Bun package manager:
npm install -g bun
- Docker and Docker Compose (for the Beads backend)
- GitHub CLI (
gh) for authentication [based on repo evidence]
- gcloud CLI authenticated to the GCP project [based on repo evidence]
Step 2: Clone and Install
git clone <repo-url>
cd v0-shokunin-ai-platform
bun install
Copy the example env file and fill in your values:
cp .env.example .env.local
Required Environment Variables
All variables below are from .env.example. Variables marked required must be set before the platform starts.
| Variable | Required | Description |
|---|
CGO_ENABLED | Required | Must be 1 for native Go bindings used by Beads CLI. Set to 1. |
NEXT_PUBLIC_FIREBASE_API_KEY | Required | Firebase Web API key |
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN | Required | Firebase auth domain (e.g. shokunin-480309.firebaseapp.com) |
NEXT_PUBLIC_FIREBASE_PROJECT_ID | Required | Firebase project ID (e.g. shokunin-480309) |
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET | Required | Firebase Storage bucket |
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID | Required | Firebase Messaging sender ID |
NEXT_PUBLIC_FIREBASE_APP_ID | Required | Firebase App ID |
NEXT_PUBLIC_FIREBASE_DATABASE_ID | Required | Firestore database ID (usually (default)) |
GITHUB_TOKEN | Required | GitHub personal access token for API calls |
ERASER_API_TOKEN | Optional | Eraser MCP API token (for diagram generation) |
BASEHUB_TOKEN | Optional | BaseHub CMS token |
LIVEBLOCKS_SECRET_KEY | Optional | Liveblocks real-time collaboration key |
GOOGLE_SERVICE_ACCOUNT_KEY | Production only | GCP service account key JSON (single line) for Cloud Run OIDC auth |
DOCS_MODE | Optional | Controls /docs route: placeholder (default), redirect, embed |
DOCS_URL | Optional | External Mintlify docs URL (used when DOCS_MODE=embed or redirect) |
TF_VAR_dolt_db_password | Terraform only | Dolt DB password for Terraform applies |
TF_VAR_beads_api_key | Terraform only | Beads API key for Terraform applies |
CGO_ENABLED=1 must be set. The Beads CLI (bd) uses native Go bindings and will fail without it.
Firebase Credentials
Contact the team for Firebase project credentials. For local-only development, the Firebase emulator can be used instead (see Local Dolt + Firebase Emulators).
Step 4: Start the Beads Backend
The platform uses a local Dolt database as the Beads (task tracking) backend. Start it with Docker Compose:
docker-compose up -d beads-backend beads-api
docker-compose.yml):
| Service | Container | Port | Description |
|---|
beads-backend | beads-backend | 3307 (host) → 3306 (container) | Dolt SQL Server — the Beads data store |
beads-api | beads-api | 8080 | Beads HTTP API — used by the bd CLI |
The Beads API runs in open/dev auth mode locally (BEADS_API_KEY is intentionally unset in docker-compose.yml). No authentication is required for local Beads operations.
infrastructure/beads-backend/README.md.
After starting the Docker services, configure the bd CLI to connect to your local Dolt backend [based on repo evidence from infrastructure/beads-backend/README.md]:
# Set mode to server
bd dolt set mode server
# Connect to the local container (mapped to port 3307)
bd dolt set host 127.0.0.1
bd dolt set port 3307
bd dolt set user root
# Verify the connection
bd dolt show
bd status
Step 6: Start the Development Server
The platform will be available at http://localhost:3000.
Step 7: (Optional) Full Stack via Docker Compose
To run the entire platform stack in Docker (including the Next.js frontend):
This starts all three services: beads-backend, beads-api, and platform-web (Next.js on port 3000).
For active development, running bun run dev directly (Step 6) is faster since it supports hot reload. Use the full Docker Compose stack only when you want to test the containerized production build.
Optional: Firebase Emulators
For fully offline development without a real Firebase project, uncomment these variables in .env.local:
NEXT_PUBLIC_FIREBASE_USE_EMULATOR=true
NEXT_PUBLIC_FIREBASE_EMULATOR_HOST=localhost
NEXT_PUBLIC_FIREBASE_EMULATOR_PORT=8080
Development Scripts
| Script | Command | Description |
|---|
| Dev server | bun run dev | Starts Next.js development server with hot reload |
| Build | bun run build | Production build (includes TypeScript type checking) |
| Lint | bun run lint | Run ESLint across the project |
| Start | bun run start | Start the compiled production build |
Troubleshooting
Build fails with TypeScript errors
Run bun run build and address the reported type errors before committing. All commits must pass the build.
bd command fails with CGO errors
Ensure CGO_ENABLED=1 is set in your .env.local or shell environment.
Firebase auth errors
Ensure Firebase credentials are set in .env.local. If using emulators, confirm NEXT_PUBLIC_FIREBASE_USE_EMULATOR=true.
Port 3000 already in use
lsof -ti:3000 | xargs kill -9
docker-compose ps. The beads-api container must be healthy.
Port 3307 already in use
Another MySQL/Dolt process may be running locally. Stop it or change the mapped port in docker-compose.yml.
