Raypx

This guide walks you through cloning the repository, configuring environment variables, and starting the development server.

Prerequisites

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

Requirement	Minimum Version	Check Command
Node.js	22+	`node --version`
pnpm	10.33+	`pnpm --version`
PostgreSQL	14+	`psql --version`
Git	2.30+	`git --version`

pnpm 10.33.0 is the version pinned in package.json. If you use a different version, run corepack enable first to let Corepack manage it automatically.

Setup

Clone the Repository

git clone https://github.com/raypx/raypx-tanstack.git
cd raypx-tanstack

Configure Environment Variables

Copy the example environment file and fill in the required values:

cp .env.example .env

Open .env and set these three required variables:

# A random string for application-level encryption
APP_KEY=your-random-string-here

# PostgreSQL connection string
DATABASE_URL=postgres://user:password@localhost:5432/raypx

# Better Auth secret (minimum 32 characters)
AUTH_SECRET=at-least-32-characters-long-random-string

AUTH_SECRET must be at least 32 characters. Generate one with openssl rand -base64 48.

Install Dependencies

pnpm install

This installs dependencies for the root application and all 11 internal packages. Turborepo handles the workspace linking automatically.

Push the Database Schema

pnpm run db:push

This runs Drizzle Kit's push command to create all tables in your PostgreSQL database. It reads the schema from packages/database/src/schema/ and applies it directly — no migration files needed for local development.

Start the Development Server

pnpm dev

The Vite dev server starts on http://localhost:3001. Open that URL in your browser.

Verify Everything Works

The landing page should load with the Raypx home screen.
Click Sign In to test the authentication flow.
Navigate to /docs to view the documentation site.
Hit /api/health to confirm the API is responding.

Troubleshooting

PostgreSQL Connection Errors

If db:push fails with connection refused, verify your DATABASE_URL and that PostgreSQL is running:

# Check if PostgreSQL is running (macOS Homebrew)
brew services list | grep postgresql

# Test the connection directly
psql $DATABASE_URL -c "SELECT 1"

Missing Environment Variables

If the server starts but authentication or database features fail, double-check that APP_KEY, DATABASE_URL, and AUTH_SECRET are set in .env. The application logs validation errors from @raypx/env on startup.

Port Already in Use

The default dev port is 3001. If it is occupied, Vite will auto-increment to 3002, 3003, and so on. Check the terminal output for the actual URL.

# Find and kill the process using port 3001
lsof -ti:3001 | xargs kill

Next Steps

Project Structure — understand the repository layout.
Architecture Overview — learn the design decisions behind Raypx.
Internal Packages — explore the 11 monorepo packages.

Quick Start