---
title: Self-hosting ClassroomIO
description: Guide to self-hosting ClassroomIO on your own servers.
---

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

This guide will help you quickly self-host ClassroomIO.

![Selfhost ClassroomIO](/selfhost-classroomio.webp)

ClassroomIO is made up of the following applications:

- [apps/api](https://github.com/rotimi-best/classroomio/tree/main/apps/api) - an Express server
- [apps/dashboard](https://github.com/rotimi-best/classroomio/tree/main/apps/dashboard) - the admin dashboard + LMS
- [supabase](https://github.com/rotimi-best/classroomio/tree/main/supabase) - the database + REST API

The quickest and easiest way to deploy both the api and dashboard is by using our [Railway Template](https://railway.app/template/dl9RG7?referralCode=8OyIj5). However there are a couple of things that you'd need first before heading over to the template, which are:

1. SMTP values - For sending emails on the api
2. Supabase - For the database used on the dashboard
3. Cloudflare R2 (optional) - Video uploads on the api

## SMTP Setup

Both for the supabase and api setup, you'd need a custom SMTP for email sending. Most importantly you need these values:

```zsh title="env"
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASSWORD=
SMTP_SENDER=
```

Make sure you have them handy because you'd need them while we go through this self-hosting guide.

<Callout title="Learn More">
  Learn more about setting up a custom SMTP server
  [here](https://supabase.com/docs/guides/auth/auth-smtp)
</Callout>

## Supabase

There are 2 options to go about setting up Supabase, you could [self-host supabase](https://supabase.com/docs/guides/self-hosting) on your own servers or you could use their cloud version. We recommend you use the cloud version because it has a very generous free tier and you get to deploy it very quickly.

We have a standalone guide to help you setup your Supabase Cloud and you can find it [here](/docs/contributor-guides/supabase-cloud).

After you go through that guide you will need the following environment variables, please also store them somewhere:

```zsh title="env"
PUBLIC_SUPABASE_URL=
PUBLIC_SUPABASE_ANON_KEY=
PRIVATE_SUPABASE_SERVICE_ROLE=
```

## Cloudflare R2

We use Cloudflare R2 for video uploading within the course builder. It is not required though and you can do without it in the app if you don't need video upload.

<Callout title="Work in Progress">This section is a work in progress.</Callout>

## Deploy on Railway

Now you have everything you need and you are ready to deploy the api and dashboard.

Go ahead and click this button to get started.

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/dl9RG7?referralCode=8OyIj5)

### Environment Variables

#### cio-api

```zsh title="env"
# Required
SMTP_HOST=""
SMTP_PORT=""
SMTP_USER=""
SMTP_SENDER=""
SMTP_PASSWORD=""
PUBLIC_SUPABASE_URL=""
PUBLIC_SUPABASE_ANON_KEY=""

# Optional
CLOUDFLARE_BUCKET_ID=""
CLOUDFLARE_ACCESS_KEY=""
CLOUDFLARE_ACCOUNT_ID=""
CLOUDFLARE_BUCKET_DOMAIN=""
CLOUDFLARE_SECRET_ACCESS_KEY=""
SENTRY_DNS=""
```

<Callout title="Learn More">
  Learn more about the environment variables
  [here](https://github.com/rotimi-best/classroomio/blob/main/apps/api/.env.example)
</Callout>

#### cio-dashboard

```zsh title="env"
# Required
PUBLIC_SUPABASE_URL=""
PUBLIC_SUPABASE_ANON_KEY=""
PRIVATE_SUPABASE_SERVICE_ROLE=""
PUBLIC_SERVER_URL=""

# Optional
OPENAI_API_KEY=""
PUBLIC_IP_REGISTRY_KEY=""
UNSPLASH_API_KEY=""
PRIVATE_APP_HOST=""
PRIVATE_APP_SUBDOMAINS=""
```

<Callout title="Learn More">
  Learn more about the environment variables
  [here](https://github.com/rotimi-best/classroomio/blob/main/apps/dashboard/.env.example)
</Callout>

## Using Docker

We provide a docker-compose configuration to deploy both the api and dashboard services. Here's how to use it:

1. Clone the repository:

```zsh title="Terminal"
git clone https://github.com/rotimi-best/classroomio.git
cd classroomio
```

2. Create a `.env` file with your environment variables (see Environment Variables section above)

3. Start the services:

```zsh title="Terminal"
docker compose up --build
```

The services will be available at:

- Dashboard: http://localhost:3082
- Backend: http://localhost:3081

### Service Configuration

The docker-compose file sets up two services:

#### Backend Service

- Runs on port 3081
- Uses Node.js slim image
- Mounts the api code directory
- Requires environment variables for:
  - Supabase configuration
  - Cloudflare R2 for video uploads
  - SMTP for email notifications

#### Dashboard Service

- Runs on port 3082
- Uses Node.js Alpine image
- Uses pnpm for package management
- Requires environment variables for:
  - Supabase configuration
  - Application settings
  - Optional API keys (OpenAI, Unsplash)

Note: We're currently working on including Supabase in the docker-compose file. If you'd like to help with this, please open a PR on GitHub! 👍