# Deploy Wizard Getting Started

This guide is for someone using `deploy-wizard` on a real app repo for the first time and expecting it to behave like a real setup-and-deploy wizard.

Core promise:

**Branch-aware staging deploys for Docker Compose homelabs.**

## The Main Idea

Run one command in the root of the app you want to deploy:

```bash
deploy-wizard
```

Or, if you want the bootstrap launcher:

```bash
curl -fsSL https://raw.githubusercontent.com/stephenjoly/deploy-wizard/main/bootstrap.sh | bash
```

The wizard is designed to finish with a real staging deployment, not just write config files and stop.

By default, `deploy-wizard` runs with the built-in `stephen-home-lab` preset. That keeps Stephen's current zero-config flow intact while still using the same manifest, profile, and lifecycle model as the rest of the CLI.

On a successful first run it will:

- write a checked-in `deploy-wizard.yml` manifest
- create or reuse the built-in `stephen-home-lab` profile stored outside the repo
- generate a Compose deployment template
- generate a GitHub Actions workflow that builds and pushes images
- discover staging env keys and confirm staging values one key at a time
- build and smoke-test the exact deployment image locally
- deploy the app on the staging app host
- verify remote health and backend HTTP readiness
- publish traffic through TRM
- verify the final public URL

The generated workflow still exists for advanced or future use, but the default Stephen happy path now uses a local image build so the wizard can validate the exact artifact before touching the server.

## Prerequisites

You need:

- Node 22+
- Docker Compose on the target staging host
- SSH access to `stephen@10.87.111.253` on port `33`
- a GitHub repo with GHCR enabled
- `curl` installed locally and on the target staging host
- a TRM bearer token available the first time you publish routes

## What To Run In A Fresh App Repo

### Option A: bootstrap launcher

From the target app repo root:

```bash
curl -fsSL https://raw.githubusercontent.com/stephenjoly/deploy-wizard/main/bootstrap.sh | bash
```

### Option B: linked local install

If you already built and linked this repo locally:

```bash
deploy-wizard
```

Both launch the same full interactive wizard.

## What Happens During The Wizard

The default flow is:

1. Preflight checks
The wizard inspects the repo, checks for compose files and Dockerfiles, inspects git/GitHub context, and checks whether deployment files already exist.

If the repo is not containerized yet, it can:

- use an existing Dockerfile to generate a starter compose file
- or create starter `Dockerfile`, `compose.yml`, and `.dockerignore` files for common app types

2. State-aware setup
If `deploy-wizard.yml` and the referenced profile already exist, the wizard summarizes the current state and lets you reuse or replace it instead of replaying setup blindly.

3. Project manifest setup
It writes or refreshes `deploy-wizard.yml`, which is the checked-in source of truth for the app repo.

4. Built-in preset setup
It creates or reuses the built-in `stephen-home-lab` profile under:

- `~/.config/deploy-wizard/profiles/<name>.yml`
- or `$XDG_CONFIG_HOME/deploy-wizard/profiles/<name>.yml`

That profile points at the fixed app host, compose root, app-data root, and TRM URL used by the default flow.

5. Runtime env collection
The wizard discovers env keys from `.env.example`, `.env`, `.env.local`, local compose `env_file` references, and compose variable references. It then confirms staging values one key at a time and writes `.deploy-wizard/staging.env.local`.

6. Artifact generation
It generates:

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

7. Optional git commit and push
If the repo is a git repo, the wizard can create a scoped commit for the generated deployment files and then optionally push the current branch to the configured GitHub repo. The push step only sends committed changes.

8. Local image build and smoke validation
The wizard builds and pushes the image locally, then starts that exact image locally with the staging env file and an HTTP smoke check before touching the server.

9. Remote deploy
It SSH-deploys the rendered compose bundle to the app host.

10. Verification
It checks remote container state, surfaces recent logs on failure, and runs an HTTP check against the backend on the app host before publishing traffic.

11. Traffic publication
Only after the app is healthy does it publish the TRM route and then verify the final public URL.

## Branch Behavior

- `main` deploys use a stable hostname like `<slug>.stephenjoly.net`
- non-main branches deploy as previews like `<slug>-<branch>.stephenjoly.net`
- preview branches use the same local image build path as `main`
- each preview gets its own remote compose file and app-data directory

