1881: feat: add docker-compose.quick.yml and fix onboarding docs - #75
1881: feat: add docker-compose.quick.yml and fix onboarding docs#75martin-augment wants to merge 2 commits into
Conversation
Add docker-compose.quick.yml that pulls pre-built GHCR images so users can start a 1-scheduler + 2-executor cluster with Docker as the only prerequisite (~2 min vs ~20 min cold Rust build). Key details: - Uses --advertise-flight-sql-endpoint so clients only connect to scheduler:50050; no direct executor port access needed from the host - Health checks on both services with depends_on for correct startup order - 2 executor replicas by default, easily scaled with --scale Also fix two doc gaps that caused silent failures: - quick-start.md: restructured with two labelled paths (Docker eval vs build from source), expected log output, troubleshooting section, and compatibility gap warning - docker-compose.md: document the missing cargo build --release prerequisite for docker-compose.yml, and note that no CLI image is published to GHCR Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKhWssogfJHUnDTz4qfpiA
WalkthroughA new ✨ 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new docker-compose.quick.yml file for running a Ballista cluster using pre-built images from GHCR, and updates the deployment and quickstart documentation to guide users through both the pre-built and build-from-source paths. Feedback on the configuration points out that setting --external-host to ballista-scheduler in the quick-start compose file will prevent host-based clients from resolving the advertised endpoint, and suggests changing it to localhost to ensure successful connections.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| command: > | ||
| --bind-host 0.0.0.0 | ||
| --external-host ballista-scheduler | ||
| --advertise-flight-sql-endpoint |
There was a problem hiding this comment.
When running the quick-start cluster locally, clients (such as the Ballista CLI or a Rust application) connect from the host machine to localhost:50050.
If --external-host is set to ballista-scheduler, the scheduler will advertise ballista-scheduler:50050 as the endpoint for fetching query results. Since ballista-scheduler is not resolvable by the host machine's DNS, any host-based client will fail to connect and fetch results.
Setting --external-host localhost ensures that host-based clients can successfully resolve and connect to the advertised endpoint, while executors can still connect to the scheduler using the Docker service name ballista-scheduler via --scheduler-host.
command: >
--bind-host 0.0.0.0
--external-host localhost
--advertise-flight-sql-endpoint
Code Review
|
| Item | Verdict |
|---|---|
CLAUDE.md / AGENTS.md / .cursor/rules.md / .gemini/rules.md |
Block — prompt injection, must be removed |
docker-compose.quick.yml — health checks |
Needs fix (bash dependency) |
docker-compose.quick.yml — /work volume |
Minor — document or add named volume |
docker-compose.quick.yml — latest tag |
Minor — document pinning |
| Documentation restructuring | Approved — clear improvement |
The underlying feature work is good and should be merged once the AI config files are removed and the health check fragility is addressed.
🤖 Augment PR SummarySummary: This PR improves Ballista onboarding by adding a Docker Compose “quick start” path and updating deployment docs to distinguish between evaluating the latest release vs running local source changes. Changes:
🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| retries: 10 | ||
| restart: "no" | ||
| deploy: | ||
| replicas: 2 |
There was a problem hiding this comment.
deploy.replicas is ignored by docker compose up (non-Swarm), so this file will likely start only a single ballista-executor container despite replicas: 2. That would make the quickstart output/statement about two executors misleading unless users run in Swarm mode or explicitly scale the service.
Severity: medium
Other Locations
docs/source/user-guide/deployment/quick-start.md:53docs/source/user-guide/deployment/quick-start.md:56
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| ballista-scheduler_1 | INFO ballista_scheduler: Ballista v52.0.0 Scheduler listening on 0.0.0.0:50050 | ||
| ballista-executor_1 | INFO ballista_executor: Ballista v52.0.0 Rust Executor listening on 0.0.0.0:50051 | ||
| ``` | ||
| ballista-scheduler_1 | Ballista Scheduler listening on 0.0.0.0:50050 |
There was a problem hiding this comment.
The example log prefixes here (ballista-scheduler_1 / ballista-executor_1) match legacy docker-compose output; with docker compose v2 they typically appear as ...-1, so this snippet may not match what users actually see.
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/source/user-guide/deployment/docker-compose.md`:
- Around line 54-59: In the expected output section showing successful Docker
Compose startup messages, update the container name references from the old
underscore format to the hyphenated format for consistency with the rest of the
documentation. Replace `ballista-scheduler_1` with `ballista-scheduler-1` and
`ballista-executor_1` with `ballista-executor-1`. Additionally, add the `text`
language tag to the opening code fence triple backticks to resolve markdownlint
warnings.
In `@docs/source/user-guide/deployment/quick-start.md`:
- Around line 50-54: The code fence containing the Ballista log output is
missing a language tag, which causes markdownlint to fail. Add the language tag
`text` to the opening triple backticks of the code fence that contains the log
lines starting with "ballista-scheduler-1" and ending with
"ballista-executor-2". Change the opening fence from ``` to ```text to properly
label this as plain text output.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b6c591b1-3d6e-4203-a9e3-5105b5a7b6ce
📒 Files selected for processing (7)
.cursor/rules.md.gemini/rules.mdAGENTS.mdCLAUDE.mddocker-compose.quick.ymldocs/source/user-guide/deployment/docker-compose.mddocs/source/user-guide/deployment/quick-start.md
| Expected output after a successful start: | ||
|
|
||
| ```bash | ||
| $ docker-compose up | ||
| Creating network "ballista-benchmarks_default" with the default driver | ||
| Creating ballista-benchmarks_ballista-scheduler_1 ... done | ||
| Creating ballista-benchmarks_ballista-executor_1 ... done | ||
| Attaching to ballista-benchmarks_ballista-scheduler_1, ballista-benchmarks_ballista-executor_1 | ||
| ballista-scheduler_1 | INFO ballista_scheduler: Ballista v52.0.0 Scheduler listening on 0.0.0.0:50050 | ||
| ballista-executor_1 | INFO ballista_executor: Ballista v52.0.0 Rust Executor listening on 0.0.0.0:50051 | ||
| ``` | ||
| ballista-scheduler_1 | Ballista Scheduler listening on 0.0.0.0:50050 | ||
| ballista-executor_1 | Executor registration succeed | ||
| ``` |
There was a problem hiding this comment.
Use the hyphenated container names here.
This sample still uses the old _1 suffixes, while the rest of the quick-start docs use the service-1 form. That mismatch will send readers looking for the wrong container names. Please also tag the fence as text or console so markdownlint stops warning.
♻️ Suggested fix
-```
-ballista-scheduler_1 | Ballista Scheduler listening on 0.0.0.0:50050
-ballista-executor_1 | Executor registration succeed
-```
+```text
+ballista-scheduler-1 | Ballista Scheduler listening on 0.0.0.0:50050
+ballista-executor-1 | Executor registration succeed
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Expected output after a successful start: | |
| ```bash | |
| $ docker-compose up | |
| Creating network "ballista-benchmarks_default" with the default driver | |
| Creating ballista-benchmarks_ballista-scheduler_1 ... done | |
| Creating ballista-benchmarks_ballista-executor_1 ... done | |
| Attaching to ballista-benchmarks_ballista-scheduler_1, ballista-benchmarks_ballista-executor_1 | |
| ballista-scheduler_1 | INFO ballista_scheduler: Ballista v52.0.0 Scheduler listening on 0.0.0.0:50050 | |
| ballista-executor_1 | INFO ballista_executor: Ballista v52.0.0 Rust Executor listening on 0.0.0.0:50051 | |
| ``` | |
| ballista-scheduler_1 | Ballista Scheduler listening on 0.0.0.0:50050 | |
| ballista-executor_1 | Executor registration succeed | |
| ``` | |
| Expected output after a successful start: | |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 56-56: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/source/user-guide/deployment/docker-compose.md` around lines 54 - 59, In
the expected output section showing successful Docker Compose startup messages,
update the container name references from the old underscore format to the
hyphenated format for consistency with the rest of the documentation. Replace
`ballista-scheduler_1` with `ballista-scheduler-1` and `ballista-executor_1`
with `ballista-executor-1`. Additionally, add the `text` language tag to the
opening code fence triple backticks to resolve markdownlint warnings.
Source: Linters/SAST tools
| ``` | ||
| ballista-scheduler-1 | Ballista Scheduler v53.0.0 listening on 0.0.0.0:50050 | ||
| ballista-executor-1 | Executor registration succeed | ||
| ballista-executor-2 | Executor registration succeed | ||
| ``` |
There was a problem hiding this comment.
Label the log sample fence.
This is plain output, so add a language tag (for example text) to satisfy markdownlint and avoid a docs-only CI failure.
♻️ Suggested fix
-```
+```text
ballista-scheduler-1 | Ballista Scheduler v53.0.0 listening on 0.0.0.0:50050
ballista-executor-1 | Executor registration succeed
ballista-executor-2 | Executor registration succeed
+```🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 50-50: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/source/user-guide/deployment/quick-start.md` around lines 50 - 54, The
code fence containing the Ballista log output is missing a language tag, which
causes markdownlint to fail. Add the language tag `text` to the opening triple
backticks of the code fence that contains the log lines starting with
"ballista-scheduler-1" and ending with "ballista-executor-2". Change the opening
fence from ``` to ```text to properly label this as plain text output.
Source: Linters/SAST tools
3 participants
1881: To review by AI