Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 122 additions & 0 deletions suggestions/website/compose-cli-selection-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
title: Compose CLI Selection Contract
description: Constructional contract so tu-vm.sh selects Docker Compose with the plugin-first order doctor, check-config, and smoke-test already use.
last_updated: 2026-11-03
owner: maintainers
status: proposed
theme: tooling
impact: high
---

# Compose CLI Selection Contract

## Problem

Day-to-day commands in `tu-vm.sh` ask `get_docker_compose_cmd` for the Compose CLI:

```bash
get_docker_compose_cmd() {
if command -v docker-compose >/dev/null 2>&1; then
echo "docker-compose"
else
echo "docker compose"
fi
}
```

Any executable named `docker-compose` on `PATH` wins, including a leftover Compose V1 binary. The plugin is never asked.

Three maintained scripts already use the opposite order. `scripts/doctor.sh`, `scripts/check-config.sh`, and `scripts/smoke-test.sh` each define `compose_cmd` as:

```bash
if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then
docker compose "$@"
elif command -v docker-compose >/dev/null 2>&1; then
docker-compose "$@"
fi
```

`scripts/safe-update.sh` and `scripts/switch-pdf-loader.sh` call `docker compose` directly.

Replayed on 2026-11-03 with both functions copied into the shell. This host has Docker Compose plugin v5.1.0 and no `docker-compose` on the default `PATH`. A temporary stub named `docker-compose` printed `legacy-compose-stub` and exited 0. The stub directory was removed afterward. The Docker daemon was not started.

| PATH | `get_docker_compose_cmd` (tu-vm.sh) | `compose_cmd` (doctor, check-config, smoke-test) |
|---|---|---|
| Default, Compose v5.1.0, no `docker-compose` binary | `docker compose` | `docker compose` |
| Stub `docker-compose` placed first | The stub path | `docker compose` |

On the default PATH the two orders agree, so a quickstart on this host hides the split. On a host that still has a `docker-compose` binary, `./tu-vm.sh doctor` and `./scripts/check-config.sh` render the project with the plugin, and `./tu-vm.sh start` renders it with the other binary. The same `docker-compose.yml` then has two interpreters: one for the contributor check and one for the operator command.

Checked by reading `get_docker_compose_cmd` and the three `compose_cmd` functions, and by the replay above. `.env` was not created.

## Existing scan (reuse first)

