Installation guide

Deployment modes

Mode	Best for	Timeline
Docker Compose (single host)	POC / demo / small teams	under 30 minutes
Docker Compose (multi host)	Mid-size orgs	1–3 days
Kubernetes (Helm)	Large estates with a container platform	2–5 days
Offline bundle	No public internet / domestic stack	site-specific

Prerequisites

Hardware (minimum / recommended)

Tier	Minimum	Recommended
CPU	8 cores	16 cores
RAM	32 GB	64 GB
Disk	200 GB SSD	≥1 TB NVMe SSD
GPU (optional for local LLMs)	—	A10 / A100 / H800 / Ascend

Operating system

Ubuntu 22.04 LTS (preferred) / 20.04
CentOS Stream 9 / RHEL 9
Unity / Kylin variants for domestic deployments

Software dependencies

Component	Version	Role
Docker	24.0+	Runtime
Docker Compose	v2.20+	Single-cluster orchestration
Git	2.30+	Source retrieval (private builds)
Nginx	1.22+	Reverse proxy (optional)

Option A — Docker Compose (single host)

1. Fetch the bundle

git clone https://git.your-org.com/combo-agent.git
cd combo-agent

2. Configure environment

cp .env.example .env
vim .env   # adjust critical variables

Key variables:

# Public URL
EXTERNAL_URL=https://combo.example.com
 
# LLM credentials (at least one)
OPENAI_API_KEY=sk-...
# or domestic providers
DEEPSEEK_API_KEY=...
QWEN_API_KEY=...
 
# Database (bundled by default, override if external)
DB_PASSWORD=change-me
 
# MinIO
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=change-me-strongly

3. Launch

docker compose up -d

Wait 3–5 minutes, then browse http://<server-ip>:9380.

4. First-run setup

Open http://<server-ip>:9380
Create the admin user
Configure LLM channels
Send a smoke message

Option B — Docker Compose (multi host)

Split data plane (DB + ES + MinIO + Redis) from application plane (API + agent runtime + web).

Typical layout:

Rendering diagram…

Reference compose files ship under deploy/multi-node/ in the delivery package.

Option C — Kubernetes (Helm)

helm repo add combo-agent https://charts.your-org.com/combo-agent
helm repo update
 
helm install combo combo-agent/combo-agent \
  --namespace combo --create-namespace \
  --values values.yaml

Important values.yaml knobs:

image:
  repository: your-registry.com/combo-agent
  tag: "v1.0.0"
 
ingress:
  enabled: true
  host: combo.example.com
 
llm:
  provider: deepseek
  apiKey: "ref:secret/llm-api-key"
 
storage:
  minio:
    persistence:
      size: 500Gi

Option D — Offline / air-gap

1. Stage images on an internet-connected builder

docker pull your-registry.com/combo-agent:v1.0.0
# ...other dependency images
 
docker save -o combo-agent-v1.0.0.tar $(docker images --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>')

Ship the tarball and the deployment bundle (compose + templates).

2. Import on the isolated site

Physical media / data-diode transfer as required.

3. Load and start

docker load -i combo-agent-v1.0.0.tar
cd combo-agent
cp .env.offline .env
docker compose up -d

Post-install checks

Health

curl http://<server>:9380/v1/health
# expect {"status": "ok", ...}

Smoke test

Create a chat in the web UI
Expect an agent reply within seconds
Logs should be free of ERROR lines

Functional smoke

Area	Action
File upload	Upload a PDF; confirm parsing
KB search	Ask a question grounded in a document
Tooling / skills	Trigger a skill (e.g., “write hello world in Python”)
Channels	Send via Feishu / WeCom and confirm routing into a session

Upgrade

cd combo-agent
git pull
./scripts/upgrade.sh v1.1.0

The script:

Backs up the database
Runs schema migrations
Pulls fresh images
Rolling restarts services
Runs health checks

Rollback

./scripts/rollback.sh v1.0.0

Rollback window: ~24 h after upgrade for one-click revert; beyond that, follow DB restore playbooks if schemas diverged.

FAQ

Q: Containers crash-loop? A: Verify .env secrets (escape special chars), disk space, and docker compose logs <service>.

Q: Web loads but agents never answer? A: LLM credential or network path to the LLM endpoint (common in locked-down DCs).

Q: No docker hub access? A: Use Option D or mirror images into a private registry.

Installation guide

On this page