# Deploy Wizard Testing Guide

This guide gives you a practical sequence for testing the one-command wizard and the underlying manual commands without guessing what is safe to run first.

## Best First Test For A Real App Repo

If you want to test the full product the way an operator is supposed to use it, do this from the root of the app repo:

```bash
deploy-wizard
```

Recommended choices on the first run:

- confirm the detected or scaffolded container files
- confirm the discovered staging env values
- leave HTTP smoke checks enabled unless the app truly cannot answer one
- let the wizard continue through deploy and proxy publication

Success looks like:

- the wizard writes or refreshes `deploy-wizard.yml`
- the image builds and passes the local smoke check
- the app deploys to the staging app host
- remote health verification passes
- the proxy side publishes successfully
- the final staging URL responds

This is the primary smoke test because it exercises the actual intended operator path.

## Safer Step-By-Step Test Order

If you want to de-risk the first real deployment, use this order instead.

### 1. Run the wizard but stop to inspect generated files first

Run:

```bash
deploy-wizard
```

Before you confirm the final deploy step, inspect:

- `.deploy-wizard/generated/staging.compose.template.yml`
- `.deploy-wizard/generated/proxy/`
- `.github/workflows/deploy-staging.yml`
- `DEPLOY.md`

### 2. Test the proxy side by itself if you want isolation

SSH mode:

```bash
deploy-wizard sync-proxy
```

TRM mode:

```bash
deploy-wizard sync-proxy
```

Success looks like:

- SSH mode: proxy file uploads cleanly
- TRM mode: rules are created or updated and `.trm.generated.yaml` files appear under `.deploy-wizard/generated/proxy/`

### 3. Test app deploy mechanics with a known image tag

Use when:

- you already have an image in GHCR
- you want to test the deploy logic without involving GitHub Actions

Command:

```bash
deploy-wizard apply --image-tag <existing-tag>
```

Success looks like:

- compose/env files upload to the app host
- `docker compose pull && up -d` succeeds
- container health verification passes
- backend HTTP verification passes before traffic is published
- proxy publication happens after the app is healthy

This is the best first real deployment test.

### 4. Test the full CI-backed path later

Use when:

- the generated workflow has been committed and pushed
- `gh` is installed and authenticated
- you want to test the complete CI-driven path

Command:

```bash
deploy-wizard apply
```

Success looks like:

- the workflow is found remotely
- `workflow_dispatch` runs successfully
- the wizard waits for the workflow to finish
- the resulting SHA is used as the deploy image tag
- the app deploy succeeds
- proxy publication succeeds

## How To Test `ssh-file` Mode

### Prerequisites

- app host reachable over SSH
- proxy host reachable over SSH
- a writable Traefik dynamic config directory on the proxy host
- an image tag that already exists in GHCR, or a committed/pushed workflow for full apply

### Smoke test

```bash
deploy-wizard
deploy-wizard sync-proxy
deploy-wizard apply --image-tag latest
```

What to verify:

- `.deploy-wizard/generated/proxy/<proxyFileName>` contains the expected Traefik YAML
- the proxy host receives that file
- the app host receives the rendered compose/env files
- the app host starts containers cleanly
- the final public URL check succeeds

## How To Test `trm-api` Mode

### Prerequisites

- app host reachable over SSH
- a working TRM base URL in the profile
- a valid bearer token exported in the configured env var
- each route has exactly one host and no `pathPrefix`

### Smoke test

```bash
deploy-wizard
ls .deploy-wizard/generated/proxy
deploy-wizard sync-proxy
deploy-wizard apply --image-tag latest
```

What to verify:

- `.deploy-wizard/generated/proxy/<route>.trm-rule.json` exists after the wizard writes artifacts
- `.deploy-wizard/trm-state.json` exists after successful TRM publication
- `.deploy-wizard/generated/proxy/<route>.trm.generated.yaml` exists after successful TRM publication
- TRM shows the rule with the expected hostname and backend URL
- the final public URL check succeeds

## Full CI Test Checklist

Before testing workflow-driven apply:

- the repo has `.github/workflows/deploy-staging.yml` committed
- that file has been pushed to the deploy branch
- `gh auth status` succeeds locally
- the repo can push images to GHCR

Then run:

```bash
deploy-wizard apply
```

If this fails immediately with a “commit and push the generated workflow” message, the remote repo does not yet have the workflow file on the target branch.

## Advanced Manual Validation Commands

If you want no remote side effects at all, these are still the safest checks:

```bash
deploy-wizard validate
deploy-wizard render
```

What they prove:

- the manifest loads
- the profile loads
- the compose files exist
- managed service names are correct
- TRM route shapes are valid if you use `trm-api`
- the generated workflow, compose template, and proxy artifacts render cleanly

## Failure Cases To Test On Purpose

These are useful confidence checks.

### TRM validation failure

Set:

- multiple hosts on one route, or
- `pathPrefix` on a route

Then run:

```bash
deploy-wizard validate
```

Expected result:

- validation fails clearly before any API call

### Missing TRM token

Unset the configured token env var and run:

```bash
deploy-wizard sync-proxy
```

Expected result:

- a clear missing-token error

### Missing remote workflow

Generate the workflow locally but do not push it, then run:

```bash
deploy-wizard apply
```

Expected result:

- apply stops and tells you to commit/push the workflow

### Bad container startup

Use a broken image tag or broken env and run:

```bash
deploy-wizard apply --image-tag <bad-tag>
```

Expected result:

- the local build or smoke check may fail before any remote deploy
- or the SSH deploy happens and post-deploy verification fails
- recent container status/logs are surfaced
- proxy publication does not happen

## What To Look At When Something Fails

Check these in order:

1. `deploy-wizard.yml`
2. the selected profile under `~/.config/deploy-wizard/profiles/`
3. `.deploy-wizard/generated/staging.compose.template.yml`
4. `.deploy-wizard/generated/proxy/`
5. `.github/workflows/deploy-staging.yml`
6. `.deploy-wizard/trm-state.json` if using TRM
7. remote `docker compose ps`
8. remote `docker compose logs`

## Short Version

If you only want the practical answer:

1. run `deploy-wizard` in the app repo
2. choose `local` build for the first deploy if CI is not already ready
3. if you want a safer staged test, use `deploy-wizard sync-proxy`
4. then `deploy-wizard apply --image-tag <existing-tag>`
5. after that works, test full `deploy-wizard apply`