Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/egeuysall/ryva-archive/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through setting up Ryva’s development environment on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 25.1.0 or higher
  • pnpm 10.20.0 or higher
  • Go 1.25.3 or higher
  • Air (Go hot reload tool)
  • Docker and Docker Compose
  • pre-commit framework
  • Git

​
Installing Prerequisites

# Install Node.js 25.1.0+ using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 25.1.0
nvm use 25.1.0

# Install pnpm
npm install -g pnpm@10.20.0

# Verify installation
node --version
pnpm --version

# Download and install Go 1.25.3+
# Visit https://golang.org/dl/ for your platform

# Verify installation
go version

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

# Verify Air is in your PATH
air -v

# Install Docker and Docker Compose
# Visit https://docs.docker.com/get-docker/ for your platform

# Verify installation
docker --version
docker compose version

# Install pre-commit framework
pip install pre-commit

# Or using Homebrew on macOS
brew install pre-commit

# Verify installation
pre-commit --version

​
Setup Methods

Ryva offers two setup methods: automated (recommended) and manual.
1

Clone the repository

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

Run automated setup

make setup-dev
The --auto flag runs setup without prompts, which is useful for CI/CD environments.
3

What the setup script does

The automated setup will:
  • ✅ Verify all prerequisites (Node.js, Go, pnpm, Docker, etc.)
  • ✅ Check project structure integrity
  • ✅ Create .env files from examples
  • ✅ Install dependencies (frontend + backend)
  • ✅ Set up git hooks (pre-commit, pre-push, commit-msg)
  • ✅ Optionally run build verification tests
  • ✅ Provide a summary and quick reference guide
4

Configure environment variables

Edit the generated .env files with your credentials:
# Edit API environment variables
nano apps/api/.env

# Edit Web environment variables
nano apps/web/.env
See Environment Variables for detailed configuration.

​
Manual Setup

1

Clone and navigate to repository

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

Install dependencies

# Install all dependencies
make install
This installs:
  • Frontend dependencies via pnpm install in apps/web
  • Go modules via go mod download in apps/api
3

Set up git hooks

# Install pre-commit hooks
make pre-commit-install
This installs:
  • pre-commit hook for code quality checks
  • pre-push hook for validation before pushing
  • commit-msg hook for Conventional Commits enforcement
4

Create environment files

# Copy environment examples
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
You must edit these files with your actual credentials before starting the application.
5

Configure environment variables

Edit each .env file with your credentials:API Configuration (apps/api/.env):
# Required: Supabase credentials
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
DATABASE_URL=postgresql://...

# Required: Application settings
GO_ENV=development
PORT=8080
JWT_SECRET=your-secret-key
Web Configuration (apps/web/.env):
# Required: Supabase and API
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
NEXT_PUBLIC_API_URL=http://localhost:8080
See Environment Variables for complete reference.

​
Starting Development

1

Start development servers

# Start both frontend and backend with hot reload
make dev
Database migrations run automatically when the API starts.
2

Access the application

Once the servers are running, you can access:

​
Development Commands

​
Root Makefile Commands

The root Makefile provides orchestration across both frontend and backend: 
make help            # Show all available commands
make dev             # Start both servers with hot reload
make dev-web         # Start only frontend
make dev-api         # Start only backend (with Air)
make build           # Build all applications
make test            # Run all tests
make test-watch      # Run tests in watch mode
make lint            # Lint all code
make format          # Format all code
make type-check      # Run TypeScript type checking
make clean           # Clean build artifacts

​
Frontend Commands

In the apps/web directory: 
cd apps/web

pnpm run dev         # Start Next.js dev server
pnpm run build       # Build for production
pnpm run start       # Start production server
pnpm run lint        # Lint TypeScript/React
pnpm run format      # Format with Prettier
pnpm run type-check  # TypeScript type checking
pnpm test            # Run unit tests
pnpm test:watch      # Run tests in watch mode
pnpm test:ui         # Run tests with UI
pnpm test:coverage   # Run tests with coverage
pnpm test:e2e        # Run E2E tests (Playwright)

​
Backend Commands

In the apps/api directory: 
cd apps/api

make dev             # Start with Air (hot reload)
make build           # Build binary
make test            # Run all tests
make test-unit       # Unit tests only
make test-integration # Integration tests only
make test-e2e        # E2E tests only
make test-cover      # Run tests with coverage
make lint            # Run golangci-lint
make format          # Format with gofmt
make clean           # Clean build artifacts

​
Pre-commit Commands

make pre-commit-install   # Install pre-commit hooks
make pre-commit-run       # Run hooks manually
make pre-commit-update    # Update hook versions

​
Hot Reload Configuration

Ryva uses different hot reload mechanisms for frontend and backend:

​
Frontend (Next.js)

Next.js includes built-in Fast Refresh:
  • Automatically reloads on file changes
  • Preserves component state when possible
  • Shows errors in browser overlay

​
Backend (Air)

Air provides Go hot reloading with configuration in apps/api/.air.toml: 
[build]
  cmd = "go build -o ./tmp/main ./cmd/server"
  bin = "./tmp/main"
  include_ext = ["go", "tpl", "tmpl", "html", "sql"]
  exclude_dir = ["assets", "tmp", "vendor", "testdata", "node_modules", "tests"]
  delay = 1000
Key features:
  • Rebuilds on .go, .sql, and template file changes
  • 1-second delay to batch rapid changes
  • Excludes test files and vendor directories
  • Logs build errors to build-errors.log

​
Troubleshooting

If you see errors about ports 3000 or 8080 being in use:
# Find and kill process using port 3000
lsof -ti:3000 | xargs kill -9

# Find and kill process using port 8080
lsof -ti:8080 | xargs kill -9
Ensure your DATABASE_URL in apps/api/.env is correct:
# Test database connection
cd apps/api
make migrate-status
If migrations fail, verify:
  • Supabase project is active
  • Database URL includes connection pooling parameters
  • Service role key has necessary permissions
If make dev-api fails with “air: command not found”:
# Install Air
go install github.com/cosmtrek/air@latest

# Ensure GOPATH/bin is in your PATH
export PATH=$PATH:$(go env GOPATH)/bin

# Add to your shell profile for persistence
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc  # or ~/.bashrc
If pre-commit hooks are blocking commits:
# Run hooks manually to see errors
make pre-commit-run

# Fix issues automatically where possible
make format
make lint

# Update hooks if they're outdated
make pre-commit-update
If frontend dependencies fail to install:
# Clear pnpm cache
pnpm store prune

# Remove node_modules and reinstall
cd apps/web
rm -rf node_modules pnpm-lock.yaml
pnpm install

​
Next Steps

Database Migrations

Learn how to create and manage database migrations

Environment Variables

Complete reference for all configuration options

Deployment Guide

Deploy Ryva to production with Docker

Testing

Run and write tests for your code

Build docs developers (and LLMs) love

Get started for freeTalk to us