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

---
title: Deploying LobeHub Database with Docker
description: >-
  Learn how to deploy the LobeHub server database version using Docker on Linux
  and local machines.
tags:
  - LobeHub
  - Docker
  - Database Deployment
  - Postgres
---

# Deploying Server Database Version Using Docker

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

<Callout type="info">
  This article assumes that you are familiar with the basic principles and processes of deploying
  the LobeHub server database version, so it only includes content related to core environment
  variable configuration. If you are not familiar with the deployment principles of the LobeHub
  server database version, please refer to [Deploying Server
  Database](/docs/self-hosting/server-database) first.
</Callout>

## Deploying on a Linux Server

Here is the process for deploying the LobeHub server database version on a Linux server:

<Steps>
  ### Create a Postgres Database Instance

  Please create a Postgres database instance according to your needs, for example:

  ```sh
  docker network create pg

  docker run --name my-postgres --network pg -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d paradedb/paradedb:latest-pg17
  ```

  The above command will create a PG instance named `my-postgres` on the network `pg`, where `paradedb/paradedb:latest-pg17` is a Postgres 17 image with pgvector and pg\_search plugins installed by default.

  <Callout type="info">
    The ParadeDB image includes pgvector (vector search) and pg\_search (full-text search) plugins, which are important
    components for LobeHub to implement RAG and knowledge base search.
  </Callout>

  <Callout type="warning">
    The above command does not specify a persistent storage location for the pg instance, so it is
    only for testing/demonstration purposes. Please configure persistent storage for production
    environments.
  </Callout>

  ### Create a file named `lobehub.env` to store environment variables:

  Click the buttons below to generate required secrets:

  <GenerateSecret envName="KEY_VAULTS_SECRET" />

  <GenerateSecret envName="AUTH_SECRET" />

  Click the button below to generate `JWKS_KEY` (for signing and verifying JWTs):

  <GenerateJWKSKey />

  ```shell
  # Website domain
  APP_URL=https://your-prod-domain.com

  # DB required environment variables
  KEY_VAULTS_SECRET=jgwsK28dspyVQoIf8/M3IIHl1h6LYYceSYNXeLpy6uk=
  # Postgres database connection string
  # Format: postgres://username:password@host:port/dbname; if your pg instance is a Docker container, use the container name
  DATABASE_URL=postgres://postgres:mysecretpassword@my-postgres:5432/postgres

  # Authentication (Better Auth)
  # Session encryption key (generate with: openssl rand -base64 32)
  AUTH_SECRET=jgwsK28dspyVQoIf8/M3IIHl1h6LYYceSYNXeLpy6uk=
  # JWKS key for signing and verifying JWTs
  JWKS_KEY='{"keys":[...]}'

  # S3 related
  S3_ACCESS_KEY_ID=xxxxxxxxxx
  S3_SECRET_ACCESS_KEY=xxxxxxxxxx
  S3_ENDPOINT=https://xxxxxxxxxx.r2.cloudflarestorage.com
  S3_BUCKET=LobeHub

  ```

  ### Start the lobehub Docker image

  ```sh
  docker run -it -d -p 3210:3210 --network pg --env-file lobehub.env --name lobehub lobehub/lobehub
  ```

  You can use the following command to check the logs:

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

  If you see the following logs in the container, it means it has started successfully:

  ```log
  [Database] Start to migration...
  ✅ database migration pass.
  -------------------------------------
    ▲ Next.js 14.x.x
    - Local:        http://localhost:3210
    - Network:      http://0.0.0.0:3210

   ✓ Starting...
   ✓ Ready in 95ms
  ```
</Steps>

<Callout type="tip">
  In our official Docker image, the database schema migration is automatically executed before
  starting the image. We ensure stability from an empty database to all tables being formally
  available. Therefore, we recommend using an empty table instance for your database to avoid the
  cost of manually maintaining table structure migration.
</Callout>

## Using Locally (Mac / Windows)

The data version of LobeHub also supports direct use on a local Mac/Windows machine.

Here, we assume that you have a pg instance available on port 5432 locally on your Mac/Windows, with the account `postgres` and password `mysecretpassword`, accessible at `localhost:5432`.

The script command you need to execute is:

```shell
$ docker run -it -d --name lobehub -p 3210:3210 \
  -e DATABASE_URL=postgres://postgres:mysecretpassword@host.docker.internal:5432/postgres \
  -e KEY_VAULTS_SECRET=jgwsK28dspyVQoIf8/M3IIHl1h6LYYceSYNXeLpy6uk= \
  -e AUTH_SECRET=jgwsK28dspyVQoIf8/M3IIHl1h6LYYceSYNXeLpy6uk= \
  -e JWKS_KEY='{"keys":[...]}' \
  -e APP_URL=http://localhost:3210 \
  -e S3_ACCESS_KEY_ID=xxxxxxxxxx \
  -e S3_SECRET_ACCESS_KEY=xxxxxxxxxx \
  -e S3_ENDPOINT=https://xxxxxxxxxx.r2.cloudflarestorage.com \
  -e S3_BUCKET=LobeHub \
  lobehub/lobehub
```

<Callout type="tip">
  `Docker` uses a virtual machine solution on `Windows` and `macOS`. If you use `localhost` /
  `127.0.0.1`, it will refer to the container's `localhost`. In this case, try using
  `host.docker.internal` instead of `localhost`.
</Callout>

[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