Getting Started with Rox

Welcome to Rox! This guide will help you set up and run Rox on your local machine.

Prerequisites

Before you begin, make sure you have the following installed:

• Bun >= 1.0.0
• Docker and Docker Compose
• PostgreSQL >= 14 (or MySQL >= 8.0, or SQLite)

Installation Steps

1. Clone the Repository

git clone https://github.com/Love-rox/rox.git
cd rox

2. Install Dependencies

bun install

3. Setup Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Edit .env with your configuration. Key variables include:

• DATABASE_URL: Your database connection string
• STORAGE_TYPE: Choose between local or s3
• JWT_SECRET: Secret key for JWT tokens

4. Start Development Services

Start PostgreSQL and Dragonfly using Docker Compose:

docker compose up -d

Wait for services to be healthy:

docker compose ps

5. Run Database Migrations

Generate and run database migrations:

bun run db:generate
bun run db:migrate

6. Start Development Servers

Start both backend and frontend:

bun run dev

Or start them individually:

# Backend only
bun run backend:dev

# Frontend only
bun run frontend:dev

The services will be available at:

• Backend API: http://localhost:3000
• Frontend: http://localhost:3001

Next Steps

• Read the Architecture Guide to understand how Rox works
• Check out the Deployment Guide for production setup
• Join our community on GitHub

Troubleshooting

Database Connection Issues

If you encounter database connection errors, make sure:

• Docker services are running (docker compose ps)
• Database credentials in .env match your setup
• PostgreSQL port (5432) is not already in use

Port Conflicts

If ports 3000 or 3001 are already in use, you can change them in:

• Backend: packages/backend/.env → PORT
• Frontend: packages/frontend/waku.config.ts → port