# Deploy Cloud Storage Engine locally

This document only covers the minimal local deployment path that has been
validated end to end:

1. build TiDB, PD, and Cloud Storage Engine
2. start MinIO as the object storage backend
3. prepare `tidb.toml`, `tikv.toml`, and `pd.toml`
4. start a local cluster with `tiup playground`
5. verify TiDB SQL and MinIO object writes

This document currently focuses on the core local deployment path.
`tikv-worker` and TiFlash / columnar will be added later after their local
deployment steps are organized and written down.

## 1. Build the binaries

The examples below assume these three repositories are sibling directories:

```text
../tidb
../pd
../cloud-storage-engine
```

If your layout is different, adjust the binary paths in the later `tiup
playground` command.

### TiDB

Build TiDB with NextGen enabled:

```bash
cd ../tidb
NEXT_GEN=1 make server
```

Expected binary:

```bash
../tidb/bin/tidb-server
```

### Cloud Storage Engine

Build the Cloud Storage Engine server from this repository:

```bash
# switch to the root directory of the cloud-storage-engine repo
cd ../cloud-storage-engine
make build
```

Expected binary:

```bash
target/debug/tikv-server
```

Notes:

- make sure `protoc` is installed and is not older than protobuf 3.x
- if you use `make release`, the binary is typically `target/release/tikv-server`

### PD

Build PD with NextGen enabled:

```bash
cd ../pd
DASHBOARD=0 NEXT_GEN=1 make pd-server
```

Expected binary:

```bash
../pd/bin/pd-server
```

Notes:

- `NEXT_GEN=1 make` may try to download TiDB Dashboard assets from GitHub
- `DASHBOARD=0` avoids that extra dependency and is sufficient for local deployment

## 2. Start MinIO

```bash
mkdir -p ~/serverless_s3/cse-test
minio server ~/serverless_s3
```

Use these local values in the examples below:

- endpoint: `http://127.0.0.1:9000`
- access key: `minioadmin`
- secret key: `minioadmin`
- bucket: `cse-test`

## 3. Prepare the config files

### `tikv.toml`

```toml
[storage]
reserve-space = 0
api-version = 2
enable-ttl = true

[dfs]
prefix = "tikv"
s3-endpoint = "http://127.0.0.1:9000"
s3-key-id = "minioadmin"
s3-secret-key = "minioadmin"
s3-bucket = "cse-test"
s3-region = "local"
```

### `pd.toml`

```toml
[keyspace]
pre-alloc = ["keyspace1", "keyspace2"]
```

### `tidb.toml`

For a simple local setup, start the first TiDB on `SYSTEM` keyspace:

```toml
keyspace-name = "SYSTEM"

[instance]
tidb_service_scope = "dxf_service"

[ratelimit]
full-speed = 1048576000
full-speed-capacity = 1048576000
low-speed-watermark = 1048576000000
block-write-watermark = 1048576000000

[security]
enable-sem = false
```

Notes:

- `tikv-worker-url` is intentionally omitted from the minimal setup
- add worker-related config only after the core TiDB + PD + CSE path is stable

## 4. Start a local cluster with TiUP playground

Use the validated minimal command below:

```bash
tiup playground v8.5.4 --tag serverless \
  --db.config ./tidb.toml --db.binpath ../tidb/bin/tidb-server \
  --kv.config ./tikv.toml --kv.binpath ./target/debug/tikv-server \
  --pd.config ./pd.toml --pd.binpath ../pd/bin/pd-server \
  --tiflash 0 \
  --without-monitor
```

Notes:

- `--tiflash 0` keeps TiFlash out of the minimal deployment path
- `--without-monitor` keeps the first run smaller and faster
- if you hit a transient `PD server timeout`, stop the playground and start it again

## 5. Verify the deployment

### Check that TiDB is up

```bash
curl http://127.0.0.1:10080/status
```

### Check basic SQL

```bash
mysql -h 127.0.0.1 -P 4000 -u root -e "select version(); show databases;"
```

### Check read/write

```bash
mysql -h 127.0.0.1 -P 4000 -u root -e "\
create database if not exists cse_deploy_test; \
use cse_deploy_test; \
create table if not exists t(a int primary key, b varchar(32)); \
insert into t values (1,'x') on duplicate key update b=values(b); \
select * from t;"
```

### Check that Cloud Storage Engine wrote objects to MinIO

```bash
find ~/serverless_s3/cse-test -type f | sed -n '1,20p'
```

You should see SST objects created under the configured DFS prefix.

## 6. TODOs

### `tikv-worker`

TODO:

- document a verified minimal `tikv-worker.toml`
- document the exact startup command and ports
- verify the end-to-end remote coprocessor flow before promoting it from TODO

### TiFlash / columnar

TODO:

- document a verified TiFlash / columnar deployment flow
- pin a version combination that is known to be compatible with the TiDB / PD / CSE binaries used here
- keep this out of the minimal deployment path until it is validated

## 7. Recommended first run

If this is your first local deployment, keep it simple:

1. start MinIO
2. build TiDB, PD, and Cloud Storage Engine
3. start a playground without `tikv-worker` and without TiFlash
4. confirm TiDB SQL works
5. confirm Cloud Storage Engine writes DFS objects into MinIO
6. add extra components only after the minimal cluster works