Platform Setup & Configuration

This guide covers the essential setup steps required to configure and deploy the Speak English Now platform.

Prerequisites

Before setting up the platform, ensure you have:

Node.js 18+ installed
MongoDB database (local or cloud)
Google Cloud Platform account
Mercado Pago account (for payments)
GitHub/Google OAuth applications configured

Environment Variables

The platform requires multiple environment variables for proper operation.

Authentication Variables

AUTH_SECRET

string

required

NextAuth.js secret key for session encryption. Generate using:

openssl rand -base64 32

AUTH_GOOGLE_ID

string

required

Google OAuth Client ID from Google Cloud Console

AUTH_GOOGLE_SECRET

string

required

Google OAuth Client Secret from Google Cloud Console

ADMIN_EMAIL

string

required

Email address of the platform administrator. Only this email will have admin access.

GOOGLE_REDIRECT_URI

string

required

OAuth redirect URI (e.g., http://localhost:3000/api/auth/callback/google)

Implementation: src/auth.ts:15-26

Database Configuration

DATABASE_URL

string

required

MongoDB connection string. Format:

mongodb+srv://username:[email protected]/database?retryWrites=true&w=majority

Schema: prisma/schema.prisma:11-14

Google Calendar Integration

CALENDAR_ID

string

required

Google Calendar ID where classes will be scheduled (usually your email address)

CALENDAR_API_KEY

string

required

Google Calendar API key from Google Cloud Console

GOOGLE_SERVICE_ACCOUNT_JSON

string (JSON)

Service account credentials as JSON string (optional, for service account authentication)

Implementation: src/app/api/calendar/route.ts:10-11

Payment Integration (Mercado Pago)

MERCADO_PAGO_ACCESS_TOKEN

string

required

Mercado Pago private access token from your account dashboard

NEXT_PUBLIC_MERCADO_PAGO_PUBLIC_KEY

string

required

Mercado Pago public key (client-side accessible)

Implementation: src/app/api/mercado-pago/create-preference/route.ts:24

Application URLs

BASE_URL

string

required

Full base URL of your application including protocol:

Development: http://localhost:3000/
Production: https://yourdomain.com/

The BASE_URL must end with a trailing slash (/) for proper URL construction in webhook and calendar routes.

AI Integration (Optional)

OPENAI_API_KEY

string

OpenAI API key for AI-powered activity generation (if using)

Reference: src/env.ts:6

Example .env File

# Authentication
AUTH_SECRET="your-generated-secret-key-here"
AUTH_GOOGLE_ID="123456789-abc.apps.googleusercontent.com"
AUTH_GOOGLE_SECRET="GOCSPX-your-secret-here"
ADMIN_EMAIL="[email protected]"
GOOGLE_REDIRECT_URI="http://localhost:3000/api/auth/callback/google"

# Database
DATABASE_URL="mongodb+srv://user:[email protected]/speakenglishnow"

# Google Calendar
CALENDAR_ID="[email protected]"
CALENDAR_API_KEY="AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# Mercado Pago
MERCADO_PAGO_ACCESS_TOKEN="APP_USR-123456789-abcdef-xyz"
NEXT_PUBLIC_MERCADO_PAGO_PUBLIC_KEY="APP_USR-123456789-abcdef-xyz-public"

# Application
BASE_URL="http://localhost:3000/"

# Optional: OpenAI
OPENAI_API_KEY="sk-proj-..."

Database Setup

1. Initialize Prisma

Generate Prisma client:

npx prisma generate

2. Push Schema to Database

For MongoDB, push the schema:

npx prisma db push

MongoDB with Prisma doesn’t use traditional migrations. Use db push to synchronize your schema.

3. Seed Initial Data (Optional)

Create a seed script if needed:

// prisma/seed.ts
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  // Add seed data here
}

main()
  .catch((e) => {
    console.error(e)
    process.exit(1)
  })
  .finally(async () => {
    await prisma.$disconnect()
  })

OAuth Configuration

Google Cloud Console Setup

Create a Project
- Go to Google Cloud Console
- Create a new project or select existing
Enable APIs
- Enable Google Calendar API
- Enable Google+ API (for OAuth)
Create OAuth Credentials
- Navigate to “APIs & Services” > “Credentials”
- Create OAuth 2.0 Client ID
- Application type: Web application
- Authorized redirect URIs:
  http://localhost:3000/api/auth/callback/google https://yourdomain.com/api/auth/callback/google
Configure Consent Screen
- Add required scopes:
  - openid
  - email
  - profile
  - https://www.googleapis.com/auth/calendar.events
Copy Credentials
- Copy Client ID to AUTH_GOOGLE_ID
- Copy Client Secret to AUTH_GOOGLE_SECRET

The admin user must grant offline access to Google Calendar. This happens automatically on first sign-in when the refresh token is captured.

GitHub OAuth Setup (Optional)

Go to GitHub Settings > Developer settings > OAuth Apps
Create new OAuth App

Set Authorization callback URL:

http://localhost:3000/api/auth/callback/github

Copy Client ID and Client Secret to environment variables

