Getting started

Complete guide for deploying Roost on your own infrastructure.

Prerequisites

• Node.js 22+ and npm
• A Supabase project (Cloud or self-hosted)
• S3-compatible storage (AWS S3, MinIO, or Cloudflare R2)
• SMTP or a configured transactional email adapter for account confirmation and password resets
• (Optional) Redis for caching and rate limiting
• (Optional) Stripe account for paid memberships

Quick Start

1. Clone and Install

git clone https://github.com/msrbuilds/roost.git
cd roost
bash install.sh

The interactive installer will guide you through configuring:

• Community name and branding
• Database provider (Supabase Cloud or Supabase Self-hosted)
• Deployment target (Docker VPS, Dockploy VPS, Vercel, Netlify, or Local)
• Required file storage and account email, plus optional Redis and Stripe

2. Set Up the Database

Supabase (Recommended)

1. Create a project at supabase.com (or use self-hosted Supabase)
2. Go to SQL Editor in your Supabase dashboard
3. Copy the entire contents of schema.sql and paste it into the SQL Editor
4. Click Run — this creates the application tables, functions, triggers, and security policies

3. Create First Admin User

1. Start the app: npm run dev:all
2. Sign up via the app at http://localhost:5000/signup
3. Go to your Supabase dashboard → SQL Editor
4. Run:

   SELECT setup_first_admin('[email protected]');

   (Use the email you signed up with)
5. Refresh the app — you now have full superadmin access

Note: The setup_first_admin function is a one-time bootstrap helper. It automatically deletes itself after promoting the first superadmin, so it cannot be misused. After this, manage roles from the Admin panel in the app.

Do NOT use the Supabase Table Editor to change roles directly — a database trigger blocks role changes unless done via service role (SQL Editor) or by a superadmin through the app.

4. Start the App

# Development
npm run dev:all

# Production (Docker)
docker compose up --build -d

Deployment Options

Docker (Recommended for Self-Hosting)

# Run the installer to generate .env.local, server/.env, and Compose's .env.
# Compose loads .env; the two development files alone are not sufficient.
# Then build and run:
docker compose up --build -d

# View logs
docker compose logs -f

# Update
docker compose down
docker compose up --build -d

The Docker setup includes:

• Frontend served by nginx with gzip, caching, and security headers
• Backend with health checks and graceful shutdown
• Built-in Traefik reverse proxy with automatic Let’s Encrypt SSL
• Optional Redis and MinIO profiles (when configured by installer)

Detailed VPS guides:

• Docker (VPS)
• Dockploy (VPS)

Vercel + VPS

Deploy frontend to Vercel, backend to a VPS or Railway:

# Frontend
vercel deploy

# Backend (on VPS)
cd server && npm run build && npm start

Netlify + VPS

Deploy frontend to Netlify, backend separately:

# Frontend
netlify deploy --prod

# Backend (on VPS)
cd server && npm run build && npm start

Stripe Setup (Paid Memberships)

1. Create a Stripe account at stripe.com
2. Create a Product and Price in the Stripe Dashboard
3. Configure the Customer Portal in Stripe settings
4. Add webhook endpoint: https://your-domain.com/api/webhooks/stripe
   • Events to listen for:
     • checkout.session.completed
     • customer.subscription.created
     • customer.subscription.updated
     • customer.subscription.deleted
     • invoice.payment_failed
     • invoice.payment_succeeded
5. Set environment variables:

   # Frontend (.env.local)
   VITE_STRIPE_ENABLED=true
   
   # Backend (server/.env)
   STRIPE_SECRET_KEY=sk_live_...
   STRIPE_WEBHOOK_SECRET=whsec_...
   STRIPE_PRICE_ID=price_...

Testing Stripe Locally

# Install Stripe CLI
stripe login

# Forward webhooks to local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# Use the webhook signing secret from the CLI output

S3 Storage Setup

AWS S3

1. Create an S3 bucket with public read access for uploads
2. Create an IAM user with S3 access
3. Set environment variables:

   AWS_REGION=us-east-1
   AWS_S3_BUCKET=your-bucket
   AWS_ACCESS_KEY_ID=AKIA...
   AWS_SECRET_ACCESS_KEY=...

MinIO (Self-Hosted S3)

If you deploy with Docker (VPS) and choose S3-Compatible -> Self-host MinIO on this VPS, the installer configures MinIO automatically in Docker Compose.

For manual/local MinIO setup, you can still run:

# Run MinIO
docker run -d -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD=password \
  minio/minio server /data --console-address ":9001"

Set S3_ENDPOINT=http://localhost:9000 in your backend .env.

Cloudflare R2

Use R2 with S3-compatible API. Set S3_ENDPOINT to your R2 endpoint.

Environment Variables Reference

Frontend (.env.local)

*Required for Supabase providers

Backend (server/.env)

Feature Flags

All features can be toggled via environment variables:

Updating

# Pull latest changes
git pull

# Rebuild
npm run build:all

# Docker
docker compose up --build -d

# Review schema changes before upgrading an existing database.
# schema.sql is the consolidated fresh-install schema, not an in-place migration.