docs(readme): document proxy + no-proxy deploy modes in parallel by crowdy · Pull Request #116 · crowdy/conoha-cli

crowdy · 2026-04-21T12:19:10Z

Summary

Refreshes the three READMEs (JA/EN/KO) to document conoha app's two deploy modes symmetrically:

proxy (blue/green via conoha-proxy, default) — now with explicit mode-marker semantics, full conoha.yml schema (compose_file, accessories, health.*, deploy.drain_ms were previously undocumented), and an accurate --proxy/--no-proxy flag table row that distinguishes init (writes the mode to the marker) from other lifecycle commands (overrides marker, mismatch = error).
no-proxy (flat, --no-proxy) — shipped in feat: --no-proxy mode for app deploy/logs/status/stop/restart/destroy/init (TLS-less single-slot) #102/feat: --no-proxy mode for app deploy/init/logs/... (#102) #103; was previously only a one-line footnote. Now has a parallel walkthrough.
Flags reference table covering --slot, --drain-ms, --follow, --service, --tail, --data-dir, plus precise --app-name semantics (required where no conoha.yml exists; ignored in proxy mode).
conoha app env family (set/list/get/unset) — previously missing from the README.
Accurate description of .env assembly on deploy: repo-committed .env first, then /opt/conoha/<app>.env.server (written by app env set) appended — server-side values win via last-occurrence semantics. The prior "place a local .env.server and it's auto-copied" claim was wrong and has been corrected.

Code references

All claims traced back to:

cmd/app/init.go:46-52 — proxy init uses pf.Name from conoha.yml; --app-name flag ignored in proxy mode.
cmd/app/mode.go:145-170 — mode marker resolution + override/mismatch semantics.
cmd/app/rollback.go:22-26 — no-proxy rollback emits a dedicated "rollback is not supported in no-proxy mode" error (not a mode-mismatch error).
cmd/app/deploy.go:119-140 — server-side .env.server merge onto workdir .env.
internal/config/projectfile.go:15-43, 97-104 — conoha.yml schema including optional compose_file, accessories, health.*, deploy.drain_ms, and compose-file auto-detect order.

Review history

Implemented via superpowers:subagent-driven-development. Spec compliance + doc-quality review surfaced 1 Critical (wrong .env.server claim) and 3 Important findings (--proxy/--no-proxy flag-table row wrongly excluding init; wrong rollback error wording; cargo-cult --app-name in proxy-mode examples). All four fixed in follow-up commit `5e1394f`; plan file corrected in `6d980a6` so Phase B (skill repo) will not re-inherit the C1 bug.

Test plan

Every flag name, help string, and default value cross-checked against `conoha app _{--help` output.}
`conoha.yml` field list matches `internal/config/projectfile.go`.
Mode-marker + override-with-mismatch semantics cross-checked against `cmd/app/mode.go:145-170`.
`.env.server` merge semantics cross-checked against `cmd/app/deploy.go:132-140` (server-side path is authoritative; no local-file auto-copy).
JA/EN/KO header structure aligned (same section order, same table shape).

…y in parallel Expands the two-mode summary table with conoha.yml / proxy boot / DNS columns so users can pick a mode at a glance. Adds a parallel "no-proxy mode" subsection that previously only existed as a one-line footnote, plus explicit mode-marker semantics (set by init, auto-detected, --proxy / --no-proxy as override-with-error-on-mismatch). Also documents the full conoha.yml schema (compose_file, accessories, health, deploy.drain_ms) — previously only name/hosts/web were shown. Adds a flags reference table covering --slot, --drain-ms, --follow, --service, --tail, --data-dir that were reachable only via --help. No functional change; just documents features already shipped in #98 (proxy blue/green) and #102/#103 (--no-proxy mode).

- C1: correct .env.server semantics — the local-file auto-copy claim was wrong. `.env.server` is the server-side file at /opt/conoha/<app>.env.server, appended to the deploy's .env after the repo-committed .env (see cmd/app/deploy.go:132-140). - I1: flag-table row for --proxy/--no-proxy wrongly excluded `init`, which also takes the flag (selects the mode to write into the marker). See cmd/app/init.go:25. - I2: rollback on no-proxy emits a dedicated "rollback is not supported" error, not a mode-mismatch error. See cmd/app/rollback.go:22-26. - I3: drop redundant --app-name from proxy-mode init/deploy/rollback examples (proxy mode reads name from conoha.yml's `name` field; --app-name is silently ignored there). Tighten the flag-table row to distinguish where --app-name is actually required vs where it's overridden by conoha.yml.

