🚀 Complete Setup Guide - Next.js + FastAPI SaaS Template

Deploy your complete SaaS application to Railway in minutes with full feature configuration.

🎯 What You Get

✅ Next.js 14 Frontend with App Router
✅ FastAPI Backend with async/await
✅ PostgreSQL Database with migrations
✅ Multi-tenant Organization system
✅ Authentication with JWT + OAuth
✅ Billing with Stripe integration
✅ Security with reCAPTCHA v3
✅ Email notifications
✅ File uploads with AWS S3
✅ Analytics with Google Analytics
✅ Monitoring with Sentry

⚡ Quick Start (5 Minutes)

1. Deploy Template

Click "Deploy Now" above
Connect your GitHub account
Choose repository name
Click "Deploy"

2. Core Configuration (Required)

Only these variables are required for basic functionality:

Backend Service:

SECRET_KEY="${{secret(32)}}"              # ✅ Auto-generated
DATABASE_URL="${{Postgres.DATABASE_URL}}" # ✅ Auto-configured
ALLOWED_ORIGINS="https://${{frontend.RAILWAY_STATIC_URL}}" # ✅ Auto-configured

Frontend Service:

NODE_ENV="production"                                    # ✅ Pre-configured
NEXT_PUBLIC_API_URL="https://${{backend.RAILWAY_STATIC_URL}}" # ✅ Auto-configured

3. Test Your Application

Frontend: https://your-frontend.railway.app
Backend API: https://your-backend.railway.app/docs
Health Check: https://your-backend.railway.app/health

🎉 Your SaaS is now live with basic functionality!

🔧 Feature Configuration (Optional)

Enable additional features by configuring external services:

🔐 Authentication & Security

Google OAuth (Optional)

Enable social login with Google.

Setup:

Go to Google Cloud Console
Create new project or select existing
Enable Google+ API
Go to Credentials → Create Credentials → OAuth 2.0 Client IDs
Set Authorized redirect URIs:
- https://your-frontend.railway.app/auth/callback/google
Copy Client ID and Secret

Backend Variables:

GOOGLE_CLIENT_ID="123456789-abcdefghijk.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="GOCSPX-your-secret-here"

Frontend Variables:

NEXT_PUBLIC_GOOGLE_CLIENT_ID="123456789-abcdefghijk.apps.googleusercontent.com"
NEXT_PUBLIC_ENABLE_OAUTH="true"

reCAPTCHA v3 (Recommended)

Protect against bots and spam.

Setup:

Go to Google reCAPTCHA Console
Click "+" to create new site
Choose reCAPTCHA v3
Add domains: your-frontend.railway.app
Copy Site Key and Secret Key

Backend Variables:

RECAPTCHA_ENABLED="true"
RECAPTCHA_SITE_KEY="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
RECAPTCHA_SECRET_KEY="6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe"
RECAPTCHA_THRESHOLD="0.5"

Frontend Variables:

NEXT_PUBLIC_RECAPTCHA_ENABLED="true"
NEXT_PUBLIC_RECAPTCHA_SITE_KEY="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"

💳 Billing & Payments

Stripe Integration

Enable subscription billing and payments.

Setup:

Create Stripe Account
Go to Developers → API Keys
Copy Publishable Key and Secret Key
Go to Developers → Webhooks
Add endpoint: https://your-backend.railway.app/webhooks/stripe
Select events: customer.*, invoice.*, subscription.*
Copy Webhook Secret

Backend Variables:

STRIPE_SECRET_KEY="sk_live_51ABCDEFghijklmnop..."
STRIPE_WEBHOOK_SECRET="whsec_1ABCDEFghijklmnop..."

Frontend Variables:

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_51ABCDEFghijklmnop..."
NEXT_PUBLIC_ENABLE_BILLING="true"

Test Mode: Use sk_test_ and pk_test_ keys for development.

📧 Email Notifications

SendGrid (Recommended)

Send transactional emails (welcome, password reset, etc.).

Setup:

Create SendGrid Account
Go to Settings → API Keys
Create new API key with Full Access
Verify sender email in Settings → Sender Authentication

Backend Variables:

EMAIL_ENABLED="true"
SMTP_HOST="smtp.sendgrid.net"
SMTP_PORT="587"
SMTP_USER="apikey"
SMTP_PASSWORD="SG.your-api-key-here"
EMAIL_FROM="noreply@yourdomain.com"
EMAIL_VERIFICATION_REQUIRED="true"

Alternative: Gmail SMTP

Setup:

Enable 2-factor authentication on Gmail
Generate App Password: Account → Security → App passwords
Use app password as SMTP password

Backend Variables:

EMAIL_ENABLED="true"
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"
EMAIL_FROM="your-email@gmail.com"

📁 File Storage

AWS S3

Store user uploads and files.

Setup:

Create AWS Account
Go to S3 → Create Bucket
Set bucket name and region
Go to IAM → Users → Add User
Attach policy: AmazonS3FullAccess
Copy Access Key ID and Secret

Backend Variables:

AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
AWS_S3_BUCKET="your-bucket-name"
AWS_REGION="us-east-1"

📊 Analytics & Monitoring

Google Analytics 4

Track user behavior and conversions.

Setup:

Go to Google Analytics
Create new GA4 Property
Add Web Stream with your domain
Copy Measurement ID (starts with G-)

Frontend Variables:

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID="G-XXXXXXXXXX"
NEXT_PUBLIC_ENABLE_ANALYTICS="true"

Hotjar (Optional)

User session recordings and heatmaps.

Setup:

Create Hotjar Account
Add new site with your domain
Copy Site ID

