Skip to main content

Deployment Guide (Docker Compose)

This guide helps you deploy BK-Lite Community Edition on a single node with Docker Compose using the one-click installation script, and optionally enable APM, RUM, Workflow, OpsPilot, and local model inference services.

1. Requirements​

  • Docker >= 20.10.23
  • Docker Compose >= v2.27.0
  • AI Edition: The local OCR, Embedding, and Rerank models served by vLLM require an Nvidia GPU with > 8 GB of available VRAM.

2. Online Installation (Quick Start)​

2.1 Standard Edition (Optional Modules Disabled by Default)​

A fresh installation does not enable APM, RUM, Workflow, OpsPilot, MLOps, or MLflow, and does not deploy vLLM. APM, RUM, and Workflow can be enabled independently of local models:

curl -fLsS https://bklite.cn/install.run | bash -s --

2.2 Enable OpsPilot (Connect to Existing Model Services)​

To use OpsPilot, add --opspilot to the installation command:

curl -fLsS https://bklite.cn/install.run | bash -s -- --opspilot

In the Community Edition installation script, --opspilot is a grouped switch that enables OpsPilot, MLOps, and MLflow together. This command does not deploy vLLM, so no GPU is required for local model inference. After installation, configure your existing private or public cloud model services in OpsPilot. Features such as knowledge bases also require appropriate Embedding, Rerank, or other models as needed.

2.3 AI Edition (OpsPilot with Local Model Services)​

To deploy OCR, Embedding, and Rerank models locally, add both --opspilot --vllm. The models bundled with vLLM do not include an LLM; you still need to configure an LLM service separately:

curl -fLsS https://bklite.cn/install.run | bash -s -- --opspilot --vllm

This option requires the Nvidia GPU and VRAM specified above. --vllm only enables local model inference services; it does not automatically enable OpsPilot.

2.4 Enable OpsPilot on an Existing Community Installation​

Run the following from your existing deployment directory (the default is /opt/bk-lite):

cd /opt/bk-lite
bash bootstrap.sh --opspilot

This command also enables OpsPilot, MLOps, and MLflow, and redeploys the related services. For offline environments, first prepare an offline package containing the images required by --opspilot, as described below.

Rerunning the installer reuses saved configuration. Existing component states are preserved when no component switches are passed. Do not add --clean to enable additional components: it deletes existing data.

2.5 Enable RUM​

Add --rum on a fresh installation:

curl -fLsS https://bklite.cn/install.run | bash -s -- --rum

RUM reuses platform Redis, NATS, and MinIO, and adds Gateway, Controller, Maintainer, initialization containers, and separate VictoriaLogs/VictoriaTraces stores.

For an existing installation, back up configuration and data, ensure deployment files and Server/Web images support RUM, then run from the actual deployment directory:

cd /opt/bk-lite
bash bootstrap.sh --rum

This reapplies the complete stack; schedule a maintenance window. Dedicated credentials, HMAC, replay signing keys, and RUM_REPLAY_INDEX_EPOCH are generated on first use and preserved. Restore original values if an existing RUM installation has lost them. If bootstrap detects a legacy data/rum/queue, stop writes, back it up, and migrate the queue before retrying; do not delete it to bypass the check.

Use bash bootstrap.sh --no-rum to disable RUM while retaining persistent data and keys.

2.6 Enable Workflow​

Workflow requires a Conductor engine. Add --workflow on a fresh installation to deploy the managed single-node engine without manually setting an endpoint:

curl -fLsS https://bklite.cn/install.run | bash -s -- --workflow

The script sets CONDUCTOR_BASE_URL=http://conductor:8080/api and selects Conductor 3.32.1 and the persistent compose_conductor volume mounted at /data. No manual Compose overlay is needed. The engine is internal-only and publishes no host port.

For an existing deployment, back up first, then run from the actual deployment directory:

cd /opt/bk-lite
bash bootstrap.sh --workflow

--workflow preserves a configured endpoint and selects the managed engine when the endpoint is missing or empty. The script adds workflow to Server's INSTALL_APPS and persists the endpoint. Reruns without a flag preserve the saved state. This reapplies the complete stack; schedule a maintenance window.

Use bash bootstrap.sh --no-workflow to disable: the script clears and saves the endpoint, removes workflow from INSTALL_APPS, and stops the managed engine container while retaining its volume and application history. It does not operate on external engines. --workflow conflicts with --no-workflow. Re-enabling the managed engine reuses its volume; switching between managed and external engines does not migrate data. The Server image must include Workflow and its background processes.

Workflow itself does not require OpsPilot. Agent, intent classification, and memory nodes require the corresponding OpsPilot capabilities. During installation, --workflow enables the module. package --workflow only includes the managed engine image; it does not enable the module on the target server.

2.7 Combine Components and Verify​

For example, enable RUM, Workflow, and OpsPilot on a fresh installation without local models:

curl -fLsS https://bklite.cn/install.run | bash -s -- --rum --workflow --opspilot

Run docker compose ps -a and inspect service logs from the actual deployment directory:

  • RUM: rum-init and rum-minio-init must exit successfully; other RUM services should be running. Follow the RUM quick start to verify real browser collection, queries, and replay.
  • Workflow: Confirm the managed conductor is healthy, inspect Server logs and the Workflow worker, trigger scheduler, and artifact cleanup processes, then publish and run a harmless workflow using the Workflow quick start.

2.8 Enable APM (Application Performance Monitoring)​

Platform-side APM includes the APM application, VictoriaTraces storage, and the apm-system-collector central collector, reusing platform NATS. APM is independent of OpsPilot, RUM, and Workflow, requires no GPU, and is not automatically enabled by --opspilot or --rum.

Online Installation and Existing Deployments​

Add --apm for a fresh installation:

curl -fLsS https://bklite.cn/install.run | bash -s -- --apm

For an existing deployment, back up first, ensure deployment files and Server/Web images support APM, then run from the actual deployment directory:

cd /opt/bk-lite
bash bootstrap.sh --apm

The script adds apm to Server's INSTALL_APPS, saves APM_ENABLED=true, generates collector configuration, and initializes the APM_TRACES stream and BKLITE_APM_SYSTEM consumer. No manual application-list changes are required. This reapplies the complete stack: schedule a maintenance window and do not add the data-deleting --clean option.

Rerunning without APM switches preserves saved state. Legacy single-node Compose configurations missing the APM setting retain their historical enabled state rather than being disabled by fresh-install defaults. To disable:

cd /opt/bk-lite
bash bootstrap.sh --no-apm

--apm conflicts with --no-apm. Disabling removes dedicated APM containers while retaining database records, trace volumes, agent artifacts, and existing NATS data. Shared NATS, Fusion-Collector, and RUM remain available. APM collection and queries are unavailable while disabled; verify the entire data path after re-enabling.

Offline Installation and Updates​

The base offline bundle excludes APM Collector and VictoriaTraces images. Create an APM bundle on an internet-connected machine:

curl -fLsS https://bklite.cn/install.run | bash -s -- package --apm

Distribute and extract it following section 3, set OFFLINE=true on the target, then run bash bootstrap.sh --apm. Combine selections as needed, for example package --apm --rum --workflow. Packaging does not enable components on the target.

An offline update inheriting an enabled APM setting still requires APM images even if --apm is omitted. Supply the images, or explicitly disable with --no-apm while retaining data. A RUM bundle containing VictoriaTraces does not imply that the APM Collector image is included.

Match image architecture and other optional components to the target environment. APM and RUM use separate trace stores; disabling APM must not remove RUM storage.

Onboarding and Verification​

Platform deployment must be followed by regional collector configuration and application agents. The data path is application agent → regional collector → NATS JetStream → central collector → VictoriaTraces.

  • On a single node, inspect docker compose ps -a and docker compose logs --tail=100 apm-system-collector victoria-traces in the actual deployment directory.
  • Follow the APM quick start to create an application, configure the region, install an agent, and generate a real request. Confirm it appears in the service catalog, topology, and traces.
  • Single-node APM storage publishes host port 10428 by default. Restrict access: this is an internal storage port, not the application agent endpoint. Use the regional endpoint provided by the product rather than this port or a RUM browser collection URL.

3. Offline Installation​

When the target server cannot access the internet, first create an offline package on an internet-connected machine that meets the version requirements, then transfer it to the target server for installation.

3.1 Create Offline Package (On Internet-Connected Machine)​

Choose one packaging option for your target environment:

  • Standard Edition (without APM, RUM, Workflow, OpsPilot, MLOps, MLflow, or vLLM):
curl -fLsS https://bklite.cn/install.run | bash -s -- package
  • OpsPilot (with MLOps and MLflow, connecting to existing model services):
curl -fLsS https://bklite.cn/install.run | bash -s -- package --opspilot
  • AI Edition (OpsPilot with local OCR, Embedding, and Rerank models; no LLM included):
curl -fLsS https://bklite.cn/install.run | bash -s -- package --opspilot --vllm
  • Add RUM and the managed Workflow engine as needed; these can be combined with --opspilot and --vllm:
curl -fLsS https://bklite.cn/install.run | bash -s -- package --rum --workflow

--rum includes RUM images; --workflow includes the managed Conductor image.

Installation files and images are saved in /opt/bk-lite, and the script automatically creates /opt/bklite-offline.tar.gz. package --opspilot includes the additional MLflow image. You must still pass the corresponding component switches when installing on the target server.

3.2 Package and Distribute (On Internet-Connected Machine)​

Copy /opt/bklite-offline.tar.gz to the target server (offline environment).

3.3 Install on Target Server (On Offline Machine)​

Extract the offline package and enter the deployment directory:

sudo mkdir -p /opt/bk-lite
sudo tar -xzvf bklite-offline.tar.gz -C /opt/bk-lite
cd /opt/bk-lite
export OFFLINE=true

In the same terminal, run one of the following commands matching the components selected when creating the package:

# Standard Edition
bash bootstrap.sh

# Or: APM (bundle must include --apm images)
bash bootstrap.sh --apm

# Or: enable OpsPilot, MLOps, and MLflow, connecting to existing model services
bash bootstrap.sh --opspilot

# Or: AI Edition, also enabling local OCR, Embedding, and Rerank models (requires GPU)
bash bootstrap.sh --opspilot --vllm

# Or: RUM + managed Workflow engine (fresh installation)
bash bootstrap.sh --rum --workflow

For existing offline deployments, first supply the required images. Packaging flags do not enable modules on the target server. See Backup and Restore for data protection requirements.

4. Uninstallation​

To completely uninstall the system:

curl -sSL https://bklite.cn/uninstall.sh | bash -s -

FAQ​

  • Are APM and RUM enabled together? No. Use --apm for APM and --rum for RUM, or pass both. Their stores are independent. Platform-side APM installation still requires regional collectors and application agents; see APM deployment.

  • Can the installation be run multiple times? Yes. Rerunning reuses saved configuration and redeploys related services. Existing component states are preserved when no component switches are passed. --clean deletes existing data and must not be used to enable additional components.

  • Can I install without configuring a MIRROR? Yes, but configuring one is recommended in China's network environment to improve download speed and stability.

  • Can I use OpsPilot without a GPU? Yes. Add --opspilot without --vllm, then configure existing private or public cloud model services in OpsPilot. The required model types depend on the features you use. OpsPilot is disabled by default on a fresh Standard Edition installation.