Abdulmuizz HamzatandRotimi Best
b599f1a017
* Update documentation for ClassroomIO: change Fumadocs to Blume, revise MDX format conventions, and clarify sidebar navigation requirements. * docs: update README and scripts for improved preview and error handling * docs: update Discord link in configuration and documentation * docs: add token-auth route and update documentation formatting * Fix formatting in auto-comment-issues.yml * Fix JSON syntax by adding a comma * fix(docs): declare Blume's Astro build deps so Cloudflare build resolves them blume build generates an Astro project under apps/docs/.blume/ that imports astro, @astrojs/mdx, @tailwindcss/vite, tailwindcss, @tailwindcss/typography, @shikijs/twoslash and @scalar/astro. Under pnpm's isolated node_modules these are nested inside blume and not resolvable from the docs app, so a clean --frozen-lockfile build (Cloudflare) fails at 'Cannot find module astro/config'. Declare them directly in @cio/docs, pinned to blume's resolved versions. * refactor(docs): update API reference paths and documentation for clarity * fix: change platofrm url to docs home page * Refactor documentation for self-hosting ClassroomIO - Removed the Supabase Cloud setup guide as it is no longer needed. - Updated the Enterprise SSO documentation to include a reference link for SSO & licensing. - Added new documentation for Content Security Policy (CSP) configuration. - Created a new section for configuring SMTP for email notifications. - Introduced a comprehensive configuration index for self-hosted ClassroomIO, detailing environment variables and their usage. - Added documentation for optional integrations including Google OAuth, OpenAI, and Unsplash. - Documented the generation and usage of required secrets for ClassroomIO. - Created a section for SSO & licensing, detailing the requirements for Enterprise features. - Added object storage configuration documentation, covering both bundled MinIO and external S3-compatible services. - Documented versioning and upgrade processes for ClassroomIO. - Updated the Coolify and Docker self-hosting guides to streamline configuration references and upgrade instructions. - Enhanced the Railway self-hosting guide with links to relevant configuration sections. - Updated token authentication documentation to reference SSO & licensing. * Add comprehensive guides for ClassroomIO features and functionalities - Introduced a new guide for the Student Dashboard, detailing navigation and features available to students. - Added a guide on using Tags for organizing and filtering courses within ClassroomIO. - Created a guide on how to take attendance in courses, including marking attendance and related functionalities. - Developed a Terminology guide to clarify key terms used throughout ClassroomIO. - Implemented a Token Auth guide for signing users into ClassroomIO from external applications using JWT. - Added instructions for using math in the editor with LaTeX support. - Created a guide for customizing the welcome email sent to students upon enrollment in courses. - Added a guide explaining what ClassroomIO is and its key features. - Updated the home documentation to provide a clearer overview of ClassroomIO and its resources. - Enhanced self-hosted configuration documentation with a new guide for deploying ClassroomIO on Dokploy. - Updated links in the self-hosted configuration documentation for better navigation. - Added new images to support the Dokploy deployment guide. - Updated asset packaging script to handle redirects for the new guide structure. - Fixed footer link to point to the correct Getting Started guide. * chore: uprage version * feat(docs): add DigitalOcean deployment guide and flatten guides structure - Add a guide for deploying ClassroomIO on DigitalOcean using Docker Compose and Caddy for automatic HTTPS. - List DigitalOcean as a deployment option in the self-hosting index. - Move guides out of content/docs/guides into content/docs (student-dashboard, tags, terminology, token-auth, what-is-classroomio, audience, cohorts, community, course, enterprise-sso, mcp, organization, quickstart/*). - Rename home.mdx to index.mdx. - Update package-assets script to emit redirects for the old guides paths. --------- Co-authored-by: Rotimi Best <best@classroomio.com>
181 lines
6.5 KiB
Plaintext
181 lines
6.5 KiB
Plaintext
---
|
|
title: Docker
|
|
description: Self-host ClassroomIO with Docker — pull pre-built images (recommended) or build from source.
|
|
---
|
|
|
|
Docker is one way to self-host ClassroomIO. There are two paths:
|
|
|
|
- **Run from pre-built images (recommended)** — pull the published `classroomio/{api,dashboard,jobs}` images. You only need one compose file and a `.env`; no repository clone and no heavy local build.
|
|
- **Build from source** — clone the repo and build the images yourself (needs ~8 GB RAM for the dashboard build).
|
|
|
|
|
|
|
|
## Run from Pre-built Images (recommended)
|
|
|
|
### Prerequisites
|
|
|
|
- Docker installed and running.
|
|
|
|
### Steps
|
|
|
|
1. Download the pull-based compose file and an env template:
|
|
|
|
```zsh title="Terminal"
|
|
curl -O https://raw.githubusercontent.com/classroomio/classroomio/main/docker-compose.images.yaml
|
|
curl -o .env https://raw.githubusercontent.com/classroomio/classroomio/main/.env.example
|
|
```
|
|
|
|
2. Edit `.env`. At minimum set `CIO_VERSION` (pin a release), `DASHBOARD_ORIGIN`, the auth secrets, and SMTP:
|
|
|
|
```zsh title=".env"
|
|
CIO_VERSION=1.0.0 # pin a release (not "latest") so upgrades are deliberate
|
|
DASHBOARD_ORIGIN=https://app.yourdomain.com
|
|
BETTER_AUTH_SECRET=<openssl rand -hex 32>
|
|
PRIVATE_SERVER_KEY=<openssl rand -hex 32> # must be identical in the api and dashboard
|
|
POSTGRES_PASSWORD=<strong password>
|
|
# Email (required for signup/reset/invites)
|
|
SMTP_HOST=
|
|
SMTP_PORT=
|
|
SMTP_USER=
|
|
SMTP_PASSWORD=
|
|
SMTP_SENDER=
|
|
```
|
|
|
|
:::danger[Set strong secrets — the stack won't start without them]
|
|
This path does **not** run `run-docker-full-stack.sh`, so secrets are not auto-generated. You must set
|
|
`BETTER_AUTH_SECRET` and `PRIVATE_SERVER_KEY` yourself, or the compose file fails fast. See
|
|
[Configuration → Environment & secrets](/self-hosted/configuration/secrets).
|
|
:::
|
|
|
|
3. Pull and start the stack (MinIO is included via the `minio` profile):
|
|
|
|
```zsh title="Terminal"
|
|
docker compose -f docker-compose.images.yaml --env-file .env --profile minio pull
|
|
docker compose -f docker-compose.images.yaml --env-file .env --profile minio up -d
|
|
```
|
|
|
|
4. Verify:
|
|
|
|
```zsh title="Terminal"
|
|
curl -sS http://localhost:3081/ # API — returns JSON
|
|
curl -I http://localhost:3082/ # Dashboard — returns 200
|
|
```
|
|
|
|
- Dashboard: http://localhost:3082
|
|
- API: http://localhost:3081
|
|
- MinIO Console: http://localhost:9001 (log in with `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` from your `.env`)
|
|
|
|
## Build from Source
|
|
|
|
Use this if you want to build the images locally (e.g. to run code changes).
|
|
|
|
### Prerequisites
|
|
|
|
- Docker Desktop installed and running
|
|
- `git` installed
|
|
- ~8 GB RAM available for the dashboard build
|
|
|
|
### Steps
|
|
|
|
1. Clone the repository:
|
|
|
|
```zsh title="Terminal"
|
|
git clone https://github.com/classroomio/classroomio.git
|
|
cd classroomio
|
|
```
|
|
|
|
2. Copy the env template and edit it:
|
|
|
|
```zsh title="Terminal"
|
|
cp .env.example .env
|
|
```
|
|
|
|
Open `.env` and set `DASHBOARD_ORIGIN` for your domain. For local development the defaults work as-is — the startup script generates `BETTER_AUTH_SECRET` and `PRIVATE_SERVER_KEY` when they are missing, and randomizes the MinIO credentials.
|
|
|
|
3. Build and start the full stack:
|
|
|
|
```zsh title="Terminal"
|
|
./run-docker-full-stack.sh --build
|
|
```
|
|
|
|
The script builds and starts Postgres, Redis, MinIO (object storage), the API, the dashboard, and the background **jobs** worker.
|
|
|
|
:::note[Default is pull, not build]
|
|
Run without `--build` and the script **pulls** the published `classroomio/*` images at the
|
|
`CIO_VERSION` in your `.env` instead of building locally — that's the faster default path.
|
|
:::
|
|
|
|
## One `.env`, One Command
|
|
|
|
Docker self-hosting uses a single root `.env` file. Every `docker compose` command reads it via `--env-file .env` — you never need separate env files per service. See [`.env.example`](https://github.com/classroomio/classroomio/blob/main/.env.example) for the full template.
|
|
|
|
## Configuration
|
|
|
|
Every variable the stack reads is documented once in the shared
|
|
[Configuration](/self-hosted/configuration) section — set the ones you need in your root `.env`:
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Environment & secrets" href="/self-hosted/configuration/secrets" icon="key-round">
|
|
`BETTER_AUTH_SECRET`, `PRIVATE_SERVER_KEY`, database, and mode/routing basics.
|
|
</Card>
|
|
<Card title="Email (SMTP)" href="/self-hosted/configuration/email" icon="mail">
|
|
SMTP for signup verification, password resets, and invites.
|
|
</Card>
|
|
<Card title="Object storage & uploads" href="/self-hosted/configuration/storage" icon="hard-drive">
|
|
MinIO or external S3/R2, plus upload size limits.
|
|
</Card>
|
|
<Card title="CSP / allowed domains" href="/self-hosted/configuration/csp" icon="shield">
|
|
Allowed external CDN, font, and media domains.
|
|
</Card>
|
|
<Card title="Integrations" href="/self-hosted/configuration/integrations" icon="plug">
|
|
Google OAuth, Unsplash, OpenAI, branding.
|
|
</Card>
|
|
<Card title="SSO & licensing" href="/self-hosted/configuration/sso" icon="id-card">
|
|
`LICENSE_KEY` for Enterprise features.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## Upgrading
|
|
|
|
ClassroomIO publishes versioned images and `CIO_VERSION` controls which tag you run. To upgrade the
|
|
pre-built images path, bump `CIO_VERSION` and re-pull:
|
|
|
|
```zsh title="Terminal"
|
|
docker compose -f docker-compose.images.yaml --env-file .env --profile minio pull
|
|
docker compose -f docker-compose.images.yaml --env-file .env --profile minio up -d
|
|
```
|
|
|
|
For the build-from-source path, `git pull` and re-run `./run-docker-full-stack.sh --build`. See
|
|
[Configuration → Versions & upgrades](/self-hosted/configuration/versions) for pinning, rollback, and
|
|
the pre-upgrade backup steps.
|
|
|
|
## Common Commands
|
|
|
|
```zsh title="Terminal"
|
|
# Start the full stack (pulls pre-built images by default)
|
|
./run-docker-full-stack.sh
|
|
|
|
# Build from source instead of pulling
|
|
./run-docker-full-stack.sh --build
|
|
|
|
# Start without MinIO (requires an external S3-compatible store)
|
|
./run-docker-full-stack.sh --no-minio
|
|
```
|
|
|
|
See [docker/docs/SELF_HOST.md](https://github.com/classroomio/classroomio/blob/main/docker/docs/SELF_HOST.md) for the full Docker reference including troubleshooting.
|
|
|
|
## Troubleshooting: "No space left on device"
|
|
|
|
```zsh title="Terminal"
|
|
docker system df # check usage
|
|
docker builder prune -f # free build cache
|
|
docker image prune -a -f # free unused images
|
|
docker container prune -f # free stopped containers
|
|
```
|
|
|
|
:::warning[Volume prune deletes data]
|
|
Avoid `docker volume prune` after `docker compose ... down` — it can remove your database and storage volumes.
|
|
:::
|
|
|
|
Then restart: `./run-docker-full-stack.sh`
|