Docker Deployment

The official image is published to Docker Hub: https://hub.docker.com/r/mlogclub/bbs-go

Option 1: Built-in MySQL

This uses the mlogclub/bbs-go:latest image by default. After startup, open http://localhost:3000 and complete the installation wizard.

The default docker-compose.yml includes MySQL. In this mode, database fields in the installer are locked, and the system automatically uses the MySQL service inside Docker:

Host: mysql
Port: 3306
Database: bbsgo
Username: bbsgo

The default docker-compose.yml starts two services:

mysql: MySQL 8.4, persisted in the Docker volume mysql-data
bbs-go: the application service. A single image runs both the Go API and React Router SSR. The API listens on 8082 inside the container, and the Web SSR service listens on and exposes 3000

docker-compose.yml

Save the following content as docker-compose.yml:

yaml

x-builtin-mysql-env: &builtin-mysql-env
  MYSQL_DATABASE: ${BBSGO_DOCKER_MYSQL_DATABASE:-bbsgo}
  MYSQL_USER: ${BBSGO_DOCKER_MYSQL_USER:-bbsgo}
  MYSQL_PASSWORD: ${BBSGO_DOCKER_MYSQL_PASSWORD:-bbsgo_password}

services:
  mysql:
    image: mysql:8.4
    restart: unless-stopped
    environment:
      <<: *builtin-mysql-env
      MYSQL_ROOT_PASSWORD: ${BBSGO_DOCKER_MYSQL_ROOT_PASSWORD:-bbsgo_root_password}
      TZ: UTC
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    volumes:
      - mysql-data:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -u\"$${MYSQL_USER}\" -p\"$${MYSQL_PASSWORD}\" --silent"]
      interval: 10s
      timeout: 5s
      retries: 10

  bbs-go:
    image: mlogclub/bbs-go:${BBSGO_IMAGE_TAG:-latest}
    restart: unless-stopped
    depends_on:
      mysql:
        condition: service_healthy
    volumes:
      - app-data:/app/data
      - app-logs:/app/logs
      - app-uploads:/app/res/uploads
    ports:
      - "3000:3000"
    environment:
      BBSGO_ENV: prod
      NODE_ENV: production
      PORT: 3000
      BBSGO_SERVER_URL: http://127.0.0.1:8082
      BBSGO_INSTALL_DOCKER_BUILTIN_MYSQL: "true"
      BBSGO_DOCKER_BUILTIN_MYSQL_HOST: mysql
      BBSGO_DOCKER_BUILTIN_MYSQL_PORT: "3306"
      BBSGO_DOCKER_BUILTIN_MYSQL_DATABASE: ${BBSGO_DOCKER_MYSQL_DATABASE:-bbsgo}
      BBSGO_DOCKER_BUILTIN_MYSQL_USERNAME: ${BBSGO_DOCKER_MYSQL_USER:-bbsgo}
      BBSGO_DOCKER_BUILTIN_MYSQL_PASSWORD: ${BBSGO_DOCKER_MYSQL_PASSWORD:-bbsgo_password}
      TZ: UTC

volumes:
  mysql-data:
  app-data:
  app-logs:
  app-uploads:

Parameters

