lobehub/docs/self-hosting/platform/docker-compose.mdx

---
title: Deploying LobeHub with Docker Compose
description: >-
  Learn how to deploy the LobeHub service using Docker Compose, including
  configuration tutorials for various services.
tags:
  - Docker Compose
  - LobeHub
  - Docker Container
  - Deployment Guide
---

# Deploying LobeHub Server Database Version with Docker Compose

<div style={{display:"flex", gap: 4}}>
  [![][docker-release-shield]][docker-release-link]

  [![][docker-size-shield]][docker-size-link]

  [![][docker-pulls-shield]][docker-pulls-link]
</div>

## Quick Start

<Callout type="info">
  **System Compatibility Notes**

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

  - Windows users must run through [WSL 2](https://aka.ms/wsl).

  - The one-click startup script is only for initial deployment; for subsequent deployments, please refer to the [Custom Deployment](#custom-deployment) section.

  - Port occupation check: Ensure that ports `3210`, `9000`, and `9001` are available.
</Callout>

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.

```sh
mkdir lobehub && cd lobehub
```

Fetch and execute the deployment script:

```sh
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)](#local-mode): Accessible only locally, not supporting LAN/public access; suitable for initial experiences.
- [Port Mode](#port-mode): Supports LAN/public `http` access; suitable for no domain or private network use.
- [Domain Mode](#domain-mode): Supports LAN/public `http/https` access with reverse proxy; suitable for personal or team use.

<Callout type="info">
  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.
</Callout>

### Local Mode

<Steps>
  ### 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.

  ```log
  The results of the secure key generation are as follows:
  LobeHub:
    - URL: http://localhost:3210
  RustFS:
    - URL: http://localhost:9000
    - Username: admin
    - Password: 8c82ea41
  ```

  ### Start Docker

  ```sh
  docker compose up -d
  ```

  ### Check Logs

  ```sh
  docker logs -f lobehub
  ```

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

  ```log
  [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](http://localhost:3210).
</Steps>

### Port Mode

<Steps>
  ### 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](#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.

  ```log
  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
  ```

  ### Start Docker

  ```sh
  docker compose up -d
  ```

  ### Check Logs

  ```sh
  docker logs -f lobehub
  ```

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

  ```log
  [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`.
</Steps>

### Domain Mode

<Steps>
  ### 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:

  | Domain              | Proxy Port | Required |
  | ------------------- | ---------- | -------- |
  | `lobe.example.com`  | `3210`     | Yes      |
  | `s3.example.com`    | `9000`     | Yes      |
  | `s3-ui.example.com` | `9001`     |          |

  ### 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`
  - 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](#custom-deployment) section for key modifications.

  <Callout type="tip">
    **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)
    - Domain Mode: You can customize ports (via reverse proxy configuration)
  </Callout>

  <Callout type="warning">
    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.
  </Callout>

  ### Check Configuration Generation Report

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

  ```log
  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
  ```

  ### Start Docker

  ```sh
  docker compose up -d
  ```

  ### Check Logs

  ```sh
  docker logs -f lobehub
  ```

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

  ```log
  [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`.
</Steps>

## 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](https://raw.githubusercontent.com/lobehub/lobe-chat/HEAD/docker-compose/deploy/docker-compose.yml) and the [environment variable configuration file](https://raw.githubusercontent.com/lobehub/lobe-chat/HEAD/docker-compose/deploy/.env.example).

```sh
curl -O https://raw.githubusercontent.com/lobehub/lobe-chat/HEAD/docker-compose/deploy/docker-compose.yml
curl -O https://raw.githubusercontent.com/lobehub/lobe-chat/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](https://github.com/rustfs/rustfs) as the local S3 object storage service by default. To configure SSO authentication services, please refer to the [Authentication Services](/docs/self-hosting/auth) documentation.

<Callout type="warning">
  If your network topology is complex, please make sure these services can communicate properly
  within your network environment.
</Callout>

### 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:

<Callout type="tip">
  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.
</Callout>

```env
S3_ENDPOINT=https://s3.example.com
```

2. PostgreSQL

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

```yaml
services:
  lobe:
    environment:
      - 'DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgresql:5432/${LOBE_DB_NAME}'
```

## FAQ

#### Database Migration Issues

You can check the logs using the following command:

```sh
docker logs -f lobehub
```

<Callout type="tip">
  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.
</Callout>

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

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

#### Using `INTERNAL_APP_URL` for Internal Server Communication

<Callout type="info">
  If you're deploying LobeHub behind a CDN (like Cloudflare) or reverse proxy, you may want to configure internal server-to-server communication to bypass the CDN/proxy layer for better performance.
</Callout>

You can configure the `INTERNAL_APP_URL` environment variable:

```yaml
environment:
  - 'APP_URL=https://lobe.example.com'  # Public URL for browser access
  - 'INTERNAL_APP_URL=http://localhost:3210'  # Internal URL for server-to-server calls
```

**How it works:**

- `APP_URL`: Used for browser/client access, OAuth callbacks, webhooks, etc. (goes through CDN/proxy)
- `INTERNAL_APP_URL`: Used for internal server-to-server communication (bypasses CDN/proxy)

If `INTERNAL_APP_URL` is not set, it defaults to `APP_URL`.

**Configuration options:**

- `http://localhost:3210` - If using Docker with host network mode
- `http://lobe:3210` - If using Docker network with service name
- `http://127.0.0.1:3210` - Alternative localhost address

<Callout type="tip">
  For Docker Compose deployments, we recommend using `http://lobe:3210` as the `INTERNAL_APP_URL` (using service name for container-to-container communication).
</Callout>

## Reverse Proxy Configuration

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

**Nginx:**

```nginx
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):

```caddyfile
lobehub.example.com {
    reverse_proxy localhost:3210
}
```

**Traefik** — add labels to the `lobe` service in `docker-compose.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
# View logs (all services)
docker compose logs -f

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

# Restart all services
docker compose restart

# Restart a specific service
docker compose restart lobehub

# Stop all services
docker compose stop

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

## Backup and Restore

**Database backup:**

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

Restore from backup:

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

**File storage (RustFS) backup:**

```sh
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
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
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
docker compose exec postgresql pg_isready -U postgres
```

If unhealthy, check its logs: `docker compose logs postgresql`

**File upload fails**

Check RustFS service:

```sh
docker compose logs rustfs
docker compose logs 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
docker system prune -a --volumes
```

## Configuring Authentication

To configure SSO authentication services (such as Casdoor, Logto, etc.), please refer to the [Authentication Services](/docs/self-hosting/auth) documentation.

[docker-pulls-link]: https://hub.docker.com/r/lobehub/lobehub
[docker-pulls-shield]: https://img.shields.io/docker/pulls/lobehub/lobehub?color=45cc11&labelColor=black&style=flat-square
[docker-release-link]: https://hub.docker.com/r/lobehub/lobehub
[docker-release-shield]: https://img.shields.io/docker/v/lobehub/lobehub?color=369eff&label=docker&labelColor=black&logo=docker&logoColor=white&style=flat-square&sort=semver
[docker-size-link]: https://hub.docker.com/r/lobehub/lobehub
[docker-size-shield]: https://img.shields.io/docker/image-size/lobehub/lobehub?color=369eff&labelColor=black&style=flat-square&sort=semver