# TiPOC Deployment POC SOP

SOP means Standard Operating Procedure. This document set is a runbook: fill
the inputs, prepare the environment, run the commands, collect the receipts,
and report the result.

## First time here?

If this is your first time using TiPOC, don't jump straight to the commands below.
Answer these four questions first to understand what you're testing, how large your
environment is, and which deployment type to pick. Then fill out
[`poc-intake-form.md`](poc-intake-form.md).

### 1. Which deployment type?

| If you want to... | Pick | Environment | Estimated requirements |
| --- | --- | --- | --- |
| Try quickly on your local machine | **tiup** | Local single node | Go + tiup playground + tipoc binary |
| Use a TiDB Cloud shared-TiKV cluster | **essential** | TiDB Cloud | Cluster + EC2 nodes + S3 + tipoc |
| Use a TiDB Cloud dedicated-TiKV cluster | **premium** | TiDB Cloud | Cluster + EC2 nodes + S3 + tipoc |

The node counts above are rough estimates. Actual numbers depend on your target
QPS (for pressure nodes) and data size (for generation nodes). See
[node-and-time-planning.md](node-and-time-planning.md) for the full sizing
tables.

### 2. What data size?

| Size | Meaning | Default for |
| --- | --- | --- |
| 10G | Small, quick validation | tiup |
| 50G | Medium | tiup |
| 100G | Medium-large | essential |
| 1T+ | Large | essential / premium |

### 3. Which workload?

| Workload | What it tests | Status |
| --- | --- | --- |
| tpce | Standard TPC-E with fixed 8:2 read/write ratio (33 tables) | `init / prepare / run` ready |
| exchange | Exchange matching with configurable read/write ratio | `init / prepare / run` ready |
| tpce-read-only | Securities customer portal, trader workbench, and broker reporting reads, isolated from the canonical foreground mix | `init / prepare / run` ready; see [`../tpce-read-only-sop.md`](../tpce-read-only-sop.md) and the [reference E2E report](../tpce-read-only-e2e-report.md) |

### 4. Is your environment ready?

- **tiup**: ensure Go is available, `tiup playground` can start, and tipoc is compiled.
- **essential / premium**: you also need a reachable TiDB Cloud cluster, EC2 nodes you
  can SSH into, and a read-write S3 bucket. See [`environment-setup.md`](environment-setup.md).

---

The public TiPOC flow is always:

```text
init -> prepare -> run -> cleanup
```

Report writing happens after `cleanup` as run closeout. It is required for the
final POC handoff, but it is not a fifth public product stage. A same-attempt
rerun stays inside `run`; it must be reported as continuation evidence unless a
clean target was restored or reprepared first.

Use the files in this order:

| Step | File | Use it for |
| ---: | --- | --- |
| 1 | `poc-intake-form.md` | Freeze the POC inputs before any command runs. |
| 2 | `node-and-time-planning.md` | Pick generation nodes and pressure nodes. |
| 3 | `environment-setup.md` | Create EC2, S3, SQL access, and monitoring bindings. |
| 4 | `deployment-poc-sop.md` | Run `init`, `prepare`, `run`, optional same-stage rerun tries, `cleanup`, and the final report handoff. |
| 5 | `../issue-65-continuation-recovery.md` | Recover the next pressure round from a completed or interrupted same-attempt run without re-importing the prepared target. |
| 6 | `../tpce-read-only-sop.md` | Configure, continue, and verify the isolated securities read-service lane. |

For a multi-round pressure simulation, fill the experiment matrix in
`poc-intake-form.md`, use `node-and-time-planning.md` to decide the first
concurrency and duration values, then follow the multi-round section in
`deployment-poc-sop.md`. The same matrix is used by both manual and AI-assisted
execution.

Two execution modes are supported:

| Mode | Rule |
| --- | --- |
| Manual | A human fills the form and runs the commands. |
| AI-assisted | AI prepares non-secret commands and checks evidence; a human owns secrets, approvals, and external actions. |

**For AI agents and human operators alike**: follow the documents in order. Do
not skip `poc-intake-form.md` to jump to render, do not create EC2 nodes before
reading `node-and-time-planning.md`, and do not run `init` without reviewing
`spec.yaml` first. Every step that this SOP documents exists because skipping it
has caused a real failure.

For multi-node Cloud source generation, do not assume the coordinator starts
prepare workers. Today only the `run` pressure path has coordinator-owned SSH
runner launch support. Prepare generation still requires the same binary and
manifest on every generation node, worker-to-coordinator TCP `18080`, and one
explicit prepare process per generation node.

Do not paste passwords, private keys, access keys, SQL DSNs, Clinic tokens, or
Grafana cookies into these documents. Use references such as `env:TIDB_DSN`,
`env:AWS_PROFILE`, instance roles, secret-file paths, or secret-manager ARNs.

Record SOP problems in `sop-doc-issues.md` when a step is unclear, when an
operator input is missing, or when a desired runtime adjustment is not exposed
by the current command scripts.

---

**Next**: Go to [poc-intake-form.md](poc-intake-form.md) and fill out the form.