# Runbook: profile.compose-e2e

Provision a compose-based e2e sandbox via `ext.compose-ssh` (e2e-framework lineage).

## Prerequisites

**Workstation**

- `uv`, `ssh`, `rsync`
- sand-boxer installed: `make setup`

**Remote host** (CoulombCore or sandboxer01)

- SSH access (`SANDBOXER_HOST` or `--host`)
- Compose runtime: `docker compose` **or** `podman-compose` (CoulombCore uses podman)
- Sufficient disk for images

```bash
export SANDBOXER_HOST=coulombcore          # or 92.205.130.254
export SANDBOXER_COMPOSE_CMD=podman-compose  # CoulombCore; omit on docker hosts
# Omit SANDBOXER_SSH_USER to use ~/.ssh/config (CoulombCore: tegwick + id_ops)
```

### Automated smoke (SAND-WP-0002-T10)

```bash
./scripts/smoke-compose-e2e.sh
```

Uses sand-boxer `e2e/docker-compose.smoke.yml` (nginx:alpine) — create → ps → destroy → verify cleanup.

## Create

Target repo must contain `e2e/e2e.yml` (for compose file path) or a
`docker-compose*.yml` at repo root.

```bash
sandboxer create \
  --profile profile.compose-e2e \
  --input repo=/path/to/repo \
  --actor adm \
  --project sand-boxer
```

Confirm `state: ready` and note `reachability.ssh`, `reachability.remote_dir`,
and `reachability.compose_project`.

## Manual readiness check

sand-boxer confirms compose services are running (not HTTP health — that is
wise-validator's job):

```bash
ssh $SANDBOXER_SSH_USER@$SANDBOXER_HOST \
  'docker compose -p <compose_project> -f <remote_dir>/<compose_file> ps'
```

## Destroy

```bash
sandboxer destroy <sandbox_id>
```

Verify cleanup:

```bash
ssh $SANDBOXER_SSH_USER@$SANDBOXER_HOST 'docker compose ls'
ssh $SANDBOXER_SSH_USER@$SANDBOXER_HOST 'ls /tmp/sandboxer/'
```

## Compatibility with legacy `make e2e`

Interim callers in `the-custodian` should migrate to sand-boxer for
provision/teardown only. Test execution remains in wise-validator (SAND-WP-0003).

| Legacy | sand-boxer |
|--------|------------|
| `make e2e REPO=foo` (full pipeline) | `sandboxer create` + wise-validator run |
| rsync + compose up | `ext.compose-ssh` provision |
| compose down + dir removal | `sandboxer destroy` |

## Troubleshooting

**Provision fails — no compose file**

Ensure repo has `e2e/e2e.yml` with `compose_file` or a root `docker-compose*.yml`.

**Leftover compose projects**

```bash
ssh $SANDBOXER_HOST 'docker compose -p sbx-e2e-<id> down -v; rm -rf /tmp/sandboxer/<id>'
```

**Skip State Hub events (local debug)**

```bash
export SANDBOXER_NO_STATE_HUB=1
```