Prerequisites
Before you run anything, let’s make sure you have what you need. Good news: the list is short. Refract runs entirely in Docker — no Node.js, no pnpm, no runtime installs on your machine. If Docker is running, you’re 90% of the way there.What you need
| Requirement | Purpose | Required |
|---|---|---|
| Docker Desktop | Runs the entire stack via Compose | Yes |
| Git | Clone and update the repo | Yes |
| Stripe account (test mode) | Payment processing — test API keys go in .env.development | Yes |
| Railway account | Deployment | Only if deploying |
| GitHub username | Repo access after purchase | Yes |
A note on Stripe
Refract ships with a real Stripe integration — not a mock, not optional. Local dev uses Stripe test keys so you’re never charged real money, but you do need a Stripe account to get those keys (that’s what the checklist below is for).make stripe-login is not a prerequisite like Docker or Git. You don’t run it in Step 1 before you’ve cloned the repo. The Stripe CLI runs inside Docker (see the stripe service in Compose). Before any containers start, the Makefile runs check-stripe-auth. The first time you run make start or make fresh-start, if the CLI isn’t authenticated yet, the command stops with a message telling you to run make stripe-login — then you retry. Same flow when auth expires (~90 days). That’s intentional: you discover it at first start, not as a separate “install CLI on your laptop” step.
Not sure where to get your Stripe test keys? Log into dashboard.stripe.com, switch to Test mode (toggle top right), then go to Developers → API keys. Copy the Secret key — you’ll need it in Step 3.
Checklist
Before moving on, make sure you have all of these:- Docker Desktop installed and running
- Git installed
- GitHub username ready
- Stripe test account created
- Stripe test API keys copied and ready to paste
If Docker Desktop isn’t running when you hit
make fresh-start in Step 4, you’ll get a confusing error. Save yourself the detour — open Docker Desktop now and make sure it shows “Running” in the status bar.That’s everything. No homebrew rabbit holes, no version conflicts, no “which Python are you on?” moments. Just Docker and a Stripe account. → Next: Step 2 — Installation