## Proxy Publishing

The default flow uses Traefik Rules Manager.

- `render` generates `.deploy-wizard/generated/proxy/<route>.trm-rule.json` preview files
- the full wizard or `sync-proxy` calls the TRM automation API
- successful TRM responses are also written back as `.trm.generated.yaml` files for inspection
- `.deploy-wizard/trm-state.json` stores returned rule IDs locally for reliable updates

Important TRM limitation:

- each route must have exactly one host
- `pathPrefix` is not supported

## The Two Config Layers

### 1. Project Manifest

This lives in the repo as `deploy-wizard.yml`.

It describes:

- which compose files to read
- which services are managed
- which service is public
- the HTTP smoke-check path
- the staging compose/env paths
- the public routes

Example:

- [`docs/examples/deploy-wizard.example.yml`](./examples/deploy-wizard.example.yml)

### 2. Global Profile

This lives outside the repo and describes the fixed home-lab target:

- app host `stephen@10.87.111.253:33`
- compose root `/home/stephen/docker/compose`
- app-data root `/home/stephen/docker/appdata`
- TRM base URL and token env var

Example profiles:

- [`docs/examples/profile.ssh-file.example.yml`](./examples/profile.ssh-file.example.yml)
- [`docs/examples/profile.trm-api.example.yml`](./examples/profile.trm-api.example.yml)

## What To Do On Later Deploys

Once a project is already configured, rerun the same command from the app repo root:

```bash
deploy-wizard
```

The wizard will detect existing state and let you:

- reuse the current manifest and profile
- reuse the current env values
- rebuild and redeploy the exact updated image
- redeploy without repeating every setup prompt

## Advanced Manual Commands

These still exist when you want a narrower workflow:

- `deploy-wizard validate`: structural validation only
- `deploy-wizard render`: regenerate files without remote side effects
- `deploy-wizard sync-proxy`: publish only the proxy side
- `deploy-wizard apply --image-tag <tag>`: advanced deploy path with a known image tag
- `deploy-wizard apply`: advanced CI-backed deploy path
- `deploy-wizard destroy [--keep-files]`: tear down the current branch's staging deployment and, by default, remove local deploy-wizard artifacts too

The older generic setup flow has been archived under `archive/generic-manual-flow` and is no longer part of the active CLI.

## Environment Variables

### App runtime env

This is your app env file:

- `.deploy-wizard/staging.env.local`

It is uploaded to the staging app host during `apply`.

### TRM auth env

In `trm-api` mode, the TRM bearer token is read from the env var configured in the profile.

In the Stephen default flow, if that env var is not set, `deploy-wizard` will prompt for the token once and store it on your machine under:

- `~/.config/deploy-wizard/credentials.json`
- or `$XDG_CONFIG_HOME/deploy-wizard/credentials.json`

Example:

```bash
export DEPLOY_WIZARD_TRM_TOKEN=your_token_here
```

Do not put the TRM token in `deploy-wizard.yml` or the target app repo.

## Common Files You Should Know

- `deploy-wizard.yml`: project source of truth
- `.deploy-wizard/staging.overlay.yml`: deployment overlay
- `.deploy-wizard/generated/staging.compose.template.yml`: rendered compose template with image-tag placeholders
- `.deploy-wizard/generated/proxy/`: SSH YAML or TRM preview artifacts
- `.deploy-wizard/trm-state.json`: local TRM rule ID cache
- `.deploy-wizard/staging.env.example`: discovered-key staging env template
- `.deploy-wizard/staging.env.local`: local, ignored source of truth for staging env values
- `.github/workflows/deploy-staging.yml`: build-and-push workflow
- `DEPLOY.md`: generated project-specific deployment notes

## Practical Advice

- Use the full `deploy-wizard` command for normal operator use.
- Let the default wizard own image naming, env capture, local smoke checks, and deploy verification.
- Use `apply --image-tag ...` when you want to test deploy mechanics without involving CI.
- Use `destroy` when you want to fully remove the current branch's staging deployment from the app host and proxy layer.
- Use `render` and `sync-proxy` only when you intentionally want partial/manual control.