---
name: deploy-tidbx
description: |
  Deploy a single-machine TiDBX cluster to a fresh remote machine over SSH using local tikv/pd/tidb tar.gz binaries, including dependency bootstrap (tiup/latest go/mysql client/minio), MinIO startup, cse.yaml upload, tiup cluster deploy, binary patch, and cluster start with per-step success/failure reporting. Use when user asks for one-command setup on one new machine. For canonical AWS multi-node TiDB X clusters, use deploy-tidbx-aws-multinode instead.
---

# Deploy TiDBX on One Machine

Use the bundled script for deterministic single-host execution and per-step reporting.

For AWS multi-node Premium/TiDB X deployments, use `deploy-tidbx-aws-multinode`. Do not extend this single-machine script with multi-node topology, EC2 provisioning, cse-worker orchestration, or SYSTEM keyspace bootstrap logic.

## Required inputs

- SSH target (`REMOTE_TARGET`, optional `SSH_PORT`)
- Local binary tar.gz paths:
  - `LOCAL_TIKV_TAR`
  - `LOCAL_PD_TAR`
  - `LOCAL_TIDB_TAR`

## Run

```bash
REMOTE_TARGET=admin@<host> \
SSH_PORT=22 \
LOCAL_TIKV_TAR=/path/to/tikv-server.tar.gz \
LOCAL_PD_TAR=/path/to/pd-server.tar.gz \
LOCAL_TIDB_TAR=/path/to/tidb-server.tar.gz \
CLUSTER_NAME=cse \
CLUSTER_VERSION=v8.5.0 \
./scripts/deploy_tidbx_new_machine.sh
```

## What the script does

1. Print execution plan before running.
2. Install remote dependencies: tiup, latest golang, mysql client, minio; export PATH in shell rc.
3. Ensure MinIO runs in background on `/home/admin/serverless_s3`, initialize `~/serverless_s3/cse-test`, and verify port `9000`.
4. Generate local SSH key if missing, configure remote `authorized_keys`, and ensure remote loopback SSH (`admin@127.0.0.1`) works for TiUP.
5. Upload the required `references/cse.yaml` template to remote `~/cse.yaml` (do not generate temp YAML).
6. Deploy cluster if absent; if cluster name already exists, skip deploy and continue to next steps.
7. Upload local tarballs to remote `~/bin` as `tidb.tar.gz`, `pd.tar.gz`, `tikv.tar.gz`; skip local-missing files, and skip upload when remote file already exists (existence check only).
8. Patch binaries for tidb/pd/tikv with `--offline -y --overwrite`; skip roles whose tarball is missing on remote.
9. Re-check MinIO readiness, then start cluster: `tiup cluster start cse`.
10. Print final cluster status summary: `tiup cluster display cse`.

The script exits immediately on first failed step and prints `SUCCESS`/`FAILED` for each step.
A built-in watchdog fails any single step running over 10 minutes (override with `STEP_TIMEOUT_SECONDS`).