Installation Guide

This guide covers the technical prerequisites and detailed setup steps for running Ryva. This is intended for users who want to understand the platform requirements or self-host Ryva.

Most users don’t need this guide! If you’re signing up for hosted Ryva, see the Quickstart Guide instead.

System Requirements

Minimum Requirements

Node.js: 20.0.0 or higher (25.1.0+ recommended)
pnpm: 9.0.0 or higher (10.20.0+ recommended)
Go: 1.25.3 or higher
PostgreSQL: 14.0 or higher
Docker & Docker Compose: Latest stable version
Operating System: Linux, macOS, or Windows with WSL2

Optional Tools

Air: Go hot reload tool for development
pre-commit: Framework for managing git hooks
Make: For running build commands

Technology Stack Overview

Frontend

Core Framework

Next.js 16: App Router with React Server Components
React 19: Latest React with compiler optimizations
TypeScript 5.9: Strict type checking enabled

Styling & UI

Tailwind CSS v4: Utility-first styling
Radix UI: Accessible component primitives
Lucide Icons: Modern icon library
next-themes: Dark mode support

State Management

TanStack Query: Server state and data synchronization
Zustand: Client state management
React Hook Form: Form state and validation

Integrations

Supabase: Authentication and database
Stripe: Payment processing
Sentry: Error tracking
hCaptcha: Bot protection

Backend

Core

Go 1.25: High-performance backend
Chi Router: Lightweight HTTP router
PostgreSQL: Primary database

Architecture

Clean architecture pattern
Handler → Service → Repository layers
Context-based request handling
Comprehensive error handling

Installation Methods

Method 1: Automated Setup (Recommended)

The fastest way to get Ryva running locally:

Clone the Repository

git clone https://github.com/egeuysall/ryva.git
cd ryva

Run Automated Setup

make setup-dev-auto

This command will:

Verify all prerequisites
Check project structure integrity
Create .env files from examples
Install dependencies (frontend + backend)
Set up git hooks (pre-commit, pre-push, commit-msg)

Configure Environment Variables

Update the generated .env files with your credentials:

/.env - Root environment variables
/apps/web/.env - Frontend configuration
/apps/api/.env - Backend configuration

You’ll need to add your Supabase and Stripe API keys for full functionality.

Start Development Servers

make dev

This starts both frontend and backend with hot reload enabled.

Method 2: Manual Setup

For more control over the installation process:

Install Prerequisites

Install required tools:

# Install Air for Go hot reload
go install github.com/cosmtrek/air@latest

# Install pre-commit framework
pip install pre-commit
# OR on macOS:
brew install pre-commit

Clone Repository

git clone https://github.com/egeuysall/ryva.git
cd ryva

Install Dependencies

make install

This installs dependencies for both frontend and backend.

Set Up Git Hooks

make pre-commit-install

Configures commit message validation and code quality checks.

Configure Environment

Create environment files:

cp .env.example .env
cp apps/web/.env.example apps/web/.env
cp apps/api/.env.example apps/api/.env

Edit each file with your configuration values.

Start Development

make dev

Database migrations run automatically on API startup.

Environment Configuration

Required Environment Variables

Frontend (`apps/web/.env`)

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8080

# Stripe Configuration
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key

# hCaptcha
NEXT_PUBLIC_HCAPTCHA_SITE_KEY=your_hcaptcha_site_key

# Analytics (Optional)
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn

Backend (`apps/api/.env`)

# Database
DATABASE_URL=postgres://user:password@localhost:5432/ryva

# Server
PORT=8080
ENVIRONMENT=development

# Authentication
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
JWT_SECRET=your_jwt_secret

# Stripe
STRIPE_SECRET_KEY=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

# Email (for notifications)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your_email@example.com
SMTP_PASSWORD=your_email_password
SMTP_FROM=noreply@ryva.app

# Sentry (Optional)
SENTRY_DSN=your_sentry_dsn

Docker Setup

Ryva includes Docker support for both local development and production deployment.

Local Development with Docker

Start Containers

docker compose -f docker-compose.local.yml up -d

This starts:

