LobeHub
LobeHub

Deploying LobeHub Server Database Version with Docker Compose

Upgrading an existing Docker Compose deployment? The latest docker-compose.yml adds a gateway service for Gateway Mode. Update .env as described in Upgrading an Existing Deployment before starting it. Otherwise the gateway container keeps restarting, agent runs fall back to the browser, and docker logs lobehub prints an ACTION REQUIRED warning.

Quick Start

System Compatibility Notes

  • One-click deployment is supported in Unix environments (Linux/macOS).

  • Windows users must run through WSL 2.

  • The one-click startup script is only for initial deployment; for subsequent deployments, please refer to the Custom Deployment section.

  • Port occupation check: Ensure that ports 3210, 9000, 9001, 8787, and 8788 are available.

Execute the following commands to set up the deployment environment; the directory lobehub will be used to store your configuration files and subsequent database files.

mkdir lobehub && cd lobehub

Fetch and execute the deployment script:

*.sh
Shell
bash <(curl -fsSL https://lobe.li/setup.sh) -l en

The script supports the following deployment modes; please choose the appropriate mode based on your needs and read the rest of the documentation.

  • Local Mode (default): Accessible only locally, not supporting LAN/public access; suitable for initial experiences.
  • Port Mode: Supports LAN/public http access; suitable for no domain or private network use.
  • Domain Mode: Supports LAN/public http/https access with reverse proxy; suitable for personal or team use.

In the script's options prompt (Option1/Option2)[Option1]: (Option1 / Option2) indicates selectable options, while [Option1] indicates the default option; simply press enter to choose the default.

Local Mode

Complete Remaining Configuration in Interactive Script

Continue pressing enter to use the default configuration.

Check Configuration Generation Report

After the script finishes running, check the configuration generation report which includes service URLs and passwords.

*.txt
Plaintext
The results of the secure key generation are as follows:
LobeHub:
  - URL: http://localhost:3210
RustFS:
  - URL: http://localhost:9000
  - Username: admin
  - Password: 8c82ea41
Agent Gateway:
  - URL: http://localhost:8787

Start Docker

docker compose up -d

Check Logs

docker logs -f lobehub

If you see the following logs in the container, it means the startup was successful:

*.txt
Plaintext
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        http://localhost:3210
  - Network:      http://0.0.0.0:3210

 ✓ Starting...
 ✓ Ready in 95ms

Access Application

Visit your LobeHub service at http://localhost:3210.

Port Mode

Complete Remaining Configuration in Interactive Script

In port mode, you need to complete the following based on the script prompts:

  • Server IP address settings: for LAN/public access.
  • Regenerate secure keys: We highly recommend regenerating the secure keys; if you lack the key generation library required by the script, we suggest referring to the Custom Deployment section for key modifications.

Check Configuration Generation Report

After the script finishes running, check the configuration generation report which includes service URLs and passwords.

*.txt
Plaintext
The results of the secure key generation are as follows:
LobeHub:
  - URL: http://your_server_ip:3210
RustFS:
  - URL: http://your_server_ip:9000
  - Username: admin
  - Password: dbac8440
Agent Gateway:
  - URL: http://your_server_ip:8787

Start Docker

docker compose up -d

Check Logs

docker logs -f lobehub

If you see the following logs in the container, it means the startup was successful:

*.txt
Plaintext
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        http://your_server_ip:3210
  - Network:      http://0.0.0.0:3210
 ✓ Starting...
 ✓ Ready in 95ms

Access Application

You can access your LobeHub service at http://your_server_ip:3210.

Domain Mode

Complete Reverse Proxy Configuration

In domain mode, you need to complete the reverse proxy configuration and ensure that the LAN/public can access the following services. Please use a reverse proxy to map the following service ports to the domain names:

DomainProxy PortRequired
lobe.example.com3210Yes
s3.example.com9000Yes
gateway.example.com8787Yes
s3-ui.example.com9001

Complete Remaining Configuration in Interactive Script

In domain mode, you need to complete the following configurations based on script prompts:

  • Domain setup for the LobeHub service: lobe.example.com
  • Domain setup for the S3 service: s3.example.com
  • Domain setup for the Agent Gateway: gateway.example.com (the reverse proxy must allow WebSocket upgrades)
  • Choose the access protocol: http or https
  • Regenerate secure keys: We highly recommend regenerating the secure keys; if you lack the key generation library required by the script, we suggest referring to the Custom Deployment section for key modifications.

Single Domain Deployment If you only have one domain, you can distinguish services by different ports:

  • Domain setup for the LobeHub service: lobe.example.com:${PORT1}
  • Domain setup for the S3 service: lobe.example.com:${PORT2} You need to configure forwarding rules for each port in the reverse proxy.

Port Mode vs Domain Mode:

  • Port Mode: The script automatically uses default ports (3210/9000/9001/8787/8788)
  • Domain Mode: You can customize ports (via reverse proxy configuration)

The following issues may impede access to your service:

  • The domain configuration here must match the reverse proxy configuration in step 1.

  • If you are using Cloudflare for domain resolution and have activated full proxy, please use the https protocol.

  • If you have used the HTTPS protocol, ensure that your domain certificate is correctly configured; one-click deployment does not support self-signed certificates by default.

Check Configuration Generation Report

After the script finishes running, check the configuration generation report which includes service URLs and passwords.

*.txt
Plaintext
The results of the secure key generation are as follows:
LobeHub:
  - URL: https://lobe.example.com
RustFS:
  - URL: https://s3.example.com
  - Username: admin
  - Password: dbac8440
Agent Gateway:
  - URL: https://gateway.example.com

Start Docker

docker compose up -d

Check Logs

docker logs -f lobehub

If you see the following logs in the container, it indicates a successful startup:

*.txt
Plaintext
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        https://localhost:3210
  - Network:      http://0.0.0.0:3210
  ✓ Starting...
  ✓ Ready in 95ms

Access Application

You can access your LobeHub service via https://lobe.example.com.

Custom Deployment

This section mainly introduces the configurations that need to be modified to customize the deployment of the LobeHub service in different network environments. Before starting, you can download the Docker Compose configuration file and the environment variable configuration file.

*.sh
Shell
curl -O https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/docker-compose.yml
curl -O https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/.env.example
mv .env.example .env

Prerequisites

Generally, to fully run the LobeHub database version, you will need at least the following three services:

  • The LobeHub database version itself
  • PostgreSQL database with PGVector plugin
  • Object storage service that supports S3 protocol

These services can be combined through self-hosting or online cloud services to meet various deployment needs. In this article, we provide a Docker Compose configuration entirely based on open-source self-hosted services, which can be used directly to start the LobeHub database version or modified to suit your requirements.

We use RustFS as the local S3 object storage service by default. To configure SSO authentication services, please refer to the Authentication Services documentation.

If your network topology is complex, please make sure these services can communicate properly within your network environment.

Necessary Configuration

Now, we will introduce the necessary configurations for running these services:

  1. S3 Object Storage

LobeHub needs to provide a public access URL for object files for the LLM service provider, so you need to configure the S3 Endpoint:

Using S3_ENDPOINT=http://rustfs:9000 directly will prevent conversation image uploads from working (browser cannot resolve container names), but avatar uploads are not affected.

*.txt
Plaintext
S3_ENDPOINT=https://s3.example.com

S3_ENDPOINT only needs to be reachable from browsers: docker-compose.yml sets S3_INTERNAL_ENDPOINT=http://rustfs:9000, so the LobeHub server itself reaches RustFS inside the Compose network.

  1. PostgreSQL

This configuration is found in the docker-compose.yml file, and you will need to configure the database name and password:

*.yml
YAML
services:
  lobe:
    environment:
      - 'DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgresql:5432/${LOBE_DB_NAME}'
  1. Internal Communication URL (INTERNAL_APP_URL)

INTERNAL_APP_URL is required for Docker Compose deployments. LobeHub's async features (e.g., AI image generation) require the container to make HTTP requests to itself internally. If INTERNAL_APP_URL is not set, the system falls back to APP_URL. When APP_URL is a host IP (e.g., http://10.1.7.146:8080), the container cannot reach that address internally, causing async features like image generation to silently fail.

*.txt
Plaintext
INTERNAL_APP_URL=http://localhost:3210
  • APP_URL: Used for browser/client access, OAuth callbacks, webhooks, etc.
  • INTERNAL_APP_URL: Used for internal server-to-server communication within the container (bypasses CDN/proxy/host network)

For Docker Compose deployments, we recommend using http://localhost:3210 (container calling itself) or http://lobe:3210 (using service name for container-to-container communication).

  1. Agent Gateway (Gateway Mode)

The gateway service lets agent runs execute on the LobeHub server instead of in the browser. It needs the following values in .env, which setup.sh fills in automatically:

  • AGENT_GATEWAY_URL: the gateway address as reached by the browser, such as https://gateway.example.com or http://your_server_ip:8787. The browser opens a WebSocket connection to it, so a reverse proxy in front of it must allow WebSocket upgrades and long read timeouts. The LobeHub server reaches the gateway at http://gateway:8787 inside the Compose network.
  • GATEWAY_SERVICE_TOKEN: a random token shared by LobeHub and the gateway.
  • JWKS_KEY: the RS256 key set LobeHub signs internal JWTs with. Every deployment must use its own key, and it stays in the lobe container.
  • JWKS_PUBLIC_KEY: the same key without its private fields. Only this value is passed to the gateway, which verifies browser sessions with it.
*.sh
Shell
# GATEWAY_SERVICE_TOKEN
openssl rand -hex 32
# JWKS_KEY and JWKS_PUBLIC_KEY (paste both lines into .env)
docker run --rm --entrypoint /bin/node lobehub/lobehub -e 'const c=require("crypto");const {privateKey,publicKey}=c.generateKeyPairSync("rsa",{modulusLength:2048});const meta={alg:"RS256",kid:c.randomBytes(8).toString("hex"),use:"sig"};console.log("JWKS_KEY="+JSON.stringify({keys:[{...privateKey.export({format:"jwk"}),...meta}]}));console.log("JWKS_PUBLIC_KEY="+JSON.stringify({keys:[{...publicKey.export({format:"jwk"}),...meta}]}))'

Upgrading an existing deployment? Follow Upgrading an Existing Deployment first. The gateway keeps its state in memory, so runs in progress are interrupted when it restarts.

Devices joined with lh connect --gateway http://your_server_ip:8788 can run local tools for this deployment through the device gateway on port 8788.

Optional: set DEVICE_GATEWAY_PUBLIC_URL in .env to a client-accessible gateway address, such as http://your_server_ip:8788. Do not use the container-internal address http://gateway:8788. Leave it unset to keep using --gateway above. For domain setup, see Connecting the Device Gateway.

Upgrading an Existing Deployment

Finish these steps before starting the new docker-compose.yml. Until they are done, the lobe-gateway container keeps restarting, agent runs fall back to the browser, and docker logs lobehub prints an ACTION REQUIRED warning at startup.

Back up .env and download the new Compose file

*.sh
Shell
cp .env .env.bak
curl -O https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/docker-compose.yml

Add the gateway variables to .env

*.txt
Plaintext
AGENT_GATEWAY_PORT=8787
DEVICE_GATEWAY_PORT=8788
# Gateway address as reached by the browser, e.g. https://gateway.example.com
AGENT_GATEWAY_URL=http://your_server_ip:8787
DEVICE_GATEWAY_URL=http://gateway:8788
# Output of: openssl rand -hex 32
GATEWAY_SERVICE_TOKEN=

Then add JWKS_PUBLIC_KEY, the public half of your existing JWKS_KEY, by running this in the directory that holds .env and pasting its output:

*.sh
Shell
docker run --rm -e JWKS_KEY="$(grep '^JWKS_KEY=' .env | cut -d= -f2-)" --entrypoint /bin/node lobehub/lobehub -e 'const {d,p,q,dp,dq,qi,...pub}=JSON.parse(process.env.JWKS_KEY).keys[0];console.log("JWKS_PUBLIC_KEY="+JSON.stringify({keys:[pub]}))'

In domain mode, also reverse proxy the gateway domain to port 8787 with WebSocket upgrades enabled.

Replace the example JWKS_KEY

If JWKS_KEY in .env is still the value shipped in the old .env.example (its kid is 6823046760c5d460), anyone can forge tokens your deployment accepts. Generate a new key pair with the command in Necessary Configuration and replace both JWKS_KEY and JWKS_PUBLIC_KEY. Desktop and CLI clients may need to sign in again afterwards.

Recreate the stack

*.sh
Shell
docker compose up -d --force-recreate

FAQ

Database Migration Issues

You can check the logs using the following command:

docker logs -f lobehub

In our official Docker images, database schema migration is automatically performed before starting. Our official images guarantee the stability of "empty database -> complete tables" for automatic table creation. Therefore, we recommend your database instance use an empty table instance to avoid the trouble of manually maintaining table structure or migrations.

If you encounter issues during table creation, you can try the following command to forcibly remove the database container and restart:

*.sh
Shell
docker compose down  # Stop the service
sudo rm -rf ./data   # Remove mounted database data
docker compose up -d # Restart

Reverse Proxy Configuration

For production deployments with a custom domain and HTTPS, configure a reverse proxy in front of LobeHub.

Nginx:

*.txt
Plaintext
server {
    listen 443 ssl http2;
    server_name lobehub.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3210;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy (automatically handles HTTPS with Let's Encrypt):

*.txt
Plaintext
lobehub.example.com {
    reverse_proxy localhost:3210
}

Traefik — add labels to the lobe service in docker-compose.yml:

*.yml
YAML
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.lobehub.rule=Host(`lobehub.example.com`)"
  - "traefik.http.routers.lobehub.entrypoints=websecure"
  - "traefik.http.routers.lobehub.tls.certresolver=letsencrypt"

Management Commands

*.sh
Shell
# View logs (all services)
docker compose logs -f

# View logs for a specific service
docker compose logs -f lobe

# Restart all services
docker compose restart

# Restart a specific service
docker compose restart lobe

# Stop all services
docker compose stop

# Update to the latest version
docker compose pull && docker compose up -d

Backup and Restore

Database backup:

*.sh
Shell
docker compose exec postgresql pg_dump -U postgres lobechat > backup.sql

Restore from backup:

*.sh
Shell
docker compose exec -T postgresql psql -U postgres lobechat < backup.sql

File storage (RustFS) backup:

*.sh
Shell
docker compose exec rustfs tar czf /tmp/backup.tar.gz /data
docker cp lobe-rustfs:/tmp/backup.tar.gz ./rustfs-backup.tar.gz

Redis — Redis automatically persists data with AOF. To manually save:

*.sh
Shell
docker compose exec redis redis-cli BGSAVE

Resource Requirements

Minimum (light usage):

  • CPU: 2 cores
  • RAM: 4 GB
  • Storage: 20 GB

Recommended (production):

  • CPU: 4+ cores
  • RAM: 8+ GB
  • Storage: 50+ GB (depending on file uploads)

For high-traffic deployments, consider using managed database (Neon, Supabase, RDS), Redis cluster for caching, and a CDN for static assets.

Troubleshooting

Service won't start

Check service status and logs:

*.sh
Shell
docker compose ps
docker compose logs [service-name]

Common causes: port already in use (change LOBE_PORT in .env), insufficient disk space, or database connection failure.

Database connection error

Verify PostgreSQL is healthy:

*.sh
Shell
docker compose exec postgresql pg_isready -U postgres

If unhealthy, check its logs: docker compose logs postgresql

File upload fails

Check RustFS service:

*.sh
Shell
docker compose logs rustfs
docker compose logs rustfs-init

rustfs-init also applies the bucket CORS rule that browser uploads need. If uploads fail in the browser with a network error, re-run it with docker compose up -d --force-recreate rustfs-init.

Verify the bucket was created: docker compose exec rustfs ls /data/lobe

Running out of disk space

Check usage: docker system df

Clean up unused resources (make sure to back up first):

*.sh
Shell
docker system prune -a --volumes

Configuring Authentication

To configure SSO authentication services (such as Casdoor, Logto, etc.), please refer to the Authentication Services documentation.