Bloggrs Lab Runner (Express + Docker + Traefik)

Spin up per-session lab containers with unique URLs (via Traefik), and serve a course lesson page that calls the API to create/stop labs.

Prereqs

• Docker (and Docker Compose v2)
• Node 18+
• For Windows: use WSL2 for best results.

Quick Start (local)

1. Start Traefik (reverse proxy) and the shared labs network:

   docker compose -f traefik.compose.yml up -d

   • Traefik dashboard: http://traefik.127.0.0.1.nip.io:8080

2. Configure environment:

   cp .env.example .env
   # .env defaults should work locally

3. Install deps & start API:

   npm install
   npm start

4. Open the lesson:

   • http://localhost:4000/lesson/hello-api

5. Click Run Code:

   • API builds labs/hello-api image if missing, starts a container with labels for Traefik, and returns a URL like: http://run-<id>.127.0.0.1.nip.io

6. Click Run Tests:

   • The page will call /api/ping on the live lab URL and show pass/fail in the terminal area.

7. Click Stop Lab to stop the container.

How it works

• traefik.compose.yml runs Traefik and creates a Docker network labs.
• The Express API starts lab containers on that same network, adding Traefik labels:
  • Host(\run-.<BASE_DOMAIN>`)` → routes to the container's port 3000.
• For local dev, BASE_DOMAIN=127.0.0.1.nip.io so subdomains resolve to 127.0.0.1 automatically.

Endpoints

• POST /api/sessions → start a lab, returns { id, url }
• GET /api/sessions/:id/status → check container status
• POST /api/sessions/:id/stop → stop the container

Notes

• This MVP runs a fixed lab image (labs/hello-api). You can extend the API to:
  • accept a template or compose reference per lesson
  • mount user code volumes
  • set TTL auto-shutdown
  • record attempts in a database
• For production, put Traefik behind HTTPS (e.g., with Let's Encrypt) and use a real wildcard domain.

NEW (v2): Build labs from the page’s code

• The lesson page now POSTs your editor contents to POST /api/sessions as files.index.js.
• The API builds a per-session Docker image with your code and runs it behind Traefik.
• The live URL is returned (e.g., http://run-<id>.127.0.0.1.nip.io).
• Stop Lab removes the container and cleans up the temp build dir (and image).

v3 updates

• Run Code now explicitly shows the live URL banner (display:flex) with the returned URL.
• Added GET /api/sessions/:id/probe so the lesson can test the lab server-side (no CORS issues).
• Lab container now sends permissive CORS headers (for direct browser checks too).