mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-27 13:29:15 +07:00
249 lines
7.2 KiB
Plaintext
249 lines
7.2 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, MinIO, 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 file to create your Docker Compose configuration:
|
|
|
|
```bash
|
|
cp docker-compose/local/.env.example docker-compose/local/.env
|
|
```
|
|
|
|
Edit `docker-compose/local/.env` as needed for your development setup. This file contains all necessary environment variables for the Docker services and configures:
|
|
|
|
- **Database**: PostgreSQL with connection string
|
|
- **Authentication**: Better Auth with Casdoor SSO
|
|
- **Storage**: MinIO S3-compatible storage
|
|
- **Search**: SearXNG search engine
|
|
|
|
#### 4. Start Docker Services
|
|
|
|
Start all required services using Docker Compose:
|
|
|
|
```bash
|
|
docker-compose -f docker-compose.development.yml up -d
|
|
```
|
|
|
|
This will start the following services:
|
|
|
|
- PostgreSQL database (port 5432)
|
|
- MinIO storage (port 9000)
|
|
- Casdoor authentication (port 8000)
|
|
- SearXNG search (port 8080)
|
|
|
|
You can check all Docker services are running by running:
|
|
|
|
```bash
|
|
docker-compose -f docker-compose.development.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.
|
|
|
|
|
|
|
|
## Image Generation Development
|
|
|
|
When working with image generation features (text-to-image, image-to-image), the Docker Compose setup already includes all necessary storage services for handling generated images and user uploads.
|
|
|
|
### Image Generation Configuration
|
|
|
|
The existing Docker Compose configuration already includes MinIO storage service and all necessary environment variables in `docker-compose/local/.env.example`. No additional setup is required.
|
|
|
|
### Image Generation Architecture
|
|
|
|
The image generation feature requires:
|
|
|
|
- **PostgreSQL**: Stores metadata about generated images
|
|
- **MinIO/S3**: Stores the actual image files
|
|
|
|
### Storage Configuration
|
|
|
|
The `docker-compose/local/.env.example` file includes all necessary S3 environment variables:
|
|
|
|
```bash
|
|
# S3 Storage Configuration (MinIO for local development)
|
|
S3_ACCESS_KEY_ID=${MINIO_ROOT_USER}
|
|
S3_SECRET_ACCESS_KEY=${MINIO_ROOT_PASSWORD}
|
|
S3_ENDPOINT=http://localhost:${MINIO_PORT}
|
|
S3_BUCKET=${MINIO_LOBE_BUCKET}
|
|
S3_ENABLE_PATH_STYLE=1 # Required for MinIO
|
|
S3_SET_ACL=0 # MinIO compatibility
|
|
```
|
|
|
|
### File Storage Structure
|
|
|
|
Generated images and user uploads are organized in the MinIO bucket:
|
|
|
|
```
|
|
lobe/ # S3 Bucket (MINIO_LOBE_BUCKET)
|
|
├── generated/ # Generated images
|
|
│ └── {userId}/
|
|
│ └── {sessionId}/
|
|
│ └── {imageId}.png
|
|
└── uploads/ # User uploads for image-to-image
|
|
└── {userId}/
|
|
└── {fileId}.{ext}
|
|
```
|
|
|
|
### Development Workflow for Images
|
|
|
|
When developing image generation features, generated images will be:
|
|
|
|
1. Created by the AI model
|
|
2. Uploaded to S3/MinIO via presigned URLs
|
|
3. Metadata stored in PostgreSQL
|
|
4. Served via the public S3 URL
|
|
|
|
Example code for testing image upload:
|
|
|
|
```typescript
|
|
// Example: Upload generated image
|
|
const uploadUrl = await trpc.upload.createPresignedUrl.mutate({
|
|
filename: 'generated-image.png',
|
|
contentType: 'image/png',
|
|
});
|
|
|
|
// Upload to S3
|
|
await fetch(uploadUrl, {
|
|
method: 'PUT',
|
|
body: imageBlob,
|
|
headers: { 'Content-Type': 'image/png' },
|
|
});
|
|
```
|
|
|
|
### Service URLs
|
|
|
|
When running with Docker Compose development setup:
|
|
|
|
- **PostgreSQL**: `postgres://postgres@localhost:5432/LobeHub`
|
|
- **MinIO API**: `http://localhost:9000`
|
|
- **MinIO Console**: `http://localhost:9001` (admin/CHANGE\_THIS\_PASSWORD\_IN\_PRODUCTION)
|
|
- **Application**: `http://localhost:3010`
|
|
|
|
## Troubleshooting
|
|
|
|
### Reset Services
|
|
|
|
If you encounter issues, you can reset the entire stack:
|
|
|
|
```bash
|
|
# Stop and remove all containers
|
|
docker-compose -f docker-compose.development.yml down
|
|
|
|
# Remove volumes (this will delete all data)
|
|
docker-compose -f docker-compose.development.yml down -v
|
|
|
|
# Start fresh
|
|
docker-compose -f docker-compose.development.yml up -d
|
|
pnpm db:migrate
|
|
```
|
|
|
|
### Port Conflicts
|
|
|
|
If ports are already in use:
|
|
|
|
```bash
|
|
# Check what's using the ports
|
|
lsof -i :5432 # PostgreSQL
|
|
lsof -i :9000 # MinIO API
|
|
lsof -i :9001 # MinIO Console
|
|
```
|
|
|
|
### Database Migrations
|
|
|
|
The setup script runs migrations automatically. If you need to run them manually:
|
|
|
|
```bash
|
|
pnpm db:migrate
|
|
```
|
|
|
|
Note: In development mode with `pnpm dev:desktop`, migrations also run automatically on startup.
|
|
|
|
---
|
|
|
|
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
|