Skip to main content

​
Self-host EaseLMS

This guide will walk you through setting up EaseLMS on your own infrastructure. You’ll have complete control over your data, users, and platform customization.
Don’t want to manage infrastructure? Check out our hosted service for a fully managed solution.

​
Prerequisites

Before you begin, ensure you have the following:

Node.js 18.0+

Download from nodejs.org

npm 10.0+

Included with Node.js installation

Supabase account

Sign up at supabase.com (free tier available)

Git

For cloning the repository
Optional services:
  • AWS account - For S3 file storage (optional for development)
  • SendGrid account - For email notifications
  • Stripe account - For accepting payments globally
  • Flutterwave account - For African market payments

​
Installation steps

1

Clone the repository

Clone the EaseLMS repository from GitHub:
git clone https://github.com/enyojoo/easelms.git
cd easelms
2

Install dependencies

Install all required packages using npm:
npm install
EaseLMS is a monorepo built with Turborepo. This command installs dependencies for both the LMS app and the marketing website.
3

Set up environment variables

Create a .env.local file in the apps/lms/ directory:
cd apps/lms
touch .env.local
Add the following environment variables:
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
Keep your .env.local file secure and never commit it to version control. It contains sensitive credentials.
4

Create a Supabase project

Set up your Supabase database:
  1. Go to supabase.com and sign in
  2. Click “New Project”
  3. Choose your organization
  4. Enter project details:
    • Name - Your project name (e.g., “easelms-production”)
    • Database Password - Strong password for database access
    • Region - Choose the closest region to your users
  5. Click “Create new project” and wait ~2 minutes for provisioning
Supabase free tier includes 500MB database storage, 1GB file storage, and 2GB bandwidth - perfect for getting started.
5

Get Supabase credentials

Retrieve your Supabase API credentials:
  1. Navigate to Project Settings → API
  2. Copy the following values:
    • Project URL → NEXT_PUBLIC_SUPABASE_URL
    • anon/public key → NEXT_PUBLIC_SUPABASE_ANON_KEY
    • service_role secret key → SUPABASE_SERVICE_ROLE_KEY
  3. Update your .env.local file with these values
The service_role key has full admin access to your database. Keep it secure and never expose it in client-side code.
6

Run the database migration

Set up your database schema:
  1. In your Supabase project, go to SQL Editor
  2. Click New Query
  3. Open the migration file at apps/lms/supabase/migrations/database_setup.sql
  4. Copy the entire file contents
  5. Paste into the SQL Editor
  6. Click Run (or press Cmd/Ctrl + Enter)
  7. Wait for “Success. No rows returned” confirmation
This migration creates all necessary tables:
  • profiles - User profiles linked to Supabase Auth
  • courses - Course information and settings
  • lessons - Individual lessons within courses
  • enrollments - Student course enrollments
  • progress - Lesson completion tracking
  • payments - Payment records and receipts
  • certificates - Generated course certificates
  • instructors - Instructor profiles
  • resources - Downloadable course materials
  • quiz_questions - Quiz questions and answers
  • quiz_settings - Quiz configuration
  • quiz_attempts - Student quiz attempts
  • quiz_results - Quiz scores and results
  • course_instructors - Links courses to instructors
  • course_prerequisites - Course dependencies
  • lesson_resources - Links lessons to resources
  • platform_settings - Global platform configuration
7

Verify the database setup

Confirm your tables were created successfully:
  1. Go to Table Editor in Supabase
  2. You should see all 17 tables listed
  3. Click on any table to view its structure
The migration also creates triggers for automatically updating timestamps and creating user profiles on signup.
8

Start the development server

From the root directory, start the development server:
npm run dev
This starts both applications:
cd apps/lms
npm run dev
9

Access the application

Open your browser and navigate to http://localhost:3000.You’ll be redirected to /auth/learner/login - the learner login page.

​
Create your first admin user

After installation, you need to create an admin account to access the admin dashboard.
1

Sign up through the UI

  1. Navigate to http://localhost:3000
  2. You’ll be redirected to the login page
  3. Click “Sign Up” to create a new account
  4. Fill in your details and submit
2

Promote user to admin

By default, new users are created with the “user” (learner) role. To make your account an admin:
  1. Go to your Supabase project → Table Editor
  2. Open the profiles table
  3. Find your user record by email
  4. Change the user_type from user to admin
  5. Save the changes
3

Access the admin dashboard

  1. Log out and log back in
  2. Navigate to /admin to access the admin dashboard
  3. You’ll now have access to:
    • User management
    • Course creation and editing
    • Analytics and reports
    • Payment management
    • Platform settings
Only grant admin access to trusted users. Admins have full control over the platform including user data, courses, and payments.

​
Configure platform branding

Customize your EaseLMS instance with your own branding.
1

Navigate to brand settings

As an admin, go to Settings → Brand in the admin dashboard.
2

Update platform information

Configure your platform details:Basic information:
  • Platform name - Your LMS name (appears in sidebar, emails)
  • Platform description - Brief description for metadata
  • Contact email - Support email shown to users
  • App URL - Your domain (used in emails and links)
Visual branding:
  • Logo (light mode) - Logo for light theme
  • Logo (dark mode) - Logo for dark theme
  • Favicon - Browser tab icon
SEO metadata:
  • SEO title - Browser title and search engine display
  • SEO description - Meta description for search engines
  • SEO keywords - Comma-separated keywords
  • SEO image - Social media preview image
3

Upload assets