The plan's replacement Markdown for Tasks 2/3/4 (JA/EN/KO READMEs) and the Phase B Task 7 recipe block embedded the same wrong "local .env.server auto-copies to .env on deploy" claim. Ground truth from cmd/app/deploy.go:107-140 and cmd/app/env.go:94,144,170,211: the server-side /opt/conoha/<app>.env.server file (written by `conoha app env set`) is appended onto the repo-committed .env at deploy time; no local .env.server is ever picked up specially. Plan updated so future re-runs don't regress the README.

…stall Docker, env is no-proxy only, drain_ms default 30000, flag scope excludes list Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…locks Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crowdy · 2026-04-21T12:49:16Z

Follow-up review (superpowers:code-reviewer, fresh eyes) surfaced 2 additional factual errors that survived the prior 2-stage review, plus 2 tightenings. All 4 fixed in `5f750c2` + `2f3ea8b`:

C1 (Critical): Docs claimed `conoha app init --no-proxy` installs Docker / Compose. Actually `cmd/app/init.go:120-127` only calls `command -v docker` and errors out with `docker is not installed on ...` if missing. Users following the old docs would have hit that error with no preparation. Fixed wording to "verifies Docker / Compose are installed; does not install them" across JA/EN/KO.
C2 (Critical): Docs presented `conoha app env` as working uniformly in both modes. In reality `cmd/app/env.go:14-27` emits `warning: app env has no effect on proxy-mode deployed slots; see app env: redesign for blue/green + accessory separation #94 for the redesign` and `runProxyDeploy` has no `.env.server` merge (only `buildNoProxyDeployCmd` at `deploy.go:132-140` does). Users setting `DATABASE_URL` via `app env set` in proxy mode would get silent nonmerge. Added an explicit caveat block pointing at #94 and recommending compose-side `environment:` / `env_file:` for proxy mode.
I1 (Minor): Clarified that omitting `deploy.drain_ms` in `conoha.yml` falls back to 30000 ms (from `cmd/app/deploy.go:257-259`), not "proxy default" (that applies only to `rollback --drain-ms 0`).
I2 (Minor): Flag-table row for `--proxy` / `--no-proxy` tightened from "all lifecycle commands" to "lifecycle commands (not `list`)" — `conoha app list` does not take these flags.

The plan file was also updated in `2f3ea8b` to propagate the same corrections so they are preserved in the repo's plan archive.

…ugh (#117) (#118) Fills three gaps in the proxy blue/green walkthrough that surfaced during post-merge review of #116: - N1: --slot auto-suffix on collision. Previously the flag description only covered explicit slot reuse. Now also notes that when --slot is omitted, a default-ID collision with a still-draining or running compose project triggers auto-suffix (-2, -3, ...) rather than destroying the other project (slot.go:47-57, deploy.go:188-194). - N3a: skipping `conoha proxy boot` and going straight to `app init` fails with an Admin API socket error — now called out inline under step 2. - N3b: DNS must resolve by the time `app init` registers the host. If it doesn't, the `app`-layer deploy still succeeds but ACME keeps failing and the hostname serves invalid certs until validation eventually succeeds — now called out inline under step 3. The skill recipe already covered this via its troubleshooting table; README now matches. Applied symmetrically across README.md (JA), README-en.md, README-ko.md. Closes #117 Co-authored-by: t-kim <t-kim@planitai.co.jp>

t-kim-planitai added 5 commits April 21, 2026 21:06

docs(readme-en): mirror proxy + no-proxy refresh from README.md

399eab2

docs(readme-ko): mirror proxy + no-proxy refresh from README.md

06c59e1

crowdy mentioned this pull request Apr 21, 2026

docs: refresh SKILL.md and recipe for proxy + no-proxy modes crowdy/conoha-cli-skill#7

Merged

5 tasks

t-kim-planitai and others added 2 commits April 21, 2026 21:44

docs(readme): fix C1/C2/I1/I2 from review — no-proxy init does not in…

5f750c2

…stall Docker, env is no-proxy only, drain_ms default 30000, flag scope excludes list Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs(plan): propagate C1/C2/I1/I2 corrections into plan replacement b…

2f3ea8b

…locks Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crowdy merged commit f7aea27 into main Apr 21, 2026
3 checks passed

crowdy deleted the docs/readme-noproxy-refresh branch April 21, 2026 12:53

crowdy mentioned this pull request Apr 21, 2026

docs(readme): cover 3 operational edge cases in app deploy walkthrough #117

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(readme): document proxy + no-proxy deploy modes in parallel#116

docs(readme): document proxy + no-proxy deploy modes in parallel#116
crowdy merged 7 commits into
mainfrom
docs/readme-noproxy-refresh

crowdy commented Apr 21, 2026

Uh oh!

crowdy commented Apr 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

crowdy commented Apr 21, 2026

Summary

Code references

Review history

Test plan

Uh oh!

crowdy commented Apr 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants