Docker Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
OneBots provides a containerized deployment model based on Node.js 24 and Alpine Linux. The Docker image encapsulates the management service and the multi-platform gateway, allowing for a self-hosted IM bot gateway environment that persists configuration through volume mapping.
Sources: AGENTS.md:14-25, README.en.md:74-78, tests/unit/docker-build-context.spec.ts:83-90
Architecture and Components
The Docker deployment utilizes a multi-stage build process to ensure a lightweight production image. It employs su-exec to safely transition from the root user to a non-privileged node user during the entrypoint execution.
Deployment Flow
The following diagram illustrates the lifecycle from container start to service readiness.
This flowchart shows the permission handling logic in the entrypoint and the transition to the application server.
Sources: tests/unit/docker-build-context.spec.ts:83-110, deploy/1panel/onebots/README.md:9-15
Key Image Components
| Component | Description | Reference Path |
|---|---|---|
| Base Image | Node.js 24 Alpine | Dockerfile |
| Runtime User | node (UID 1000) | docker-entrypoint.sh |
| Healthcheck | Internal JS probe for /ready | scripts/docker-healthcheck.mjs |
| Data Directory | Persistent storage mount point | /data |
Sources: AGENTS.md:214-225, tests/unit/docker-build-context.spec.ts:71-78
Configuration and Persistence
Persistence is mandatory for OneBots Docker deployments. If you do not mount a host directory to the /data path, all configurations, device sessions, and runtime generations are lost upon container restart.
Data Volume Structure
The /data directory stores the following critical assets:
config.yaml: The primary configuration file for platforms and protocols.- Device sessions: Authentication tokens and session states for IM platforms.
- Databases: SQLite instances for message logging and internal state.
- Verified runtime generations: Immutable snapshots of the gateway environment.
Sources: README.en.md:74-78, deploy/1panel/onebots/README.md:9-12, AGENTS.md:217-219
Bootstrapping the Manager
For new installations with empty data volumes, the manager starts without pre-configured accounts. You must obtain a one-time pairing code to access the Web UI.
docker exec --user 1000:1000 onebots \
node /app/packages/onebots/lib/bin.js auth bootstrap --data-dir /data
Sources: README.en.md:86-90, deploy/1panel/onebots/README.md:16-18
Healthcheck Mechanism
OneBots includes a dedicated healthcheck script that verifies the readiness of the management service. The probe ignores legacy routing and targets the management port (default 6727).
Healthcheck Sequence
The healthcheck script validates the application identity, checks the version against expected constants, and ensures the instance_id is present.
Sources: tests/unit/docker-healthcheck.spec.ts:24-35, packages/core/src/app-observability.ts:241-255
Readiness Requirements
The /ready endpoint returns a 503 Service Unavailable status if any of the following conditions are met:
- The application has not finished starting.
- A runtime operation (e.g., configuration reload or account setup) is in progress.
- The disk configuration has drifted or is unavailable.
- Required platform accounts are offline.
Sources: packages/core/src/app-observability.ts:127-145, tests/unit/docker-healthcheck.spec.ts:63-75
Specialized Environments
Hugging Face (HF) Spaces
The Dockerfile.hf and docker-entrypoint-hf.sh are optimized for Hugging Face Spaces. This environment uses a specific restoration script (hf-data-archive-restore.mjs) to download and extract data backups from repository files.
- RESTORE_DATA: Downloads
data_backup.tar.gzandconfig_backup.yamlusinghf-repository-download.mjs. - Permissions: The entrypoint unsets
HF_TOKENbefore execution to prevent credential leakage.
Sources: tests/unit/docker-build-context.spec.ts:130-142, tests/unit/docker-build-context.spec.ts:167-175
1Panel Integration
Deployment via 1Panel involves using the 1panel-network and mapping port 6727. The docker-compose.yml should reference ghcr.io/lc-cn/onebots:master or a specific version tag.
Sources: deploy/1panel/README.md:20-25, deploy/1panel/onebots/README.md:27-29
Summary
Docker deployment for OneBots centers on the management of the /data volume and the execution of the management service on port 6727. The system ensures security through non-root execution and operational stability via a robust healthcheck probe that monitors the internal readiness state of all platform adapters and protocols.