mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-27 13:29:15 +07:00
7ba15cceba
* 🔥 chore(docker-compose): remove Casdoor SSO dependency Casdoor is no longer needed since BetterAuth now supports email/password registration natively. LOBE-3907 * ♻️ refactor(docker-compose): restructure directories - Rename local/ to dev/ for development dependencies - Remove logto/ and zitadel/ from production/ - Restore Casdoor config in production/grafana/ - Simplify dev/ to core services only (postgresql, redis, rustfs, searxng) - Update docker-compose.development.yml to use dev/ - Remove minio-bucket.config.json (switched to rustfs) * ♻️ refactor(docker-compose): simplify dev environment setup - Remove docker-compose.development.yml, use dev/docker-compose.yml directly - Add npm scripts: dev:docker, dev:docker:down, dev:docker:reset - Simplify .env.example.development (remove variable refs, redundant vars) - Update docker-compose/dev/.env.example (consistent passwords) - Add docker-compose/dev/data/ to .gitignore - Update setup docs: use npm scripts, remove image generation section * 🔧 chore: add SSRF_ALLOW_PRIVATE_IP_ADDRESS to dev env example * 🔒 security: auto-generate KEY_VAULTS_SECRET and AUTH_SECRET in setup.sh - Remove hardcoded secrets from docker-compose.yml - Add placeholders to .env.example files - Generate secrets dynamically in setup.sh using openssl rand -base64 32 * 🔧 chore(docker-compose): expose SearXNG port and improve dev scripts - Add SearXNG port mapping (8180:8080) for host access - Use --wait flag in dev:docker to ensure services are healthy - Include db:migrate in dev:docker:reset for one-command reset - Update MinIO reference to RustFS in zh-CN docs - Add SearXNG to service URLs and port conflict docs
176 lines
4.8 KiB
Plaintext
176 lines
4.8 KiB
Plaintext
---
|
|
title: Environment Setup Guide
|
|
description: >-
|
|
Step-by-step guide to set up LobeHub development environment locally or
|
|
online.
|
|
tags:
|
|
- LobeHub
|
|
- Development Setup
|
|
- Node.js
|
|
- PNPM
|
|
- Bun
|
|
- Git
|
|
- Docker
|
|
- PostgreSQL
|
|
---
|
|
|
|
# Environment Setup Guide
|
|
|
|
Welcome to the LobeHub development environment setup guide.
|
|
|
|
## Online Development
|
|
|
|
If you have access to GitHub Codespaces, you can click the button below to enter the online development environment with just one click:
|
|
|
|
[![][codespaces-shield]][codespaces-link]
|
|
|
|
## Local Development
|
|
|
|
Before starting development on LobeHub, you need to install and configure some necessary software and tools in your local environment. This document will guide you through these steps.
|
|
|
|
### Development Environment Requirements
|
|
|
|
First, you need to install the following software:
|
|
|
|
- Node.js: LobeHub is built on Node.js, so you need to install Node.js. We recommend installing the latest stable version.
|
|
- PNPM: We use PNPM as the preferred package manager. You can download and install it from the [PNPM official website](https://pnpm.io/installation).
|
|
- Bun: We use Bun as the npm scripts runner. You can download and install it from the [Bun official website](https://bun.com/docs/installation).
|
|
- Git: We use Git for version control. You can download and install it from the Git official website.
|
|
- Docker: Required for running PostgreSQL, RustFS, and other services. You can download and install it from the [Docker official website](https://www.docker.com/get-started).
|
|
- IDE: You can choose your preferred integrated development environment (IDE). We recommend using WebStorm/VSCode.
|
|
|
|
### VSCode Users
|
|
|
|
We recommend installing the extensions listed in [.vscode/extensions.json](https://github.com/lobehub/lobehub/blob/main/.vscode/extensions.json) for the best development experience.
|
|
|
|
### Project Setup
|
|
|
|
After installing the above software, you can start setting up the LobeHub project.
|
|
|
|
#### 1. Get the Code
|
|
|
|
First, you need to clone the LobeHub codebase from GitHub. Run the following command in the terminal:
|
|
|
|
```bash
|
|
git clone https://github.com/lobehub/lobehub.git
|
|
cd lobehub
|
|
```
|
|
|
|
#### 2. Install Dependencies
|
|
|
|
Use PNPM to install the project's dependencies:
|
|
|
|
```bash
|
|
pnpm i
|
|
```
|
|
|
|
#### 3. Configure Environment
|
|
|
|
Copy the example environment files:
|
|
|
|
```bash
|
|
# Docker services configuration
|
|
cp docker-compose/dev/.env.example docker-compose/dev/.env
|
|
|
|
# Next.js development server configuration
|
|
cp .env.example.development .env
|
|
```
|
|
|
|
Edit these files as needed:
|
|
|
|
- `docker-compose/dev/.env` - Docker services (PostgreSQL, Redis, RustFS, SearXNG)
|
|
- `.env` - Next.js dev server (database connection, S3 storage, auth, etc.)
|
|
|
|
#### 4. Start Docker Services
|
|
|
|
Start all required services using Docker Compose:
|
|
|
|
```bash
|
|
bun run dev:docker
|
|
```
|
|
|
|
This will start the following services:
|
|
|
|
- PostgreSQL database (port 5432)
|
|
- Redis cache (port 6379)
|
|
- RustFS storage (API port 9000, Console port 9001)
|
|
- SearXNG search (port 8180)
|
|
|
|
You can check all Docker services are running by running:
|
|
|
|
```bash
|
|
docker compose -f docker-compose/dev/docker-compose.yml ps
|
|
```
|
|
|
|
#### 5. Run Database Migrations
|
|
|
|
Execute the database migration script to create all necessary tables:
|
|
|
|
```bash
|
|
pnpm db:migrate
|
|
```
|
|
|
|
You should see: `✅ database migration pass.`
|
|
|
|
#### 6. Start Development Server
|
|
|
|
Launch the LobeHub development server:
|
|
|
|
```bash
|
|
bun run dev
|
|
```
|
|
|
|
Now, you can open `http://localhost:3010` in your browser, and you should see the welcome page of LobeHub. This indicates that you have successfully set up the development environment.
|
|
|
|
|
|
|
|
## Service URLs
|
|
|
|
When running with Docker Compose development setup:
|
|
|
|
- **PostgreSQL**: `postgres://postgres@localhost:5432/lobechat`
|
|
- **Redis**: `redis://localhost:6379`
|
|
- **RustFS API**: `http://localhost:9000`
|
|
- **RustFS Console**: `http://localhost:9001`
|
|
- **SearXNG**: `http://localhost:8180`
|
|
- **Application**: `http://localhost:3010`
|
|
|
|
## Troubleshooting
|
|
|
|
### Reset Services
|
|
|
|
If you encounter issues, you can reset the entire stack:
|
|
|
|
```bash
|
|
# Completely reset Docker environment (delete all data and restart)
|
|
bun run dev:docker:reset
|
|
```
|
|
|
|
### Port Conflicts
|
|
|
|
If ports are already in use:
|
|
|
|
```bash
|
|
# Check what's using the ports
|
|
lsof -i :5432 # PostgreSQL
|
|
lsof -i :6379 # Redis
|
|
lsof -i :9000 # RustFS API
|
|
lsof -i :9001 # RustFS Console
|
|
lsof -i :8180 # SearXNG
|
|
```
|
|
|
|
### Database Migrations
|
|
|
|
Run migrations manually when needed:
|
|
|
|
```bash
|
|
pnpm db:migrate
|
|
```
|
|
|
|
---
|
|
|
|
During the development process, if you encounter any issues with environment setup or have any questions about LobeHub development, feel free to ask us at any time. We look forward to seeing your contributions!
|
|
|
|
[codespaces-link]: https://codespaces.new/lobehub/lobehub
|
|
[codespaces-shield]: https://github.com/codespaces/badge.svg
|