Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone

Relationships

#1969 Add interactive serve setup skill with best-practice guidance

Opened by stack72 · 9/2/2026

Problem

Setting up swamp serve requires users to navigate a multi-step decision tree (host type, dev vs production, datastore, vault, auth, TLS, grants) by reading architecture docs and assembling the right combination themselves. There's no guided flow that walks them through it based on their situation.

Proposed Solution

Create a new swamp:serve-setup skill (or similar) that uses the interactive state-machine pattern proven by swamp-getting-started and issue-lifecycle. The skill walks users through setup by asking about their situation and mapping answers to opinionated best-practice recommendations.

Decision tree

  1. What's the host? — local dev, single cloud VM, container/k8s
  2. Dev or production? — dev skips most of the below; production (including HA) hits all of it
  3. Datastore — S3, GCS, local filesystem (recommend S3/GCS for production)
  4. Vault backend — local file vs external (driven by host/prod answer)
  5. Auth — single-user token vs OAuth/SSO (driven by team size)
  6. TLS — recommend reverse proxy (nginx/Caddy) for TLS termination, not swamp serve itself
  7. Grants — who gets access to what

Each answer narrows the next question. A dev setup on localhost skips half of them. A production HA deployment hits all of them.

Key design principles

  • Lead with best practices, don't gate on them. The skill recommends the right setup and explains why (e.g., "We recommend Caddy for TLS termination because..."), but the user can always override. Make the right path the easy path.
  • Ask about the situation, not the config. Questions are about what the user is trying to do (host, scale, dev/prod), and we map that to the right setup — not "do you want TLS? Pick a method."
  • Fast-path experienced users. If someone says "I need HA with GCS and OIDC," skip the walkthrough and confirm the setup directly.
  • Separate from the serve guide. This is an interactive workflow skill, not a reference. The existing serve guide stays as-is for users who already know what they're doing.

Implementation notes

  • Use AskUserQuestion for structured choices with descriptions
  • Model on swamp-getting-started state machine: gate/action/verify/on-failure blocks per step
  • Progressive disclosure — only load references relevant to the user's chosen path
  • Could generate the final swamp serve command and any companion config (e.g., Caddyfile, nginx config) at the end
02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

9/2/2026, 7:16:40 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.