Skip to main content

​
Local Development Setup

This guide walks you through setting up LobeHub for local development.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Quick Start

1
Clone the Repository
2
git clone https://github.com/lobehub/lobe-chat.git
cd lobe-chat
3
Install Dependencies
4
Use pnpm to install all project dependencies:
5
pnpm install
6
Configure Environment
7
Copy the example environment files:
8
Docker Services
cp docker-compose/dev/.env.example docker-compose/dev/.env
Next.js Server
cp .env.example.development .env
9
Edit these files to configure:
10
  • docker-compose/dev/.env - PostgreSQL, Redis, RustFS, SearXNG settings
  • .env - Database connection, S3 storage, authentication, API keys
    • 11
    Start Docker Services
    12
    Start all required backend services:
    13
    bun run dev:docker
    14
    This starts:
    15
  • PostgreSQL (port 5432) - Primary database
  • Redis (port 6379) - Cache and session storage
  • RustFS (ports 9000/9001) - S3-compatible file storage
  • SearXNG (port 8180) - Search engine
    • 16
    Verify services are running:
    17
    docker compose -f docker-compose/dev/docker-compose.yml ps
    18
    Run Database Migrations
    19
    Create all necessary database tables:
    20
    pnpm db:migrate
    21
    You should see: ✅ database migration pass.
    22
    Start Development Server
    23
    Launch LobeHub:
    24
    Full Stack
    bun run dev
    SPA Only
    bun run dev:spa
    Next.js Only
    bun run dev:next
    25
    Open http://localhost:3010 in your browser.

    ​
    Service URLs

    When running the development environment:
    ServiceURL
    Applicationhttp://localhost:3010
    SPA Dev Serverhttp://localhost:9876
    PostgreSQLpostgres://postgres@localhost:5432/lobechat
    Redisredis://localhost:6379
    RustFS APIhttp://localhost:9000
    RustFS Consolehttp://localhost:9001
    SearXNGhttp://localhost:8180

    ​
    VS Code Setup

    For the best development experience with VS Code:
    1. Install recommended extensions from .vscode/extensions.json
    2. VS Code will prompt you automatically when you open the project
    3. Key extensions include:
      • ESLint
      • Prettier
      • TypeScript and JavaScript Language Features
      • Tailwind CSS IntelliSense

    ​
    Alternative Development Modes

    ​
    GitHub Codespaces

    Develop in the cloud with one click: Open in GitHub Codespaces

    ​
    Desktop App Development

    To work on the Electron desktop app: 
    cd apps/desktop
pnpm run dev
    See Desktop App Development for details.

    ​
    Mobile SPA Development

    bun run dev:spa:mobile
    Access at http://localhost:3012

    ​
    Troubleshooting

    ​
    Reset Everything

    If you encounter issues, reset the entire stack: 
    # Completely reset Docker environment (deletes all data)
bun run dev:docker:reset

    ​
    Port Conflicts

    Check what’s using a port: 
    lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis
lsof -i :3010  # App

    ​
    Database Connection Issues

    Ensure Docker services are running: 
    docker compose -f docker-compose/dev/docker-compose.yml ps
    Re-run migrations if needed: 
    pnpm db:migrate

    ​
    Clean Install

    Remove all node_modules and reinstall: 
    bun run clean:node_modules
pnpm install

    ​
    Next Steps

    Build docs developers (and LLMs) love

    Get started for freeTalk to us