Environment Variables

Ryva uses environment variables to configure both the frontend (Next.js) and backend (Go API). This guide documents all available configuration options.

Environment Files

Ryva uses three environment files:

apps/api/.env

Backend (Go API) configuration

apps/web/.env

Frontend (Next.js) configuration

.env

Docker Compose configuration (production only)

Never commit .env files to version control. Use .env.example files as templates.

Backend Configuration (apps/api/.env)

Configuration for the Go API server.

Application Settings

GO_ENV

string

required

Environment mode for the application.Values: development, production, stagingExample:

GO_ENV=production

PORT

string

required

Port number for the API server.Default: 8080Example:

PORT=8080

Database Configuration

DATABASE_URL

string

required

PostgreSQL connection string with connection pooling parameters.Format: postgresql://[user]:[password]@[host]:[port]/[database]?[params]Example:

DATABASE_URL=postgresql://postgres:password@db.project.supabase.co:5432/postgres?sslmode=require&pool_max_conns=10

For Supabase, use the connection pooling URL for better performance.

Supabase Configuration

SUPABASE_URL

string

required

Your Supabase project URL.Example:

SUPABASE_URL=https://abcdefghijklmnop.supabase.co

SUPABASE_ANON_KEY

string

required

Supabase anonymous (public) key for client-side access.Example:

SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

SUPABASE_SERVICE_ROLE_KEY

string

required

Supabase service role key for admin operations (bypasses RLS).Example:

SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Keep this secret secure! It has full database access and bypasses Row Level Security.

JWT Configuration

JWT_SECRET

string

required

Secret key for signing JWT tokens. Must be at least 32 characters.Example:

JWT_SECRET=your-super-secret-key-min-32-characters-long-please

Generate a secure secret:

openssl rand -base64 32

JWT_EXPIRY

string

required

Token expiration duration.Format: Go duration string (1h, 24h, 168h)Example:

JWT_EXPIRY=24h

CORS Configuration

ALLOWED_ORIGINS

string

required

Comma-separated list of allowed origins for CORS.Example:

# Development
ALLOWED_ORIGINS=http://localhost:3000

# Production (multiple domains)
ALLOWED_ORIGINS=https://ryva.dev,https://www.ryva.dev,https://app.ryva.dev

Email Configuration (Resend)

RESEND_API_KEY

string

Resend API key for sending transactional emails.Example:

RESEND_API_KEY=re_123456789abcdefghijklmnop

RESEND_AUDIENCE_ID

string

Resend audience ID for contact management.Example:

RESEND_AUDIENCE_ID=aud_123456789

RESEND_FROM_EMAIL

string

Email address to send from.Example:

RESEND_FROM_EMAIL=noreply@ryva.dev

RESEND_FROM_NAME

string

Display name for sent emails.Example:

RESEND_FROM_NAME=Ryva

Sentry Configuration

SENTRY_DSN

string

Sentry Data Source Name for error tracking.Example:

SENTRY_DSN=https://abc123@o123456.ingest.sentry.io/7654321

SENTRY_ENVIRONMENT

string

Environment name for Sentry error grouping.Values: development, staging, productionExample:

SENTRY_ENVIRONMENT=production

Stripe Configuration

STRIPE_SECRET_KEY

string

Stripe secret key for payment processing.Example:

# Test mode
STRIPE_SECRET_KEY=sk_test_...

# Live mode
STRIPE_SECRET_KEY=sk_live_...

Use test keys in development, live keys only in production!

STRIPE_WEBHOOK_SECRET

string

Stripe webhook signing secret for verifying webhook events.Example:

STRIPE_WEBHOOK_SECRET=whsec_...

STRIPE_PERSONAL_PRICE_ID

string

Stripe price ID for personal plan.Example:

STRIPE_PERSONAL_PRICE_ID=price_1234567890

STRIPE_TEAM_PRICE_ID

string

Stripe price ID for team plan.Example:

STRIPE_TEAM_PRICE_ID=price_0987654321

STRIPE_SUCCESS_URL

string

Redirect URL after successful payment.Example:

STRIPE_SUCCESS_URL=https://ryva.dev/billing/success

STRIPE_CANCEL_URL

string

Redirect URL after cancelled payment.Example:

STRIPE_CANCEL_URL=https://ryva.dev/billing/cancelled

Email Template Configuration

BASE_URL

string

Base URL for email template rendering and links.Example:

# Development
BASE_URL=http://localhost:3000

# Production
BASE_URL=https://ryva.dev

Complete Backend Example

# Application
GO_ENV=development
PORT=8080

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
DATABASE_URL=postgresql://postgres:password@db.project.supabase.co:5432/postgres

# JWT
JWT_SECRET=development-secret-key-min-32-chars
JWT_EXPIRY=24h

# CORS
ALLOWED_ORIGINS=http://localhost:3000

# Email (optional in dev)
RESEND_API_KEY=
RESEND_AUDIENCE_ID=
RESEND_FROM_EMAIL=dev@localhost
RESEND_FROM_NAME=Ryva Dev

# Sentry (optional)
SENTRY_DSN=
SENTRY_ENVIRONMENT=development

# Stripe (test mode)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=
STRIPE_PERSONAL_PRICE_ID=
STRIPE_TEAM_PRICE_ID=
STRIPE_SUCCESS_URL=http://localhost:3000/billing/success
STRIPE_CANCEL_URL=http://localhost:3000/billing/cancelled

# Template Base URL
BASE_URL=http://localhost:3000

Frontend Configuration (apps/web/.env)

Configuration for the Next.js application.

Supabase Configuration

NEXT_PUBLIC_SUPABASE_URL

string

required

Your Supabase project URL (publicly accessible).Example:

NEXT_PUBLIC_SUPABASE_URL=https://abcdefghijklmnop.supabase.co

NEXT_PUBLIC_SUPABASE_ANON_KEY

string

required

Supabase anonymous key (publicly accessible).Example:

NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Configuration

NEXT_PUBLIC_API_URL

string

required

Backend API URL.Example:

# Development
NEXT_PUBLIC_API_URL=http://localhost:8080

# Production
NEXT_PUBLIC_API_URL=https://api.ryva.dev

Site Configuration

NEXT_PUBLIC_SITE_URL

string

required

Public URL of your site (for SEO, OpenGraph, sitemap).Example:

NEXT_PUBLIC_SITE_URL=https://ryva.dev

Environment Mode

NODE_ENV

string

required

Node.js environment mode.Values: development, production, testExample:

NODE_ENV=production

Next.js automatically sets this based on the command (next dev vs next build).

Sentry Configuration

NEXT_PUBLIC_SENTRY_DSN

string

Sentry DSN for frontend error tracking (publicly accessible).Example:

NEXT_PUBLIC_SENTRY_DSN=https://abc@o123.ingest.sentry.io/456

SENTRY_AUTH_TOKEN

string

Sentry auth token for uploading source maps (build time only).Example:

SENTRY_AUTH_TOKEN=sntrys_your_auth_token

This is a secret token. Only use during build, never expose to client.

hCaptcha Configuration

NEXT_PUBLIC_HCAPTCHA_SITE_KEY

string

hCaptcha site key for form protection (publicly accessible).Example:

NEXT_PUBLIC_HCAPTCHA_SITE_KEY=10000000-ffff-ffff-ffff-000000000001

CMS Configuration (Sanity)

NEXT_PUBLIC_SANITY_PROJECT_ID

string

Sanity project ID for headless CMS.Example:

NEXT_PUBLIC_SANITY_PROJECT_ID=abc12345

NEXT_PUBLIC_SANITY_DATASET

string

Sanity dataset name.Example:

NEXT_PUBLIC_SANITY_DATASET=production

Stripe Configuration

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

string

Stripe publishable key (publicly accessible).Example:

# Test mode
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Live mode
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...

Complete Frontend Example

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# API
NEXT_PUBLIC_API_URL=http://localhost:8080

# Site
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Environment
NODE_ENV=development

# Sentry (optional)
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_AUTH_TOKEN=

# hCaptcha (optional)
NEXT_PUBLIC_HCAPTCHA_SITE_KEY=

# Sanity (optional)
NEXT_PUBLIC_SANITY_PROJECT_ID=
NEXT_PUBLIC_SANITY_DATASET=

# Stripe (test mode)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

Docker Compose Configuration (.env)

Used only for production Docker deployments.

GITHUB_REPOSITORY_OWNER

string

required

GitHub username or organization for GHCR images.Example:

GITHUB_REPOSITORY_OWNER=egeuysall

IMAGE_TAG

string

required

Docker image tag for backend.Example:

IMAGE_TAG=latest
# or specific version
IMAGE_TAG=v1.0.0

CADDY_IMAGE_TAG

string

required

Docker image tag for Caddy reverse proxy.Example:

CADDY_IMAGE_TAG=latest

Complete Docker Example

.env

GITHUB_REPOSITORY_OWNER=egeuysall
IMAGE_TAG=latest
CADDY_IMAGE_TAG=latest

Security Best Practices

Never commit .env files

Add to .gitignore:

.env
.env.local
.env.*.local
apps/api/.env
apps/web/.env

Use strong secrets

Generate cryptographically secure secrets:

# Generate 32-byte base64 secret
openssl rand -base64 32

# Generate 64-byte hex secret
openssl rand -hex 64

Separate environments

Use different values for development, staging, and production:

Different database instances
Different API keys
Different secrets
Test Stripe keys in dev, live keys in production

Rotate secrets regularly

Rotate JWT_SECRET periodically
Rotate API keys after team member departures
Update Stripe webhook secrets after changes

Limit access

Store production secrets in secure vault (e.g., 1Password, AWS Secrets Manager)
Use CI/CD environment variables for deployment
Never share secrets in chat or email

Environment Variable Prefix Guide

Variables with NEXT_PUBLIC_ prefix are exposed to the browser. Never use this prefix for secrets!

Prefix	Visibility	Usage
`NEXT_PUBLIC_`	Public (browser)	Client-side accessible values (API URLs, public keys)
None	Server-only	Backend secrets, private keys, database URLs

Safe for NEXT_PUBLIC_:

API URLs
Supabase URL and anon key
Stripe publishable key
Sentry DSN
Site URL

NEVER use NEXT_PUBLIC_ for:

Database URLs
Service role keys
Secret keys
API secrets
Private tokens

Troubleshooting

Environment variables not loading

Verify .env file exists in correct location
Restart development server after changes
Check for syntax errors (no spaces around =)
Ensure no trailing spaces or quotes

# Correct
PORT=8080

# Wrong
PORT = 8080
PORT="8080"

NEXT_PUBLIC_ variables not accessible

Variables with NEXT_PUBLIC_ prefix are embedded at build time:

Restart Next.js dev server
For production, rebuild:
```
cd apps/web
pnpm run build
```
Verify variable name starts with NEXT_PUBLIC_

Database connection fails

Check your DATABASE_URL:

Verify credentials are correct
Ensure SSL mode is set (?sslmode=require)
Test connection:
```
psql "$DATABASE_URL"
```
For Supabase, use connection pooling URL

CORS errors in development

Ensure ALLOWED_ORIGINS includes your frontend URL:

# Backend .env
ALLOWED_ORIGINS=http://localhost:3000

# Frontend .env
NEXT_PUBLIC_API_URL=http://localhost:8080

Next Steps

Development Setup

Set up your local development environment

Deployment Guide

Configure environment for production deployment

Database Migrations

Learn about DATABASE_URL and migrations

Documentation Index

​Environment Files

apps/api/.env

apps/web/.env

.env

​Backend Configuration (apps/api/.env)

​Application Settings

​Database Configuration

​Supabase Configuration

​JWT Configuration

​CORS Configuration

​Email Configuration (Resend)

​Sentry Configuration

​Stripe Configuration

​Email Template Configuration

​Complete Backend Example

​Frontend Configuration (apps/web/.env)

​Supabase Configuration

​API Configuration

​Site Configuration

​Environment Mode

​Sentry Configuration

​hCaptcha Configuration

​CMS Configuration (Sanity)

​Stripe Configuration

​Complete Frontend Example

​Docker Compose Configuration (.env)

​Complete Docker Example

​Security Best Practices

​Environment Variable Prefix Guide

​Troubleshooting

​Next Steps

Development Setup

Deployment Guide

Database Migrations

Environment Files

Backend Configuration (apps/api/.env)

Application Settings

Database Configuration

Supabase Configuration

JWT Configuration

CORS Configuration

Email Configuration (Resend)

Sentry Configuration

Stripe Configuration

Email Template Configuration

Complete Backend Example

Frontend Configuration (apps/web/.env)

Supabase Configuration

API Configuration

Site Configuration

Environment Mode

Sentry Configuration

hCaptcha Configuration

CMS Configuration (Sanity)

Stripe Configuration

Complete Frontend Example

Docker Compose Configuration (.env)

Complete Docker Example

Security Best Practices

Environment Variable Prefix Guide

Troubleshooting

Next Steps