agentops icon indicating copy to clipboard operation
agentops copied to clipboard
Published 2 months ago • verified publisher icon AgentOps-AI

docs(app): 5‑Minute Quickstart for local dev (native, no Docker) + manual fallback when 'just' is missing

Open devin-ai-integration[bot] opened this issue 4 months ago • 5 comments

📥 Pull Request

📘 Description Fixed Docker Compose setup to work out-of-the-box and updated README with Docker-first quickstart guide for beginners.

Key Changes:

  • Fixed API build context: Changed compose.yaml API build context from ./api to ./ to resolve COPY deploy/jockey errors during docker compose build
  • Enabled API docs: Added API_DOMAIN: ${API_DOMAIN} to compose environment variables so Redoc UI loads by default at http://localhost:8000/redoc
  • Docker-first README: Completely rewrote app/README.md to prioritize Docker Compose as the recommended setup method, with clear 5-minute quickstart instructions
  • Comprehensive troubleshooting: Added troubleshooting notes for common Docker build issues and manual fallback commands

🧪 Testing Verified end-to-end Docker Compose workflow:

  1. Build verification: docker compose build --no-cache completes without deploy/jockey copy errors
  2. Service startup: docker compose up -d and docker compose --profile dashboard up -d start all containers successfully
  3. Endpoint verification:
    • ✅ API docs: http://localhost:8000/redoc loads correctly
    • ✅ Dashboard: http://localhost:3000 loads sign-in page

Screenshots:

  • API Redoc interface: API Docs
  • Dashboard sign-in page: Dashboard

⚠️ Review Focus Areas

  • Build context change: Verify build.context: ./ doesn't break other Dockerfile assumptions or file paths
  • Environment mapping: Confirm all required env vars are properly passed from .env → compose.yaml → containers
  • README accuracy: Check if Docker-first approach aligns with project goals and if any critical setup steps were missed
  • Placeholder credentials: The included .env uses test values suitable for local dev but not production

🔗 Links

  • Link to Devin run: https://app.devin.ai/sessions/137f33112af34bd8bc9f553351f1d1fa
  • Requested by: @areibman

⚡ Impact This change enables docker compose up -d to work immediately for new contributors, significantly reducing setup friction and making the project more accessible to beginners.

devin-ai-integration[bot] avatar Aug 21 '25 06:08 devin-ai-integration[bot]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • [ ] Disable automatic comment and CI monitoring

devin-ai-integration[bot] avatar Aug 21 '25 06:08 devin-ai-integration[bot]

Quick update — Docker-first flow now works end-to-end.

Changes in this round:

  • compose.yaml: removed dashboard volume mount that overwrote the built .next directory, causing “Could not find a production build” loops
  • Verified compose build/run again

Verification (local):

  • Commands:
    • docker compose down
    • docker compose build --no-cache
    • docker compose up -d
    • docker compose --profile dashboard up -d
    • docker compose ps; docker compose logs api --tail=200; docker compose logs dashboard --tail=200
  • Results:
    • API: up at http://localhost:8000 (Redoc available; API_DOMAIN is passed via compose)
    • Dashboard: up at http://localhost:3000 (no more .next build loop)

Open questions for reviewer:

  1. Dashboard profile: keep behind profile (current) or auto-start with base compose (remove profiles line)?
  2. Env examples: prefer adding minimal .env.example files for app/, api/, dashboard/ vs. keeping inline examples in README?

If you prefer, I can:

  • Switch dashboard to auto-start and update README accordingly
  • Add minimal example env files and reference them in README

CI is running; I’ll keep an eye on it and address anything that comes up.

devin-ai-integration[bot] avatar Sep 16 '25 04:09 devin-ai-integration[bot]

Update: Docker-first flow re-verified end-to-end ✅

What I did this round

  • Rebuilt and started via Docker Compose:
    • docker compose down
    • docker compose build --no-cache
    • docker compose up -d
    • docker compose --profile dashboard up -d
    • docker compose ps; docker compose logs api --tail=200; docker compose logs dashboard --tail=200
  • Verified locally:
    • API: http://localhost:8000 (Redoc available; API_DOMAIN passed via compose)
    • Dashboard: http://localhost:3000 (no more “Could not find a production build”)

Changes already in this PR

  • compose.yaml
    • build.context for api set to ./ so api/Dockerfile can COPY deploy/jockey
    • API_DOMAIN passed through to enable docs
    • Removed dashboard volume mount to preserve production .next build
  • app/README.md
    • Docker-first 5‑Minute Quickstart at the top with clear steps and troubleshooting
    • Explicit note about dashboard compose profile and how to auto-start it
    • Manual Docker + native local fallbacks

Mapping feedback → action → result

  • “Compose should work out of the box” → Updated build context and env → docker compose up -d now works
  • “Dashboard not starting due to missing .next” → Removed volume mount → dashboard starts reliably
  • “Beginner-friendly README, Docker first” → Rewrote quickstart, added troubleshooting → verified against a clean build

Open questions for maintainers

  1. Dashboard profile: Keep behind profile (current) or auto-start on docker compose up -d (remove profiles line)?
  2. Env examples: Add minimal .env.example files for app/, api/, dashboard/ (recommended for onboarding), or keep examples inline in README?

If you want, I can:

  • Switch dashboard to auto-start and update README accordingly
  • Add .env.example files and wire cp commands into the README

CI: Currently green. I’ll monitor and address anything that pops up.

devin-ai-integration[bot] avatar Sep 16 '25 04:09 devin-ai-integration[bot]

Maintainers — quick clarification request to finalize Docker-first onboarding:

  • Dashboard default: Keep it behind a compose profile (current) or auto-start it with docker compose up -d (remove profiles line)?
  • Env examples: Would you like minimal .env.example files added for app/, api/, and dashboard/ with placeholders and cp steps in the README, or keep examples inline in the README?
  • Any other steps you want included or simplified for the beginner path?

Current state (verified locally; CI green):

  • docker compose up -d starts API; docker compose --profile dashboard up -d starts dashboard
  • http://localhost:8000/redoc loads (API_DOMAIN passed via compose)
  • http://localhost:3000/signin loads (dashboard build volume removed to preserve production .next)

Happy to implement whichever defaults you prefer and push an update right away.

devin-ai-integration[bot] avatar Sep 16 '25 05:09 devin-ai-integration[bot]

Verification update — Docker-first run is working ✅

  • Re-ran compose:
    • docker compose up -d
    • docker compose --profile dashboard up -d
    • docker compose ps; docker compose logs api --tail=120; docker compose logs dashboard --tail=120
  • Results:
    • API: up; docs at http://localhost:8000/redoc
    • Dashboard: up at http://localhost:3000/signin

Screenshots:

  • API Redoc: API Redoc
  • Dashboard Sign-in: Dashboard

Notes:

  • Stripe env vars are not set locally (expected); API warns but serves docs.
  • Compose passes API_DOMAIN to enable docs; dashboard volume mount removed to preserve the built .next.

Open questions to finalize (happy to implement either way):

  1. Dashboard default: keep behind compose profile (current) or auto-start with docker compose up -d?
  2. Env examples: add minimal .env.example files for app/, api/, dashboard/ and reference cp commands in README, or keep inline examples only?

devin-ai-integration[bot] avatar Sep 16 '25 05:09 devin-ai-integration[bot]