feat: add guided walkthrough with Codespaces support#286
Open
AntTheLimey wants to merge 1 commit intomainfrom
Open
feat: add guided walkthrough with Codespaces support#286AntTheLimey wants to merge 1 commit intomainfrom
AntTheLimey wants to merge 1 commit intomainfrom
Conversation
📝 WalkthroughWalkthroughAdds a guided walkthrough feature: devcontainer configurations, Codespaces post-create behavior, interactive bash scripts for setup/run/validation of a 3-node distributed PostgreSQL cluster (Spock multi-master) via the pgEdge Control Plane, new documentation, and a small mkdocs/navigation and .gitignore update. Changes
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Member
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
AntTheLimey
force-pushed
the
feature/walkthrough
branch
from
76efa02 to
fe7ad40
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/walkthrough.md`:
- Around line 39-52: The docs currently imply install.sh only downloads files
but the bootstrap now launches examples/walkthrough/guide.sh, which is
confusing; update docs/walkthrough.md to state that running the curl | bash
command will run the installer which in turn launches the interactive guide
(install.sh) and add a note explaining how to rerun the interactive guide
manually from the repo root via bash examples/walkthrough/guide.sh so users
don’t try to start it twice.
- Around line 305-317: Replace the container-existence poll with an active
Postgres readiness check and a replication-sync check: instead of using docker
ps for n2, loop until a psql connection (PGPASSWORD=password psql -h localhost
-p 5433 -U admin example -c "SELECT 1") succeeds to ensure Postgres is accepting
connections, then loop until a replication verification query
(PGPASSWORD=password psql -h localhost -p 5433 -U admin example -tAc "SELECT 1
FROM example WHERE id = 3;") returns the expected row, sleeping between
attempts; update the echo messages accordingly to "Waiting for n2 to accept
connections..." and "Replication is synced." so readiness and replication are
both guaranteed before proceeding.
In `@examples/walkthrough/guide.sh`:
- Around line 8-11: The script defines CP_PORT and uses it for CP_URL but never
passes it into docker run, so the container (started with --network host) still
listens on 3000; update the docker run/startup steps that reference
CP_CONTAINER/CP_IMAGE to bind or set the control-plane port consistently by
exporting or injecting CP_PORT into the container startup (or hardcode 3000),
e.g., ensure the docker run command uses -p "${CP_PORT}:3000" or configures the
container to listen on "${CP_PORT}" so CP_URL and the container port match;
apply the same change to the other startup/health-check blocks mentioned (around
the other occurrences).
- Around line 238-239: The docker container/service resolution in the prompt_run
invocations (e.g., the line calling prompt_run "docker exec $(docker ps --filter
label=pgedge.node.name=n1 --format '{{.Names}}') ...") is too broad and can pick
other databases' nodes; update every docker ps and docker service ls selector
that currently filters only by pgedge.node.name (and where used,
pgedge.component) to also include --filter label=pgedge.database.id=${DB_ID} so
the lookups are scoped to this walkthrough's database; ensure all occurrences
(the prompt_run calls and any docker service ls lines referenced around the
ranges noted) add that extra filter and keep the same --format/command usage.
In `@examples/walkthrough/setup.sh`:
- Around line 62-84: When the script checks "if ! docker info &>/dev/null" avoid
unconditionally using systemctl/usermod recovery steps; first test for systemd
by using "command -v systemctl" before calling systemctl is-active and emitting
systemd-specific instructions. If systemctl is not available, capture the docker
info error output and call error/explain to report a generic "Docker socket is
unreachable" message including the captured docker info failure text and a
suggestion to check Docker in the current environment (e.g., start the daemon or
use containerdev features), rather than printing systemd-specific commands;
update the branch that currently uses systemctl is-active, error, and explain so
it first gates on command -v systemctl and uses the alternate generic messaging
when systemctl is absent, referencing the docker info check, systemctl
is-active, error, explain, and SCRIPT_DIR symbols to locate the changes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b180121f-0e79-4b2c-8386-001e632716e5
📒 Files selected for processing (9)
.devcontainer/dev/devcontainer.json.devcontainer/walkthrough/devcontainer.json.devcontainer/walkthrough/post-create.shdocs/walkthrough.mdexamples/walkthrough/guide.shexamples/walkthrough/install.shexamples/walkthrough/runner.shexamples/walkthrough/setup.shmkdocs.yml
AntTheLimey
force-pushed
the
feature/walkthrough
branch
3 times, most recently
from
835ac10 to
e74ffb1
Compare
Add a guided walkthrough that deploys a 3-node distributed PostgreSQL database with active-active multi-master replication using the Spock extension, all orchestrated by pgEdge Control Plane. Three ways to experience the walkthrough: - Docs site — walkthrough.md renders as a standard MkDocs page - Interactive terminal guide — guide.sh with branded UX and spinners - GitHub Codespaces — one-click environment with Docker-in-Docker Includes: - docs/walkthrough.md — 4-step walkthrough with prerequisites, macOS Docker Desktop instructions, and cleanup - examples/walkthrough/guide.sh — interactive terminal guide - examples/walkthrough/setup.sh — cross-platform prerequisites checker (Linux + macOS) - examples/walkthrough/install.sh — curl-pipe bootstrap with interactive picker - examples/walkthrough/runner.sh — terminal UX framework - .devcontainer/ — Codespaces devcontainers for walkthrough and dev
AntTheLimey
force-pushed
the
feature/walkthrough
branch
from
e74ffb1 to
9284d0a
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (1)
examples/walkthrough/runner.sh (1)
59-82: Consider capturing the command's exit status for debugging.The
eval "$cmd"calls don't preserve the exit status, so command failures won't propagate. This is likely intentional for walkthrough UX (continue even if a step fails), but you may want to at least display the exit status for user awareness.That said, the current behavior is reasonable for an interactive guide where output visibility is the primary concern.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@examples/walkthrough/runner.sh` around lines 59 - 82, The prompt_run function currently uses eval "$cmd" (both in the slow and fast branches) without capturing or displaying the command's exit status; modify prompt_run to capture the exit code immediately after each eval (e.g., local exit_code=$?), then print or log that exit code (and optionally a brief success/failure message) so users can see failures for debugging; ensure you capture the exit code right after eval in both the tmpfile branch (after eval "$cmd" > "$tmpfile" ...) and the direct branch (after eval "$cmd" 2> ...), and preserve existing spinner/tmptfile cleanup behavior in start_spinner/stop_spinner and rm -f "$tmpfile".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@examples/walkthrough/runner.sh`:
- Around line 59-82: The prompt_run function currently uses eval "$cmd" (both in
the slow and fast branches) without capturing or displaying the command's exit
status; modify prompt_run to capture the exit code immediately after each eval
(e.g., local exit_code=$?), then print or log that exit code (and optionally a
brief success/failure message) so users can see failures for debugging; ensure
you capture the exit code right after eval in both the tmpfile branch (after
eval "$cmd" > "$tmpfile" ...) and the direct branch (after eval "$cmd" 2> ...),
and preserve existing spinner/tmptfile cleanup behavior in
start_spinner/stop_spinner and rm -f "$tmpfile".
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: de0f2cb5-4b88-42db-92e5-c7b247e5d119
📒 Files selected for processing (10)
.devcontainer/dev/devcontainer.json.devcontainer/walkthrough/devcontainer.json.devcontainer/walkthrough/post-create.sh.gitignoredocs/walkthrough.mdexamples/walkthrough/guide.shexamples/walkthrough/install.shexamples/walkthrough/runner.shexamples/walkthrough/setup.shmkdocs.yml
🚧 Files skipped from review as they are similar to previous changes (6)
- examples/walkthrough/setup.sh
- mkdocs.yml
- .devcontainer/walkthrough/devcontainer.json
- examples/walkthrough/install.sh
- examples/walkthrough/guide.sh
- .devcontainer/dev/devcontainer.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a guided walkthrough that deploys a 3-node distributed PostgreSQL
database with active-active multi-master replication using the Spock
extension, all orchestrated by pgEdge Control Plane.
Three ways to experience the walkthrough
docs/walkthrough.mdrenders as a standard MkDocspage at docs.pgedge.com with admonitions, tips, and copyable code
blocks
examples/walkthrough/guide.shwalks you through the same steps with branded UX, spinners, and
press-Enter prompts
pre-configured and walkthrough auto-opened via the Runme VS Code
extension
walkthrough.mdis designed to work in any context: discovered on thedocs site and followed by hand, opened in VS Code with Runme for
click-to-execute cells, or used alongside the interactive guide as a
reference. All code blocks use
docker execfor psql so no host-sidePostgres client is needed.
What's included
docs/walkthrough.md— 4-step walkthrough (start CP, create DB,verify replication, resilience demo) with prerequisites section,
cleanup instructions, and Explore Further commands
examples/walkthrough/guide.sh— interactive terminal guidewith the same 4 steps, branded output, spinners, and idempotent
re-run support
examples/walkthrough/setup.sh— prerequisites checker:validates docker/curl/jq are installed, Docker daemon is accessible,
and (on macOS) Docker Desktop host networking is enabled
examples/walkthrough/install.sh— curl-pipe bootstrap thatdownloads walkthrough files, runs setup, and presents a picker to
choose between the interactive guide or self-paced walkthrough
examples/walkthrough/runner.sh— terminal UX framework withpgEdge brand colors, output dividers, spinners, and interactive
prompts
.devcontainer/— Codespaces devcontainers for both walkthroughand development workflows
Cross-platform support (Linux + macOS)
setup.shdetects the OS and adjusts Docker diagnostics: systemctlon Linux, Docker Desktop guidance on macOS, generic fallback for
non-systemd Linux
setup.shvalidates Docker Desktop host networking on macOS (runs athrowaway
--network hostcontainer) with step-by-step enableinstructions if it fails
guide.shusesssfor port detection on Linux,lsofon macOSguide.shuses--advertise-addrfor Swarm init on Linux (handlesmulti-interface hosts), plain
docker swarm initon macOSwalkthrough.mdhas an explicit Prerequisites section with macOSDocker Desktop host networking instructions and a tip for the Swarm
multi-interface error
Test plan
Interactive guide (guide.sh)
Walkthrough markdown (walkthrough.md)
mkdocs serve— verify page renders with prerequisites, admonitions, and tipsBootstrap installer (install.sh)
curl -fsSL .../install.sh | bash— downloads files, runs setupCodespaces