Option	Description
`BBSGO_IMAGE_TAG`	BBS-GO image tag. Defaults to `latest`.
`BBSGO_DOCKER_MYSQL_DATABASE`	Built-in MySQL database name. Defaults to `bbsgo`.
`BBSGO_DOCKER_MYSQL_USER`	Built-in MySQL username. Defaults to `bbsgo`.
`BBSGO_DOCKER_MYSQL_PASSWORD`	Built-in MySQL user password. Defaults to `bbsgo_password`.
`BBSGO_DOCKER_MYSQL_ROOT_PASSWORD`	Built-in MySQL root password. Defaults to `bbsgo_root_password`; change it for production.
`BBSGO_INSTALL_DOCKER_BUILTIN_MYSQL`	Enables Docker built-in MySQL install mode; database fields in the installer are locked.
`BBSGO_DOCKER_BUILTIN_MYSQL_HOST`	MySQL hostname for the app. In compose, this is the service name `mysql`.
`BBSGO_DOCKER_BUILTIN_MYSQL_PORT`	MySQL port for the app. Defaults to `3306`.
`BBSGO_DOCKER_BUILTIN_MYSQL_DATABASE`	Database name used by the app. Keep it aligned with `BBSGO_DOCKER_MYSQL_DATABASE`.
`BBSGO_DOCKER_BUILTIN_MYSQL_USERNAME`	MySQL username used by the app. Keep it aligned with `BBSGO_DOCKER_MYSQL_USER`.
`BBSGO_DOCKER_BUILTIN_MYSQL_PASSWORD`	MySQL password used by the app. Keep it aligned with `BBSGO_DOCKER_MYSQL_PASSWORD`.
`BBSGO_ENV`	Runtime environment. Use `prod` for Docker deployment.
`NODE_ENV`	Web SSR runtime environment. Use `production` for production.
`PORT`	Web SSR listen port. Defaults to `3000`.
`BBSGO_SERVER_URL`	Internal URL used by Web SSR to access the Go API. Defaults to `http://127.0.0.1:8082`.
`TZ`	Container timezone. Defaults to `UTC`; set it to your local timezone if needed.
`ports: "3000:3000"`	Maps host port `3000` to the Web SSR service in the container.
`mysql-data`	Persistent volume for MySQL data.
`app-data`	Persistent volume for app config, SQLite database, search indexes, and runtime data.
`app-logs`	Persistent volume for application logs.
`app-uploads`	Persistent volume for uploaded files and auto-downloaded IP databases.
`healthcheck`	Waits for MySQL to become available before starting the app service.

Start command:

bash

docker compose up -d

By default, do not set BBSGO_IMAGE_TAG; docker compose up -d uses latest. To use another version, specify the image tag:

bash

BBSGO_IMAGE_TAG=<version> docker compose up -d

Option 2: Single Container

bash

docker run -d \
  --name bbs-go \
  --restart unless-stopped \
  -p 3000:3000 \
  -e BBSGO_ENV=prod \
  -e NODE_ENV=production \
  -e PORT=3000 \
  -e BBSGO_SERVER_URL=http://127.0.0.1:8082 \
  -e TZ=UTC \
  -v bbs-go-data:/app/data \
  -v bbs-go-logs:/app/logs \
  -v bbs-go-uploads:/app/res/uploads \
  mlogclub/bbs-go:latest

After startup, open http://localhost:3000. In the installer, enter an external MySQL configuration manually or choose SQLite. This mode does not orchestrate a MySQL service, so no additional compose file is required.

This uses mlogclub/bbs-go:latest by default. To use another version, replace latest with the version tag, for example mlogclub/bbs-go:v4.3.5.

Persistent Data

For both modes, persist these paths:

/app/data: config file, SQLite database, search indexes, and runtime data
/app/logs: service logs
/app/res/uploads: uploaded files and auto-downloaded IP databases

The built-in MySQL mode also persists:

/var/lib/mysql: MySQL data

The image includes a default config file. On first startup, it is copied automatically to /app/data/bbs-go.yaml. /app/bbs-go.yaml in the container working directory points to this persisted config file, so the application still reads bbs-go.yaml from its startup directory as usual. The installer writes back values such as installed and site settings. In single-container mode, it also writes the database settings entered by the user.

Change Default Passwords

Before production deployment, change the built-in MySQL passwords with environment variables:

bash

BBSGO_DOCKER_MYSQL_ROOT_PASSWORD=your_root_password \
BBSGO_DOCKER_MYSQL_PASSWORD=your_password \
docker compose up -d

You may also set:

BBSGO_DOCKER_MYSQL_DATABASE: database name, default bbsgo
BBSGO_DOCKER_MYSQL_USER: database username, default bbsgo
BBSGO_DOCKER_MYSQL_PASSWORD: database password, default bbsgo_password
BBSGO_DOCKER_MYSQL_ROOT_PASSWORD: root password, default bbsgo_root_password

In built-in MySQL mode, the backend builds the database connection from these environment variables automatically. You do not need to edit db.url in /app/data/bbs-go.yaml.

Common Commands

bash

docker compose logs -f bbs-go
docker compose restart bbs-go
docker compose down

To remove database and upload volumes together:

bash

docker compose down -v

Docker Deployment ​

Option 1: Built-in MySQL ​

docker-compose.yml ​

Parameters ​

Option 2: Single Container ​

Persistent Data ​

Change Default Passwords ​

Common Commands ​

Docker Deployment

Option 1: Built-in MySQL

docker-compose.yml

Parameters

Option 2: Single Container

Persistent Data

Change Default Passwords

Common Commands