Frontend Variables:

NEXT_PUBLIC_HOTJAR_ID="1234567"

Sentry

Error tracking and performance monitoring.

Setup:

Create Sentry Account
Create new project (React + Python)
Copy DSN from project settings

Backend Variables:

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

Frontend Variables:

NEXT_PUBLIC_SENTRY_DSN="https://abc123@o123456.ingest.sentry.io/123456"

💬 Chat & Support (Optional)

Enable these if you plan to add chat functionality later.

Frontend Variables:

NEXT_PUBLIC_ENABLE_CHAT="false"  # Set to "true" when ready

🌍 Localization

Frontend Variables:

NEXT_PUBLIC_DEFAULT_LOCALE="en-US"           # or "pt-BR"
NEXT_PUBLIC_SUPPORTED_LOCALES="en-US,pt-BR"  # Add more as needed

🛠️ Advanced Configuration

Subscription Plans

Customize your billing plans:

Backend Variables:

BILLING_PLANS="BASIC,PRO,EXPERT"
PLAN_BASIC_NAME="Basic"
PLAN_BASIC_PRICE="0"
PLAN_BASIC_FEATURES="user_management,basic_dashboard"
PLAN_PRO_NAME="Professional"
PLAN_PRO_PRICE="2900"  # $29.00 in cents
PLAN_PRO_FEATURES="user_management,basic_dashboard,advanced_reports"
PLAN_EXPERT_NAME="Expert"
PLAN_EXPERT_PRICE="4900"  # $49.00 in cents
PLAN_EXPERT_FEATURES="user_management,basic_dashboard,advanced_reports,analytics,priority_support"

Security Settings

Backend Variables:

JWT_ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES="15"
REFRESH_TOKEN_EXPIRE_DAYS="7"

Application Info

Backend Variables:

APP_NAME="Your SaaS Name"
APP_VERSION="1.0.0"
ENVIRONMENT="production"
DEBUG="false"

Frontend Variables:

NEXT_PUBLIC_APP_NAME="Your SaaS Name"
NEXT_PUBLIC_APP_VERSION="1.0.0"
NEXT_PUBLIC_ENVIRONMENT="production"

🔍 Testing Your Configuration

Health Check

Visit: https://your-backend.railway.app/health

Should show:

{
  "status": "healthy",
  "timestamp": "2025-01-XX...",
  "services": {
    "database": "connected",
    "redis": "connected",
    "email": "configured",
    "stripe": "configured",
    "recaptcha": "enabled"
  }
}

Authentication Test

Go to your frontend: https://your-frontend.railway.app
Try to register a new account
Check email for verification (if enabled)
Test login functionality

API Documentation

Visit: https://your-backend.railway.app/docs

Interactive Swagger UI
Test all endpoints
View request/response schemas

🚨 Troubleshooting

Common Issues

❌ 405 Method Not Allowed

Problem: Frontend getting 405 on /api/auth/login Solution: Check NEXT_PUBLIC_API_URL points to backend URL:

NEXT_PUBLIC_API_URL="https://your-backend.railway.app"  # ✅ Correct
NEXT_PUBLIC_API_URL="https://your-frontend.railway.app" # ❌ Wrong

❌ Database Connection Error

Problem: Backend can't connect to database Solution: Verify DATABASE_URL is set correctly:

DATABASE_URL="${{Postgres.DATABASE_URL}}"  # ✅ Auto-configured by Railway

❌ Email Not Sending

Problem: Password reset emails not working Solution: Check email configuration:

EMAIL_ENABLED="true"
SMTP_HOST="smtp.sendgrid.net"
SMTP_USER="apikey"
SMTP_PASSWORD="SG.your-actual-api-key"
EMAIL_FROM="noreply@yourdomain.com"

❌ Stripe Webhooks Failing

Problem: Subscription updates not working Solution:

Check webhook URL: https://your-backend.railway.app/webhooks/stripe
Verify webhook secret matches: STRIPE_WEBHOOK_SECRET="whsec_..."
Ensure selected events include: customer.*, subscription.*

❌ OAuth Login Not Working

Problem: Google login redirects fail Solution: Update authorized redirect URIs:

https://your-frontend.railway.app/auth/callback/google

📚 Next Steps

1. Custom Domain (Optional)

Go to Railway project → Settings → Domains
Add your custom domain
Update DNS records as shown
Update all OAuth redirect URIs to use new domain

2. Environment Variables

Development: Use test keys (Stripe test mode, etc.)
Production: Use live keys with proper security

3. Monitoring Setup

Enable Sentry for error tracking
Set up Google Analytics for user insights
Configure Hotjar for user experience analysis

4. Content & Branding

Update APP_NAME and NEXT_PUBLIC_APP_NAME
Customize email templates
Add your logo and branding

✅ Configuration Checklist

Essential (Required for basic functionality)

SECRET_KEY (auto-generated)
DATABASE_URL (auto-configured)
NEXT_PUBLIC_API_URL (auto-configured)

Authentication

Google OAuth keys
reCAPTCHA keys (recommended)

Billing

Stripe keys (if billing enabled)
Webhook endpoint configured

Email

SMTP configuration (SendGrid/Gmail)
Sender email verified

Storage

AWS S3 credentials (if file uploads needed)

Analytics

Google Analytics ID
Sentry DSN (recommended)

🆘 Support

Documentation: Check project README.md
Issues: Create GitHub issue in your deployed repository
Community: Railway Discord server
Updates: Watch repository for template updates

🚀 Ready to launch your SaaS? Your application is now fully configured and production-ready!

Template Version: 2025.1 | Last Updated: January 2025