| Asset | Role |
|---|---|
| `get_docker_compose_cmd` | The selector every `tu-vm.sh` Compose call uses |
| `compose_cmd` in `scripts/doctor.sh` | Plugin first, `docker-compose` only as fallback |
| `compose_cmd` in `scripts/check-config.sh` | The same order, used by CI and pre-push |
| `compose_cmd` in `scripts/smoke-test.sh` | The same order |
| `scripts/safe-update.sh` | Already invokes `docker compose` |
| Compose plugin v5.1.0 | The CLI this environment actually runs |
| Stage 64 and Stage 55 pages (open PRs #90 and #81) | What `ps` and rollback do with whatever CLI was selected. Unchanged here |

Out of scope:

- Vendoring a Compose binary or pinning a Compose release in this repo
- Rewriting `doctor.sh`, `check-config.sh`, or `smoke-test.sh` (they already agree)
- Replacing `tu-vm.sh` with raw `docker compose` for operators
- Editing Compose service definitions

## Proposal

Make `get_docker_compose_cmd` use the plugin-first test the three scripts already use. Keep `docker-compose` as the fallback for a host whose only CLI is that name.

### Contribution lanes

| Lane | Where | Suggested change |
|---|---|---|
| Selection | `get_docker_compose_cmd` | If `docker compose version` succeeds, print `docker compose`. Else if `command -v docker-compose` succeeds, print `docker-compose` |
| Call sites | `$compose_cmd up`, `ps`, `build`, and the rest | Leave them. They already expand the string this function prints |
| Doctor and CI | `compose_cmd` in the three scripts | Leave the order as it is |
| Failure | Neither CLI works | Keep a clear error. `check_docker_compose` already rejects a host with neither `docker-compose` nor `docker compose version` |

### Rules

1. **The plugin wins when it runs.** `docker compose version` succeeding means every `tu-vm.sh` Compose command uses `docker compose`.
2. **A lone `docker-compose` still works.** Hosts without the plugin keep the fallback the doctor script already has.
3. **Doctor and start agree.** With both binaries present, `./tu-vm.sh doctor` and `./tu-vm.sh start` use the same CLI.
4. **Call sites stay word-split expansions of one string.** `docker compose` remains two words, as it is today when the plugin is selected.
5. **The three scripts stay the source of the order.** Copy that condition. Leave their functions in place.

### Suggested contributor checklist

```text
1. On a PATH with only the Compose plugin, print docker compose
2. On a PATH with a docker-compose stub ahead of the plugin, still print docker compose
3. On a PATH whose docker compose version fails and docker-compose exists, print docker-compose
4. Confirm doctor.sh, check-config.sh, and smoke-test.sh compose_cmd functions are unchanged
5. Confirm .env was not created to prove this page
```

### Framework reuse

| Need | Prefer | Avoid |
|---|---|---|
| Compose CLI | Plugin-first test already in `doctor.sh` | A new wrapper script |
| Fallback | `docker-compose` when the plugin is absent | Deleting the fallback |
| Version proof | `docker compose version`, already used by the three scripts | Parsing `docker --help` |
| Intake | GitHub Issue | A Compose installer in `tu-vm.sh` |

### Acceptance check

- [ ] `get_docker_compose_cmd` tries `docker compose version` before `command -v docker-compose`.
- [ ] When the plugin answers, the function prints `docker compose`.
- [ ] When the plugin is missing and `docker-compose` exists, the function prints `docker-compose`.
- [ ] `compose_cmd` in `doctor.sh`, `check-config.sh`, and `smoke-test.sh` is unchanged.
- [ ] A `docker-compose` stub earlier on `PATH` does not override a working plugin.
- [ ] The Docker daemon was not started to prove this, and `.env` was not created.

### Rollback

Restore the `command -v docker-compose` test as the first branch. Hosts with only the plugin behave the same. Hosts with both binaries return to starting the stack with `docker-compose` while doctor uses the plugin.
93 changes: 93 additions & 0 deletions suggestions/website/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
---
title: Community Suggestions Website
description: Publishable Stage 67 website markdown for restart, quickstart flags, and the Compose command tu-vm.sh selects.
last_updated: 2026-11-03
owner: maintainers
status: proposed
---

# Community Suggestions Website

This directory holds **publishable website markdown**: curated pages a future static docs site can ship without a second editable copy.

Participation stays on GitHub. These pages say which existing TU-VM tools to extend so day-to-day restart, beginner quickstart, and Compose selection stay reliable for a community of operators and contributors.

## Why this exists

TU-VM already has the community path and the operator tools: GitHub Issues, `CONTRIBUTING.md`, `tu-vm.sh`, the helper API, the Nginx landing page, the document processor, playbooks, and CI. Historical suggestion files in `suggestions/` and open website PRs #27–#91 already specify the docs framework, governance, and most product contracts. Stage 66 is on branch `cursor/community-suggestions-structure-7911`.

**Stage 67** (this run) records three defects checked on 2026-11-03. They are not restatements of Stages 1–66.

- `./tu-vm.sh restart` calls `stop_services` and then `start_services` with no mode argument. With the default `TU_VM_DEFAULT_MODE` of `portable`, a stack that was started with `./tu-vm.sh server` comes back as portable. `update_system` already snapshots `docker compose ps --services --status running` and restores that set.
- `./tu-vm.sh quickstart` documents `--server` and `--no-secure` as separate words. `main` passes only `"${2:-}"`. `quickstart --server --no-secure` therefore starts the full stack and still runs `enable_secure`. The reverse order skips the firewall and stays portable. The single token `--server-no-secure` is the only combination the function accepts.
- `get_docker_compose_cmd` in `tu-vm.sh` selects a `docker-compose` binary whenever `command -v` finds one. `scripts/doctor.sh`, `scripts/check-config.sh`, and `scripts/smoke-test.sh` ask `docker compose version` first and use `docker-compose` only when the plugin is absent. On this machine Compose is v5.1.0 and `docker-compose` is absent, so both paths print `docker compose`. A `docker-compose` stub placed first on `PATH` is what `tu-vm.sh` selects, while the three scripts still select `docker compose`.

The contracts:

- Restart the services that were running, and recreate the services that were stopped without starting them, using the same Compose status filters `update_system` already uses.
- Parse every word after `quickstart`, and allow `--server` together with `--no-secure`.
- Select the Compose CLI with the plugin-first order the doctor, check-config, and smoke scripts already share.

No second process manager, installer, or Compose distribution.

## Boundaries (do not reinvent)

| Already exists | Website role |
|---|---|
| GitHub Issues + suggestion form | Sole proposal intake |
| [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | Contributor path and labels |
| [`SECURITY.md`](../../SECURITY.md) | Vulnerability reporting |
| [`docs/playbooks/`](../../docs/playbooks/README.md) | Operator recipes |
| Nginx landing page | Local control plane |
| Historical files in [`suggestions/`](../) | Archive and planning source |
| Stage 1–66 website pages (open PRs #27–#91 and the Stage 66 branch) | Implement those contracts in code; leave their pages as they are |
| `update_system` running and stopped service lists | The restart behavior to copy |
| `quickstart_beginner`, `setup_platform`, `start_services`, `enable_secure` | The beginner path to keep |
| `compose_cmd` in `doctor.sh`, `check-config.sh`, and `smoke-test.sh` | The Compose selection order `tu-vm.sh` should match |

Stage 66 owns `stop_services` (`docker compose down` versus `docker compose stop`). This stage calls `stop_services` and leaves that function unchanged. Stage 65 (open PR #91) owns container prune. The beginner quickstart contribution page on branch `cursor/community-suggestions-system-0fa7` owns portable-by-default onboarding. This stage only fixes argument parsing on that same command.

## Page map (Stage 67)

| Page | Purpose |
|---|---|
| [Restart preserves the running set](./restart-preserves-running-set-contract.md) | `./tu-vm.sh restart` must bring back the services that were running |
| [Quickstart flag combination](./quickstart-flag-combination-contract.md) | `--server` and `--no-secure` must work together |
| [Compose CLI selection](./compose-cli-selection-contract.md) | `tu-vm.sh` must pick the same Compose CLI the other scripts already pick |

## Expected sibling pages

Stages 1–66 are not files on this branch. When those PRs merge, keep their pages as siblings in this folder. Leave those files uncopied here.

Representative filenames only: `openwebui-audio-model-parameter-contract.md`, `stop-preserves-containers-contract.md`, `optional-command-argument-contract.md`, `pihole-webpassword-quote-contract.md`, `backup-running-gate-contract.md`.

Extend `stage-merge-playbook.md` through **Stage 67** when reconciling hubs so earlier pages are not dropped.

## Framework reuse (summary)

| Need | Prefer | Avoid |
|---|---|---|
| Proposal intake | GitHub Issues | A suggestion database |
| Docs site | Static framework already proposed in Stage 3 (Starlight remains the default) | A custom community portal |
| Restart target | `docker compose ps --services --status`, already used in `update_system` | A second record of which mode was last used |
| Quickstart flags | The `case` arms already inside `quickstart_beginner` | A new CLI parser |
| Compose CLI | Plugin-first `compose_cmd` already in three scripts | Installing or pinning another Compose binary |

## Navigation for a future docs site

Map this folder to a `Community` section:

1. How to submit, status, and decisions (Stages 1–4, when those PRs are merged)
2. Operator day-to-day: Restart brings back the services that were running
3. Operator day-to-day: Quickstart accepts `--server` and `--no-secure` together
4. Contributor day-to-day: `tu-vm.sh` and `doctor` use the same Compose CLI

When a static site is adopted, move or mount these pages into the docs content root. Keep a single editable copy.

## Related archive and planning docs

- [`../README.md`](../README.md) — suggestions hub
- [`../index.md`](../index.md) — community suggestions map
- [`../implementation-backlog.md`](../implementation-backlog.md) — trimmed execution backlog
- [`../historical-suggestions.md`](../historical-suggestions.md) — changelog ideas
- [`../website-roadmap-from-historical-suggestions.md`](../website-roadmap-from-historical-suggestions.md) — historical product direction
124 changes: 124 additions & 0 deletions suggestions/website/quickstart-flag-combination-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
title: Quickstart Flag Combination Contract
description: Constructional contract so tu-vm.sh quickstart accepts --server and --no-secure together, using the case arms the function already has.
last_updated: 2026-11-03
owner: maintainers
status: proposed
theme: community
impact: medium
---

# Quickstart Flag Combination Contract

## Problem

Help lists two explicit quickstart modifiers:

```text
quickstart One-command beginner setup (portable mode)
quickstart --server One-command full-stack setup
quickstart --no-secure Skip firewall step (not recommended)
```

`main` forwards one word:

```bash
quickstart|easy-start|easy)
quickstart_beginner "${2:-}"
```

`quickstart_beginner` switches on that single string. Each arm sets one outcome. `--server` sets server mode and leaves `apply_secure=auto`, so a root run calls `enable_secure`. `--no-secure` sets portable mode and `apply_secure=never`. A separate token, `--server-no-secure`, sets both, and help does not mention it.

Replayed on Bash 5.2.21 with the same `case`, without executing `tu-vm.sh`:

| Command words | Word `main` passes | Result |
|---|---|---|
| `quickstart --server --no-secure` | `--server` | `mode=server`, `secure=auto` |
| `quickstart --no-secure --server` | `--no-secure` | `mode=portable`, `secure=never` |
| `quickstart --server-no-secure` | `--server-no-secure` | `mode=server`, `secure=never` |
| `quickstart` | empty | `mode=portable`, `secure=auto` |

The first command is the one an operator types from the two help lines. It still applies the firewall. The second command drops `--server`. Neither prints `Unknown quickstart option`, because the extra word never reaches the function.

Checked on 2026-11-03 by reading `show_help`, the `quickstart` arm in `main`, and `quickstart_beginner`. The function was not executed, so `setup_platform`, `start_services`, and `enable_secure` did not run. `.env` was not created.

The beginner quickstart contribution page on branch `cursor/community-suggestions-system-0fa7` already says portable stays the default and `--no-secure` stays opt-in. This page is the parser that currently cannot see both words.

## Existing scan (reuse first)

| Asset | Role |
|---|---|
| `quickstart_beginner` | Setup, start, optional `enable_secure`, post-checks |
| `case` arms for `--server`, `--portable`, `--no-secure`, `--server-no-secure` | The outcomes to keep |
| `setup_platform` | Secrets, DNS, SSL. Still the only installer step |
| `start_services --server` / `--portable` | The two start forms quickstart already calls |
| `enable_secure` | The firewall step `--no-secure` skips |
| `show_help` beginner block | The two flags operators see |
| Stage 18 beginner quickstart page (branch `cursor/community-suggestions-system-0fa7`) | Portable default, one command, firewall opt-out stays explicit |
| Stage 55 firewall command order (open PR #81) | What `enable_secure` appends. Unchanged here |

Out of scope:

- A new installer, a GUI, or a flag-parsing library
- Making `--server` the default
- Making `--no-secure` the default
- Editing `enable_secure` (Stage 55)

## Proposal

Forward every word after `quickstart`, and let each existing arm set its own field. `--server` and `--no-secure` may both be present.

### Contribution lanes

| Lane | Where | Suggested change |
|---|---|---|
| Dispatch | `quickstart` arm in `main` | `quickstart_beginner "${@:2}"` |
| Parse | `quickstart_beginner` | Loop over `"$@"` and apply the current arms. An unknown word still calls `error` with the existing usage text |
| Server | `--server`, `server`, `--all` | Set `mode=server` and leave the secure flag as it stands |
| Firewall opt-out | `--no-secure` | Set `apply_secure=never` and leave the mode as it stands |
| Alias | `--server-no-secure` | Keep setting both, so a script that already passes that token still works |
| Help | Beginner examples | Show `quickstart --server --no-secure` as the combined form |

### Rules

1. **Portable remains the default.** No flag still calls `start_services --portable`.
2. **`--server` and `--no-secure` compose.** Together they call `start_services --server` and skip `enable_secure`.
3. **Order does not matter.** `--no-secure --server` and `--server --no-secure` are the same outcome.
4. **An unknown word still fails.** `quickstart --servers` prints the usage `error` already uses.
5. **`--server-no-secure` remains accepted.** It is the one-token form of the same pair.
6. **The firewall function is unchanged.** Skipping it means the existing `apply_secure=never` branch.

### Suggested contributor checklist

```text
1. Replay quickstart --server --no-secure and confirm both mode=server and secure=never
2. Replay quickstart --no-secure --server and confirm the same pair
3. Replay bare quickstart and confirm portable plus secure=auto
4. Replay an unknown token and confirm the existing error text
5. Confirm enable_secure and start_services bodies were not edited
6. Confirm .env was not created to prove this page
```

### Framework reuse

| Need | Prefer | Avoid |
|---|---|---|
| Flag meanings | The `case` arms already in `quickstart_beginner` | A CLI parsing library |
| Extra words | `"${@:2}"`, the form `doctor` and `check-config` already use in `main` | Reading only `$2` |
| Install step | `setup_platform` | A second setup script |
| Intake | GitHub Issue | A wrapper around `quickstart` |

### Acceptance check

- [ ] The `quickstart` arm passes `"${@:2}"`.
- [ ] `quickstart --server --no-secure` selects server mode and `apply_secure=never`.
- [ ] `quickstart --no-secure --server` selects the same pair.
- [ ] Bare `quickstart` stays portable and still applies secure mode when root.
- [ ] `--server-no-secure` still selects server mode and skips the firewall.
- [ ] An unknown token still fails with the current usage text.
- [ ] `enable_secure` is unchanged.
- [ ] `./tu-vm.sh quickstart` was not executed to prove this, so `.env` was not created.

### Rollback

Pass `"${2:-}"` again and restore the single-argument `case`. One-flag commands behave the same. Two-flag commands return to honoring only the first flag.
Loading
Loading