PostgreSQL database
Frontend (Next.js)
Backend (Go API)
Caddy reverse proxy

Access Services

Frontend: http://localhost:3000
API: http://localhost:8080
Via Caddy: http://localhost

View Logs

docker compose -f docker-compose.local.yml logs -f

Production Deployment

Build Images

make docker-build

Start Production Stack

docker compose up -d

Uses pre-built images from GitHub Container Registry.

Monitor Services

docker compose ps
docker compose logs -f

Database Setup

Migrations

Database migrations run automatically when the API server starts. No manual intervention needed!

Creating New Migrations

If you need to create a new migration:

make db-create-migration name=add_your_feature

This creates timestamped .up.sql and .down.sql files in apps/api/db/migrations/.

Verification

Test Your Installation

Check Frontend

Visit http://localhost:3000You should see the Ryva landing page.

Check API Health

curl http://localhost:8080/health

Should return a healthy status response.

Run Tests

make test

Runs test suites for both frontend and backend.

Available Commands

Primary Commands

# Start both servers with hot reload
make dev

# Start only frontend
make dev-web

# Start only backend
make dev-api

Troubleshooting

Common Issues

Port Already in Use

If ports 3000 or 8080 are already in use:

# Find process using port
lsof -i :3000
lsof -i :8080

# Kill process
kill -9 <PID>

Or change the port in your .env files.

Database Connection Failed

Verify your DATABASE_URL is correct and PostgreSQL is running:

# Check if PostgreSQL is running
pg_isready

# Test connection
psql $DATABASE_URL

Migration Errors

If migrations fail to run:

Check database connection
Verify migration files are valid SQL
Check migration table: SELECT * FROM schema_migrations;
Manually roll back if needed

Module Not Found Errors

Clear caches and reinstall:

# Frontend
cd apps/web
rm -rf node_modules .next
pnpm install

# Backend
cd apps/api
go clean -modcache
go mod download

Production Considerations

Security

Use strong, unique secrets for all environment variables
Enable SSL/TLS certificates (Caddy handles this automatically)
Configure rate limiting via Caddy
Set up Sentry for error tracking
Regular security updates

Performance

Enable Redis for caching (optional)
Configure CDN for static assets
Use connection pooling for database
Monitor with health check endpoints
Set up log aggregation

Scaling

Use managed PostgreSQL (Supabase recommended)
Deploy API instances behind load balancer
Use containerized deployments (Docker/Kubernetes)
Configure auto-scaling based on metrics

Next Steps

Start Using Ryva

Follow the quickstart guide to create your first workspace

Development Guide

Learn about contributing and development workflows

For hosted Ryva users, all infrastructure is managed for you. Simply sign up and start using the platform!

Get Started

Core Features

Guides

Architecture

Documentation Index

​Installation Guide

​System Requirements

​Minimum Requirements

​Optional Tools

​Technology Stack Overview

​Frontend

Core Framework

Styling & UI

State Management

Integrations

​Backend

Core

Architecture

​Installation Methods

​Method 1: Automated Setup (Recommended)

​Method 2: Manual Setup

​Environment Configuration

​Required Environment Variables

​Frontend (apps/web/.env)

​Backend (apps/api/.env)

​Docker Setup

​Local Development with Docker

​Production Deployment

​Database Setup

​Migrations

​Creating New Migrations

​Verification

​Test Your Installation

​Available Commands

​Primary Commands

​Troubleshooting

​Common Issues

​Production Considerations

​Security

​Performance

​Scaling

​Next Steps

Start Using Ryva

Development Guide

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Minimum Requirements

Optional Tools

Technology Stack Overview

Frontend

Backend

Installation Methods

Method 1: Automated Setup (Recommended)

Method 2: Manual Setup

Environment Configuration

Required Environment Variables

Frontend (`apps/web/.env`)

Backend (`apps/api/.env`)

Docker Setup

Local Development with Docker

Production Deployment

Database Setup

Migrations

Creating New Migrations

Verification

Test Your Installation

Available Commands

Primary Commands

Troubleshooting

Common Issues

Production Considerations

Security

Performance

Scaling

Next Steps