Self-host LMS Bridge

1What you'll be running

LMS Bridge is fully containerized. The production stack is four small services that come up ready to use — migrations and an idempotent seed run automatically on first boot.

2Prerequisites

• A host with Docker. Any Linux VM (institutional or cloud) with Docker Engine and the Compose plugin. 2 vCPU / 2 GB RAM is plenty for a pilot.
• A public HTTPS domain — only if you'll launch it from a real LMS. An LMS will not launch a tool over http:// or localhost. For local preview alone, you can skip this.
• An AI API key (optional). Anthropic, OpenAI, or Azure OpenAI — or run a local OpenAI-compatible model. You can also start in mock mode to explore the product with no key and no cost.

3Quick start (Docker)

Option A — Prebuilt images (fastest)

Download just the compose file and an example env, fill it in, and start:

# 1. Get the production compose file and an example env
curl -fsSLO https://raw.githubusercontent.com/hjmacemail/lmsbridge/main/docker-compose.prod.yml
curl -fsSL  https://raw.githubusercontent.com/hjmacemail/lmsbridge/main/.env.example -o .env

# 2. Edit .env — set SECRET_KEY, your AI provider + key, and public URLs (see below)
nano .env

# 3. Start the stack
docker compose -f docker-compose.prod.yml up -d

That's it. The frontend comes up on :8080, the backend API on :8000, the marketing site on :8090, and Postgres on a named volume. Pin a release with IMAGE_TAG=v1.0.0 in .env (defaults to :latest).

Option B — Build from source

git clone https://github.com/hjmacemail/lmsbridge.git
cd lmsbridge
cp .env.example .env        # then edit .env
docker compose up --build -d

Verify it's healthy

curl http://localhost:8000/api/v1/health     # backend
# then open http://localhost:8080 in a browser

The seed creates demo accounts so you can log in immediately; disable it for production by dropping the seed --if-empty step from the backend command (see the deployment guide).

4Configure your environment

Everything is driven by .env. The variables you'll almost always set:

5Put HTTPS in front

An LMS requires public HTTPS, so terminate TLS with a reverse proxy in front of the frontend (:8080) and backend (:8000). Caddy is the shortest path — it gets a certificate automatically:

# Caddyfile
lms-bridge.your-university.edu {
    handle /api/* {
        reverse_proxy localhost:8000
    }
    handle {
        reverse_proxy localhost:8080
    }
}

nginx, Traefik, or your cloud load balancer work equally well. After TLS is live, set TOOL_BASE_URL, FRONTEND_BASE_URL, and CORS_ORIGINS to that https:// domain and restart the backend.

6Register it in your LMS

Self-hosting runs the tool; LMS Bridge then launches inside your LMS as an LTI 1.3 tool. Once it's on a public HTTPS domain, fetch your ready-made registration URLs:

curl https://lms-bridge.your-university.edu/api/v1/lti/config

Then add the tool in Canvas, Moodle, Brightspace, or Blackboard using those URLs (many platforms support one-click Dynamic Registration). Full per-LMS steps are in the Install guide and the downloadable per-LMS PDFs.

7Choose your AI model

LMS Bridge is provider-agnostic and bring-your-own-key, so the AI runs on infrastructure you approve:

• Anthropic / OpenAI — set LLM_PROVIDER and the matching API key.
• Azure OpenAI — keeps traffic inside your Azure tenant; set the endpoint, deployment, and key.
• Local / on-prem model — any OpenAI-compatible endpoint works, so nothing has to leave your network.
• No key yet? Start in mock mode to explore the full product with zero cost, then switch later.

You only pay your provider for the tokens you use — there's no per-student LMS Bridge fee. Set a spend cap in your provider's console to stay in control.

8Updates & backups

Update to a new version

# Prebuilt images
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

# From source
git pull && docker compose up --build -d

Database migrations run automatically on backend startup, so updates are safe to apply in place. Your data persists in the postgres-data volume across restarts and upgrades.

Back up your data

docker compose exec db pg_dump -U lmsbridge lmsbridge > backup-$(date +%F).sql

9Other deploy options

Prefer managed hosting or Kubernetes? The same stack deploys anywhere containers run. The repo includes ready-made blueprints:

• Render — one-click Blueprint from render.yaml.
• Railway — deploy from GitHub with the Postgres plugin.
• Fly.io — fly launch with the provided infra/fly.backend.toml.
• Kubernetes — run backend + frontend as Deployments behind an Ingress with TLS; probe GET /api/v1/health.

Step-by-step instructions for each live in the full Deployment Guide in the repository.