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

[devin-ai-integration]

📥 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:
• Dashboard sign-in page:

⚠️ 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]

🤖 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

[areibman]

Removing my approval

[areibman]

Removing my approval

[areibman]

Removing my approval

[areibman]

Removing my approval

[areibman]

Removing my previous approval

[areibman]

Removing my previous approval

[areibman]

Removing my previous approval

[areibman]

Removing my previous approval

[areibman]

.

[areibman]

test

[areibman]

test

[areibman]

f

[devin-ai-integration]

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]

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.

[areibman]

test

[devin-ai-integration]

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.

[areibman]

test2

[devin-ai-integration]

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:
• Dashboard Sign-in:

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?