Upload your brand assets:
  1. Click the upload button for each asset type
  2. Select your image file
  3. Wait for upload to AWS S3 (if configured) or Supabase Storage
  4. Preview the changes in real-time
Recommended sizes:
  • Logo: 120x40px (transparent PNG)
  • Favicon: 32x32px or 64x64px
  • SEO image: 1200x630px (JPG or PNG)
4

Save your changes

Click “Save Changes” to apply your branding across:
  • Application UI (sidebar logo)
  • Email templates (logo and platform name)
  • Browser tabs (favicon)
  • Search engines (SEO metadata)

​
Set up email notifications

Enable automated email notifications for enrollments, completions, and payments.
1

Create a SendGrid account

  1. Sign up at sendgrid.com
  2. Verify your email address
  3. Complete the SendGrid onboarding
2

Generate an API key

  1. Navigate to Settings → API Keys
  2. Click Create API Key
  3. Name it (e.g., “EaseLMS Production”)
  4. Select Full Access permissions
  5. Click Create & View
  6. Copy the API key (shown only once)
3

Configure environment variables

Add SendGrid settings to your .env.local:
SENDGRID_API_KEY=SG.xxxxxxxxxxxxx
SENDGRID_FROM_EMAIL=noreply@yourdomain.com
SENDGRID_FROM_NAME=Your Platform Name
SENDGRID_REPLY_TO=support@yourdomain.com
Use a verified sender email. SendGrid requires domain verification for production sending.
4

Verify sender identity

  1. In SendGrid, go to Settings → Sender Authentication
  2. Choose Domain Authentication (recommended) or Single Sender Verification
  3. Follow the verification steps
  4. Wait for verification to complete
5

Test email delivery

Restart your development server and test:
  1. Create a new user account
  2. Check your inbox for the welcome email
  3. Enroll in a course and verify enrollment confirmation
Emails automatically sent:
  • Welcome email (new user signup)
  • Enrollment confirmation
  • Course completion notification
  • Certificate ready notification
  • Payment confirmation/failure
  • Admin notifications (enrollments, payments, completions)

​
Configure payment gateways

Accept payments for paid courses using Stripe or Flutterwave.
1

Create a Stripe account

  1. Sign up at stripe.com
  2. Complete business verification
  3. Activate your account
2

Get API credentials

  1. Navigate to Developers → API keys
  2. Copy your Publishable key and Secret key
  3. Use test keys for development, live keys for production
3

Configure environment variables

Add to .env.local:
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxx
4

Set up webhooks

  1. In Stripe Dashboard, go to Developers → Webhooks
  2. Click Add endpoint
  3. Set URL to https://yourdomain.com/api/webhooks/stripe
  4. Select events: checkout.session.completed, checkout.session.expired
  5. Copy the webhook signing secret
  6. Add to .env.local: STRIPE_WEBHOOK_SECRET=whsec_xxxxx

​
Deploy to production

When you’re ready to deploy your EaseLMS instance:
1

Build the application

npm run build
This creates optimized production builds for both apps.
2

Choose a hosting platform

Deploy to your preferred platform:

Vercel

Easy deployment with zero config

AWS

Full control with EC2, ECS, or Amplify

DigitalOcean

Simple droplet or App Platform
3

Set production environment variables

Configure all environment variables in your hosting platform:
  • Use production Supabase credentials
  • Use live Stripe/Flutterwave keys
  • Set production AWS S3 bucket
  • Update NEXT_PUBLIC_APP_URL to your domain
4

Configure custom domain

  1. Add your custom domain to your hosting platform
  2. Configure DNS records as instructed
  3. Enable SSL/HTTPS (usually automatic)
  4. Update platform branding settings with new domain

​
Troubleshooting

Error: “Could not connect to Supabase”Solutions:
  • Verify your NEXT_PUBLIC_SUPABASE_URL is correct
  • Check that your NEXT_PUBLIC_SUPABASE_ANON_KEY is valid
  • Ensure your Supabase project is active (not paused)
  • Check Supabase service status at status.supabase.com
Error: Migration errors when running database_setup.sqlSolutions:
  • Ensure you’re running the migration in a fresh database
  • Check for syntax errors if you modified the migration
  • Run each section separately to identify the failing part
  • Check Supabase logs for detailed error messages
Error: “Failed to upload file”Solutions:
  • Verify AWS credentials are correct
  • Check S3 bucket permissions allow uploads
  • Ensure CORS is configured on your S3 bucket
  • For development, uploads will fall back to Supabase Storage if AWS is not configured
Error: Emails not being deliveredSolutions:
  • Verify SendGrid API key is valid
  • Check sender email is verified in SendGrid
  • Review SendGrid activity logs for failures
  • Check spam folder for test emails
  • Ensure SENDGRID_FROM_EMAIL matches verified sender
Error: Payment redirects failSolutions:
  • Verify Stripe/Flutterwave API keys are correct
  • Use test mode keys for development
  • Check webhook endpoints are accessible
  • Review payment gateway dashboard for errors
  • Ensure NEXT_PUBLIC_APP_URL is set correctly for redirects

​
Next steps

Create your first course

Log in as admin and start building your course content

Customize branding

Upload your logo and configure platform settings

Invite instructors

Add instructors to help create and manage courses

Deploy to production

Launch your LMS and start enrolling students

​
Get help

Need assistance with installation or configuration?

Email support

Contact us for technical support

GitHub issues

Report bugs or request features

Documentation

Read the full documentation

Hosted service

Skip setup with managed hosting