Conversation
Add comprehensive CLAUDE.md documentation for the ACAS docker compose environment, including: - Wait script for services to be ready (based on docker_bob_setup.sh) - Docker compose lifecycle commands - Common workflows for code changes - Volume management - Troubleshooting steps The wait script polls http://localhost:3001/api/authors to verify ACAS is ready, which implicitly confirms the roo service is also ready since the acas container waits for roo during startup. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Make shell wait script POSIX-safe (use -eq, quote variables, while loop) - Convert relative links to full GitHub URLs for cross-repo references - Ensures documentation is accessible when viewed on GitHub Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new CLAUDE.md document describing how to run ACAS locally with Docker Compose, including service/port overview, image/tag conventions, common workflows, and troubleshooting guidance.
Changes:
- Introduces
CLAUDE.mdwith Docker Compose environment documentation - Documents image naming/tagging and local Roo image workflow
- Adds a “wait for services” snippet and operational troubleshooting notes
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Alternative: docker compose.override.yml | ||
|
|
||
| Instead of editing `docker compose.yml` directly, you can create a `docker compose.override.yml`: | ||
|
|
||
| ```yaml | ||
| # docker compose.override.yml | ||
| version: '2' |
There was a problem hiding this comment.
Docker Compose only auto-loads override files with the standard naming (docker-compose.override.yml / compose.override.yml). A file named docker compose.override.yml (with a space) will not be picked up automatically, so users would have to pass -f explicitly.
| image: mcneilco/acas-roo-server-oss:dev | ||
| ``` | ||
|
|
||
| This file is automatically loaded by docker compose and won't be committed to git (if properly gitignored). |
There was a problem hiding this comment.
“Automatically loaded … and won't be committed to git” isn’t accurate as written: override auto-loading depends on the correct filename, and git will still see the file unless it’s ignored. Consider explicitly instructing users to add the override filename to .gitignore (or use .git/info/exclude) if you want to prevent accidental commits.
| This file is automatically loaded by docker compose and won't be committed to git (if properly gitignored). | |
| When named `docker compose.override.yml` in the same directory as your main compose file, this file is automatically loaded by Docker Compose. To avoid accidentally committing it, add `docker compose.override.yml` to your `.gitignore` (or `.git/info/exclude`). |
|
|
||
| ## Waiting for Services to be Ready | ||
|
|
||
| After starting services, it takes time for all services to initialize. The ACAS container waits for the Roo service to be ready before completing its own startup, so you only need to wait for the ACAS API endpoint. |
There was a problem hiding this comment.
The explanation that “the ACAS container waits for the Roo service to be ready” doesn’t match the current docker-compose.yml wiring (there’s no depends_on from acas to roo, and the wait-for-it.sh usage is on the roo service waiting for db). It would be more accurate to justify the check as “/api/authors depends on the persistence service (roo), so it’s a good readiness signal for backend availability.”
| After starting services, it takes time for all services to initialize. The ACAS container waits for the Roo service to be ready before completing its own startup, so you only need to wait for the ACAS API endpoint. | |
| After starting services, it takes time for all services to initialize. The `/api/authors` endpoint on the ACAS API depends on the Roo persistence service (and its database), so once this endpoint responds successfully the backend stack is ready. |
| The `docker compose.yml` defines four services: | ||
|
|
There was a problem hiding this comment.
docker-compose.yml is the actual Compose file in this repo (with a hyphen). The documentation currently references docker compose.yml (with a space), which will mislead users when they try to edit or open the file—please update the filename here (and keep it consistent in later sections too).
|
|
||
| ```bash | ||
| # .env | ||
| ACAS_TAG=master |
There was a problem hiding this comment.
The .env example shows ACAS_TAG=master, but the repository’s .env currently sets ACAS_TAG=latest. Please align this snippet with the actual default (or explain why users should change it to master).
| ACAS_TAG=master | |
| ACAS_TAG=latest |
Summary
Key Features
Wait Script
Based on
docker_bob_setup.sh, polls the ACAS API endpoint to verify all services are ready:Since the ACAS container waits for the Roo service during startup, checking the ACAS API endpoint confirms that all backend services are ready.
Documentation Sections
Related PRs
🤖 Generated with Claude Code