January 1, 2025

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)

Using DevContainer (Recommended)

If you're using VS Code or GitHub Codespaces, you can set up your development environment with just one click using DevContainer.

DevContainer Features

  • One-click setup: Dependencies, databases, and SSL certificates are all automatically configured
  • Multi-database: PostgreSQL, MariaDB, and Dragonfly are ready to use out of the box
  • HTTPS enabled: Local SSL certificates are automatically generated with mkcert
  • AI development support: Claude Code comes pre-installed

Setup Steps

  1. Install the Dev Containers extension in VS Code
  2. Clone the repository: git clone https://github.com/Love-rox/rox.git
  3. Open the folder in VS Code
  4. Select "Reopen in Container" (or press F1 → Dev Containers: Reopen in Container)
  5. The initial setup will run automatically (takes about 5-10 minutes)

Once setup is complete, start development with:

bun run dev

Tip: HTTPS is enabled inside DevContainer, so you can access it via https://localhost.

Manual Installation

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:

  • URL: Your instance's public URL (e.g., https://your-domain.com)
  • DATABASE_URL: Your database connection string
  • STORAGE_TYPE: Choose between local or s3

4. Start Development Services

Start PostgreSQL and Dragonfly using Docker Compose (for development only):

docker compose up -d

Wait for services to be healthy:

docker compose ps

Note: Docker is used here for development database services. For production deployments, we recommend bare metal installation for better performance and control.

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:

Next Steps

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

Update History

Date Changes
2025-12-12 Added DevContainer section