Local Development - Vibe Kanban

This guide walks you through setting up a local Vibe Kanban Cloud instance for development and testing.

Prerequisites

Before you begin, ensure you have:

Docker and Docker Compose installed
Git to clone the repository
Node.js 20+ and pnpm (for running the desktop client)
A GitHub or Google OAuth application

Step 1: Clone the Repository

git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban

Step 2: Create OAuth Application

You need at least one OAuth provider. Choose GitHub, Google, or both.

GitHub OAuth
Google OAuth

Go to GitHub Developer Settings
Click New OAuth App
Fill in the details:
- Application name: Vibe Kanban Local
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/v1/oauth/github/callback
Click Register application
Copy the Client ID
Click Generate a new client secret and copy it

Go to Google Cloud Console
Create a new project or select an existing one
Click Create Credentials → OAuth client ID
Select Web application
Add authorized redirect URI: http://localhost:3000/v1/oauth/google/callback
Click Create
Copy the Client ID and Client Secret

Step 3: Configure Environment

Create a .env.remote file in crates/remote/:

# Generate a secure JWT secret
openssl rand -base64 48

Copy the output and create your .env.remote:

.env.remote

# Required - JWT secret for authentication
VIBEKANBAN_REMOTE_JWT_SECRET=<paste_your_generated_secret_here>

# Optional - Password for ElectricSQL database role (electric_sync user)
ELECTRIC_ROLE_PASSWORD=

# OAuth — configure at least one provider. Leave the other empty or remove it.
GITHUB_OAUTH_CLIENT_ID=your_github_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_github_client_secret

# Google OAuth (leave empty if not using Google login)
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=

# Relay (required for relay/tunnel features)
# For plain HTTP local dev:
VITE_RELAY_API_BASE_URL=http://localhost:8082

# Email invitations (optional — leave empty to disable)
LOOPS_EMAIL_API_KEY=

# Loops transactional email template IDs (optional — defaults are the upstream templates).
# Override these with your own Loops account template IDs if using a custom Loops account.
LOOPS_INVITE_TEMPLATE_ID=cmhvy2wgs3s13z70i1pxakij9
LOOPS_REVIEW_READY_TEMPLATE_ID=cmj47k5ge16990iylued9by17
LOOPS_REVIEW_FAILED_TEMPLATE_ID=cmj49ougk1c8s0iznavijdqpo

For production or self-hosting on a server, add PUBLIC_BASE_URL (your public URL, e.g. https://kanban.example.com) and REMOTE_SERVER_PORTS=0.0.0.0:3000:8081 so the server is reachable from other hosts. Defaults keep local dev unchanged.

Never commit .env.remote to version control. It’s already in .gitignore.

Step 4: Start the Stack

From the crates/remote directory, start all services:

cd crates/remote
docker compose --env-file .env.remote -f docker-compose.yml up --build

Or from the repo root:

pnpm run remote:dev

This starts:

PostgreSQL on port 5433 (external) / 5432 (internal)
ElectricSQL on port 3000 (internal only, used by Remote Server for real-time sync)
Remote Server on port 3000 (external) / 8081 (internal)
Relay Server on port 8082 (external and internal)

The remote server binds to 127.0.0.1:3000 only - it’s not accessible from other machines. For production, use a reverse proxy.

Wait until you see health checks passing:

remote-server-1  | INFO remote: Server listening on 0.0.0.0:8081

Step 5: Access the Web Interface

Open http://localhost:3000 in your browser. You should see the Vibe Kanban Cloud login page. Sign in with your configured OAuth provider (GitHub or Google).

Step 6: Connect the Desktop Client (Optional)

To use the desktop client with your local server:

# In a new terminal, from the repository root
export VK_SHARED_API_BASE=http://localhost:3000

pnpm install
pnpm run dev

The desktop client will now connect to your local Cloud instance instead of the hosted version. To test relay/tunnel mode end-to-end, add:

export VK_SHARED_API_BASE=https://localhost:3001
export VK_SHARED_RELAY_API_BASE=https://relay.localhost:3001
export VK_TUNNEL=1

This mode requires local HTTPS + Caddy routing (next step).

Step 7: Optional Local HTTPS + Caddy (required for tunnel-mode testing)

Use the checked-in Caddyfile.example in the repository root. It routes:

localhost:3001 -> remote server (127.0.0.1:3000)
relay.localhost:3001 and *.relay.localhost:3001 -> relay server (127.0.0.1:8082)

caddy run --config Caddyfile.example

If you use this HTTPS setup, update OAuth callback URLs to:

GitHub: https://localhost:3001/v1/oauth/github/callback
Google: https://localhost:3001/v1/oauth/google/callback

Stopping the Stack

To stop all services:

docker compose down

To stop and remove all data (fresh start):

docker compose down -v

Troubleshooting

Database connection errors

Ensure the database is healthy before the server starts:

# Check database status
docker compose ps

# View database logs
docker compose logs remote-db

OAuth callback errors

Verify your OAuth callback URLs match exactly for your setup:

HTTP local stack:
- GitHub: http://localhost:3000/v1/oauth/github/callback
- Google: http://localhost:3000/v1/oauth/google/callback
HTTPS + Caddy:
- GitHub: https://localhost:3001/v1/oauth/github/callback
- Google: https://localhost:3001/v1/oauth/google/callback

ElectricSQL fails to connect

ElectricSQL requires the electric_sync database user, which is created automatically by the Remote Server on first startup. If ElectricSQL fails to connect:

Ensure the Remote Server has started successfully and run its migrations
Check that ELECTRIC_ROLE_PASSWORD is set in your .env.remote
Restart the stack — ElectricSQL will retry the connection

docker compose --env-file .env.remote -f docker-compose.yml restart electric

Port already in use

If port 3000 is in use, you can change it in docker-compose.yml:

ports:
  - "127.0.0.1:3001:8081"  # Change 3001 to your preferred port

Update your OAuth callback URLs accordingly.

Relay health endpoint returns HTML instead of JSON

Problem: curl -sk https://relay.localhost:3001/health returns HTML, and relay/tunnel fails.Cause: Caddy routed relay hostnames to the remote app (:3000) instead of relay server (:8082).Solution:

Use host-specific routing for relay.localhost and *.relay.localhost
Verify:
- curl -sk https://relay.localhost:3001/health returns {"status":"ok"}
- curl -sk https://localhost:3001/v1/health returns remote server health JSON

Next Steps

Once you have local development working, you can:

Deploy to Fly.io for production (coming soon)
Deploy with Docker Compose on your own server (coming soon)

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Create OAuth Application

​Step 3: Configure Environment

​Step 4: Start the Stack

​Step 5: Access the Web Interface

​Step 6: Connect the Desktop Client (Optional)

​Step 7: Optional Local HTTPS + Caddy (required for tunnel-mode testing)

​Stopping the Stack

​Troubleshooting

​Next Steps

Prerequisites

Step 1: Clone the Repository

Step 2: Create OAuth Application

Step 3: Configure Environment

Step 4: Start the Stack

Step 5: Access the Web Interface

Step 6: Connect the Desktop Client (Optional)

Step 7: Optional Local HTTPS + Caddy (required for tunnel-mode testing)

Stopping the Stack

Troubleshooting

Next Steps