Payment Integration Setup

See the dedicated Payment Integration guide for detailed Mercado Pago configuration.

Calendar Integration Setup

See the dedicated Calendar Setup guide for detailed Google Calendar configuration.

Application Deployment

Development

npm install
npm run dev

Access at http://localhost:3000

Production Build

npm run build
npm start

Deployment Platforms

The application can be deployed to:

Vercel (recommended for Next.js)
- Automatic deployments from Git
- Environment variables in dashboard
- Serverless functions support
Railway
- Full Node.js environment
- MongoDB hosting available
- Environment variable management
DigitalOcean App Platform
- Container-based deployment
- Database hosting
- SSL certificates included

Environment Variables in Production

Never commit .env files to version control. Use platform-specific environment variable management:

Vercel: Project Settings > Environment Variables
Railway: Project > Variables tab
DigitalOcean: App Settings > Environment Variables

Post-Deployment Checklist

After deployment, verify:

OAuth providers work (test login)
Admin email grants proper access
Database connections are stable
Google Calendar events create successfully
Mercado Pago webhooks receive notifications
SSL certificate is active (production)
Error logging is configured
Backup strategy is in place

Security Best Practices

Session Security

Sessions expire after 30 days
JWT tokens are signed with AUTH_SECRET
HTTPS required in production

API Security

All admin routes verify email match
Server actions validate user sessions
Database queries use parameterized inputs

Data Protection

User passwords managed by OAuth providers
Sensitive tokens stored server-side only
Environment variables never exposed to client

Monitoring and Logging

Recommended Tools

Error Tracking: Sentry
Performance: Vercel Analytics
Database: MongoDB Atlas monitoring
Uptime: UptimeRobot

Log Locations

Current logging is console-based. Consider implementing:

// lib/logger.ts
import winston from 'winston'

export const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' }),
  ],
})

Troubleshooting

Common Issues

“No admin access”

Verify ADMIN_EMAIL matches your OAuth email exactly
Check environment variables are loaded
Clear browser cookies and re-login

“Calendar events not creating”

Verify admin user has granted calendar permissions
Check googleRefreshToken is stored in database
Verify Calendar API is enabled in Google Cloud

“Payment webhook not receiving”

Ensure BASE_URL ends with /
Verify Mercado Pago webhook URL is correct
Check webhook URL is publicly accessible

“Database connection failed”

Verify DATABASE_URL format
Check MongoDB Atlas IP whitelist
Ensure database user has proper permissions

Payment Integration

Configure Mercado Pago payment processing

Calendar Setup

Set up Google Calendar integration

Admin Features

Configuration

Platform Setup & Configuration

Prerequisites

Environment Variables

Authentication Variables

Database Configuration

Google Calendar Integration

Payment Integration (Mercado Pago)

Application URLs

AI Integration (Optional)

Example .env File

Database Setup

1. Initialize Prisma

2. Push Schema to Database

3. Seed Initial Data (Optional)

OAuth Configuration

Google Cloud Console Setup

GitHub OAuth Setup (Optional)

Payment Integration Setup

Calendar Integration Setup

Application Deployment

Development

Production Build

Deployment Platforms

Environment Variables in Production

Post-Deployment Checklist

Security Best Practices

Session Security

API Security

Data Protection

Monitoring and Logging

Recommended Tools

Log Locations

Troubleshooting

Common Issues

Payment Integration

Calendar Setup

Build docs developers (and LLMs) love

Admin Features

Configuration

​Prerequisites

​Environment Variables

​Authentication Variables

​Database Configuration

​Google Calendar Integration

​Payment Integration (Mercado Pago)

​Application URLs

​AI Integration (Optional)

​Example .env File

​Database Setup

​1. Initialize Prisma

​2. Push Schema to Database

​3. Seed Initial Data (Optional)

​OAuth Configuration

​Google Cloud Console Setup

​GitHub OAuth Setup (Optional)

​Payment Integration Setup

​Calendar Integration Setup

​Application Deployment

​Development

​Production Build

​Deployment Platforms

​Environment Variables in Production

​Post-Deployment Checklist

​Security Best Practices

​Session Security

​API Security

​Data Protection

​Monitoring and Logging

​Recommended Tools

​Log Locations

​Troubleshooting

​Common Issues

​Related Resources

Payment Integration

Calendar Setup

Build docs developers (and LLMs) love

Prerequisites

Environment Variables

Authentication Variables

Database Configuration

Google Calendar Integration

Payment Integration (Mercado Pago)

Application URLs

AI Integration (Optional)

Example .env File

Database Setup

1. Initialize Prisma

2. Push Schema to Database

3. Seed Initial Data (Optional)

OAuth Configuration

Google Cloud Console Setup

GitHub OAuth Setup (Optional)

Payment Integration Setup

Calendar Integration Setup

Application Deployment

Development

Production Build

Deployment Platforms

Environment Variables in Production

Post-Deployment Checklist

Security Best Practices

Session Security

API Security

Data Protection

Monitoring and Logging

Recommended Tools

Log Locations

Troubleshooting

Common Issues

Related Resources