First Run
This is the moment everything comes together. One command, and Refract builds, migrates, seeds, and starts the entire stack. Go make a coffee — it’ll be ready when you get back.The command
- Builds or rebuilds all Docker images
- Starts PostgreSQL, Redis, and supporting tooling (including Bull Board for BullMQ)
- Runs the migrator container — workspace builds, migrations, then seeds — before anything else starts
- Starts the backend (GraphQL on port 3000) and consumer after migrations succeed
- Starts the frontend on port 4000 after the backend is healthy
- Starts the Stripe CLI forwarding webhooks to the backend
- Starts Dozzle and Bull Board for local observability
make start does the same thing without the --force-recreate and --build flags — use it for subsequent starts once you’ve already built the images. Use make fresh-start any time you want a clean slate.About Stripe CLI auth
Billing is backed by Stripe in every environment — it’s not optional.make stripe-login is not a Step 1 prerequisite (like installing Docker). The Stripe CLI runs in Docker; you do not install it on your host.
Before Compose starts, make start and make fresh-start both run check-stripe-auth (see Makefile). If the CLI inside the container isn’t logged in, the command exits with a message — that’s how you know to run make stripe-login. Complete the browser flow, then run make start or make fresh-start again (or every ~90 days when credentials expire).
What you should see
Queues: The default stack uses BullMQ on Redis. Bull Board (port 3998) shows your jobs. If you adopt SQS later, follow SQS — Localstack and SQS Admin are not in the default Compose file. Once everything is running, these URLs should all be reachable:| Service | URL | What it is |
|---|---|---|
| Frontend | http://localhost:4000 | Landing page and admin |
| Backend / GraphQL | http://localhost:3000 | Express + GraphQL |
| Admin | http://localhost:4000/admin | After signing in |
| Dozzle | http://localhost:8080 | Live Docker logs |
| Bull Board | http://localhost:3998 | Redis / BullMQ UI — details |
Verification checklist
Run through these before moving on — they’ll catch 90% of configuration issues:- Landing page loads at http://localhost:4000
- You can sign up and reach
/adminwith an organization - The default Free plan appears after seeding
- No failing containers in
docker compose ps - Dozzle shows backend logs without repeating crash loops
Common issues
If something isn’t right, here’s where to look first:make fresh-start fails immediately
→ Check that .env.development exists at the repo root. The check-env step requires it.
Stripe login message appears
→ Run make stripe-login, complete the browser flow, then re-run make fresh-start.
Port conflict errors
→ Something else on your machine is using port 4000, 3000, 5432, or 6379. Stop the conflicting service or change the host port in compose.yml.
Docker errors before any container starts
→ Docker Desktop isn’t running. Open it, wait for the “Running” status, then try again.
Backend crash loop in Dozzle
→ Usually a missing or incorrect value in .env.development. Check your Stripe keys, Postgres credentials, and PGHOST=rds.
Still stuck?
If you’ve tried everything and you’re still stuck — reach out in the Refract Discord (access is included with your subscription). Post your error and either I or a fellow Refract builder will help you get unstuck. See Support for Discord channels, bug reporting, and direct contact.More commands
Need to stop the stack, run migrations manually, or install a new dependency? See the full list in Make Commands.The stack is running. Now let’s take a look around. → Next: Step 5 — Explore