Local Development Setup
Step-by-step guide to clone, install, and run Reloop services locally.
Welcome to the local development setup guide for Reloop. Reloop is a high-performance, type-safe email and campaign automation platform designed as a modern monorepo.
This document provides a clear, sequential path for both developers and automated agents to set up and run all services in a local environment.
Prerequisites
Before starting, ensure that you have the following installed on your machine:
- Bun: The fast all-in-one JavaScript runtime (v1.3.0+) → Install Bun
- Docker & Docker Compose: To run PostgreSQL, Redis, ClickHouse, etc. → Install Docker Desktop
- Git: For cloning the repository
Interactive Walkthrough
Follow these steps sequentially to set up and run the Reloop monorepo in your local environment.
Please perform all steps in the exact order listed below to prevent database connectivity errors and routing issues.
Clone and Install Dependencies
First, verify that your local environment has Bun v1.3.0+ installed:
bun --version
Next, clone the repository and install all node modules from the root directory:
git clone git@github.com:reloop-labs/reloop.git
cd reloop
bun install
Configure Local Domain (Hosts File)
Reloop uses a unified local domain (local.reloop.sh) and a Caddy reverse proxy to manage session cookies and authentication seamlessly across all microservices. To enable this, you must map local.reloop.sh to your loopback address (127.0.0.1).
echo "127.0.0.1 local.reloop.sh" | sudo tee -a /etc/hosts
Add-Content -Path $env:windir\System32\drivers\etc\hosts -Value "127.0.0.1`tlocal.reloop.sh"
Modifying your hosts file requires administrator or root privileges. You may be prompted to input your system password.
Start Docker Infrastructure
Reloop relies on several high-performance backing services. Ensure Docker is running on your machine, then spin up the complete infrastructure suite:
bun docker:up
This boots the following services in the background:
- PostgreSQL (
5432): Core database for transactional data and auth. - Redis (
6379): Cache store, background workers, and session management. - ClickHouse (
8123): High-speed analytics and logs database. - Caddy (
80/443): Auto-SSL gateway and reverse-proxy routing. - Grafana & Loki (
3000/3100): Log aggregation and service dashboards.
Caddy, Postgres, and Redis bind to their standard ports on your host. If you have existing local instances of PostgreSQL (5432), Redis (6379), or web servers (Nginx/Apache on 80 or 443) running directly on your host machine, you must stop them before starting the Docker container suite.
Initialize the Database
Before running migrations, wait 5–10 seconds after starting Docker to ensure PostgreSQL is fully healthy and accepting connections.
Then, apply the database schema (via Drizzle ORM) and seed the initial/default workspace metadata directly from the root directory:
# Push the schema changes directly to your local database
bun db:push
# Populate the database with default workspace and seed data
bun db:seed
You can inspect your local database tables visually at any time:
bun db:studio
Configure Environment Variables
Reloop microservices seek .env files within their respective subdirectories. We provide two ways to configure them:
# Automatically generates all service .env files from their .env.dev templates in 1 click
bun env:setup
If you prefer to copy them manually, duplicate the .env.dev templates to .env in the target directories. For example, for the Auth Service:
cp apps/backend/auth/.env.dev apps/backend/auth/.env
Start Reloop Services
Run the development servers concurrently using Turborepo from the root directory:
bun dev
If you only wish to work on frontend or backend subsystems, you can run them separately:
bun frontend:dev
bun backend:dev
Once running, your entire secure Reloop portal is unified and accessible at https://local.reloop.sh!
Service URLs and Ports Reference
Once your development servers are running, they are accessible through the unified gateway domain or via their direct localhost ports.
Unified Domain Routing (Recommended)
Thanks to the Caddy reverse proxy, you can access the entire unified platform securely under a single local domain (https://local.reloop.sh). This is the recommended entrypoint as it manages cookie sharing and CORS seamlessly:
| Route Path | Destination | Target Port | Description |
|---|---|---|---|
| https://local.reloop.sh/ | Web App | 3000 | Main public marketing pages & landing site |
| https://local.reloop.sh/dashboard | User Dashboard | 3001 | Core workspace, campaigns, and user dashboard app |
| https://local.reloop.sh/docs | Public Docs | 3003 | This developer/public documentation portal |
| https://local.reloop.sh/api/auth | Auth API | 8000 | User auth, sessions, Better Auth handler |
| https://local.reloop.sh/api/... | Microservice APIs | 8011 - 8023 | Dynamic routes to individual backend APIs |
Direct Frontend Applications
If you need to access frontend applications directly without the Caddy proxy:
| Application | Direct URL | Port | Description |
|---|---|---|---|
| Web App | http://localhost:3000 | 3000 | Marketing website and public content |
| User Dashboard | http://localhost:3001 | 3001 | Main client app (workspaces, lists, campaigns) |
| Public Docs | http://localhost:3003 | 3003 | This developer/public documentation portal |
Direct Backend API Services
Backend microservices receive API requests from the frontend via the Caddy proxy at https://local.reloop.sh/api/.... However, you can also query them directly at their raw localhost ports:
| Service Name | Caddy Route | Raw Port | Description |
|---|---|---|---|
| Auth API | /api/auth | 8000 | Better Auth handlers and user management |
| Domain API | /api/domain | 8011 | Custom domain delegation & DKIM verification |
| API Key API | /api/api-key | 8012 | External and internal API key provisioning |
| Webhook API | /api/webhook | 8013 | Webhook ingress and dispatching handlers |
| Contacts API | /api/contacts | 8014 | Recipient groups, segments, and contact listings |
| Mailing API | /api/mail | 8015 | Campaign engine, SMTP queues, and sending pipeline |
| Logs API | /api/logs | 8016 | Event logger and ClickHouse query service |
| Workflow API | /api/workflow | 8017 | Automation workflows and state engines |
| Upload API | /api/upload | 8018 | File upload storage manager and CDN endpoints |
| Template API | /api/template | 8019 | Visual email builder & templates repository |
| Kumomta API | /api/kumomta | 8021 | Kumomta mail server synchronization hook |
| Email API | /api/email | 8022 | Direct transactional email handler |
| Billing API | /api/billing | 8023 | Stripe subscriptions and billing integration |
Backing Infrastructure Services
These supporting systems are hosted inside Docker containers and run as your backend services' dependencies:
| Service | Port | Description |
|---|---|---|
| PostgreSQL | 5432 | Primary relational database |
| Redis | 6379 | Cache and BullMQ background task queue |
| ClickHouse | 8123 | High-volume analytical tracking database |
| NATS | 4222 | Core messaging bus / pub-sub broker |
| Loki | 3100 | Log aggregation engine |
| Grafana | 3000 (Direct) | Infrastructure metrics dashboards |
Quick Developer Cheat Sheet
Keep these core monorepo commands handy for routine tasks:
| Command | Action | Scope |
|---|---|---|
bun run check | Run code quality checks, lints, and format checks | Full Monorepo |
bun env:setup | Automatically populate all backend microservice .env files | Environments |
bun db:push | Synchronize current schema changes to PostgreSQL | Database |
bun db:seed | Re-seed the local database with default data | Database |
bun docker:down | Stop and tear down all docker containers | Infrastructure |
bun run --filter=<package-name> <script> | Run a package script specifically | Target Package |
Next Steps
Now that your base local environment is running, explore the specialized setup instructions: