Cloud API Development

This guide is for contributors and operators who want to run the omnilux.tv cloud infrastructure locally or on their own hosted stack.

It is not required for normal self-hosted OmniLux usage.

Prerequisites

• Supabase CLI or a Supabase cloud project
• Node.js 22+
• pnpm

Supabase project creation

Option 1: Supabase Cloud

1. Create a project at supabase.com
2. Note your project URL and API keys from Settings > API
3. These values go into your environment variables

Option 2: Self-hosted Supabase

supabase init
supabase start

This starts a local Supabase stack (PostgreSQL, GoTrue, PostgREST, etc.) on your machine.

Database schema

Run migrations to set up the cloud database schema:

supabase db push

Or apply migrations manually:

supabase migration up

The cloud database (Supabase/PostgreSQL) is separate from the server's local SQLite database. The cloud database handles:

• User accounts and authentication for omnilux.tv
• Claimed server relationships
• Subscription and billing state
• Invites and cloud-linked account data
• Analytics and other public platform services

Authentication configuration

Configure Supabase Auth:

1. Go to Authentication > Providers in the Supabase dashboard
2. Enable Email/Password authentication
3. Optionally enable OAuth providers (GitHub, Google, etc.)
4. Configure email templates for verification, password reset, etc.

Environment variables

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs...

# For local development
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=<local-anon-key>
SUPABASE_SERVICE_ROLE_KEY=<local-service-role-key>

The anon key is safe to expose in the browser (it uses Row Level Security). The service role key must never be exposed — it bypasses RLS.

Row Level Security (RLS)

All tables have RLS policies. Key rules:

• Users can only read their own data
• Service role key bypasses RLS (used server-side only)
• Subscription data is readable by the owning user
• Admin tables are restricted to service role access

Testing the setup

# Verify connection
curl https://your-project.supabase.co/rest/v1/ \
  -H "apikey: your-anon-key"

A successful response confirms the API is accessible.