diff --git a/site/README.md b/site/README.md
new file mode 100644
index 0000000..2650c30
--- /dev/null
+++ b/site/README.md
@@ -0,0 +1,7 @@
+# Course website
+
+Astro Starlight site built from the lessons in `course/`.
+
+Run locally: `npm ci && npm run dev` (from this directory), then open http://localhost:4321.
+
+`COURSE_HOST` (e.g. `course.example.com`) sets the public site URL at build time. Unset, the site uses `http://localhost:4321`. Deploys must set it; see `../deploy/README.md`.
diff --git a/site/astro.config.mjs b/site/astro.config.mjs
index 93160f8..ba9c484 100644
--- a/site/astro.config.mjs
+++ b/site/astro.config.mjs
@@ -1,14 +1,13 @@
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 
-// The site is served at the root of its own subdomain. COURSE_HOST is required at build
-// time (e.g. COURSE_HOST=course.example.com); there is deliberately no default, so a
-// deploy can never ship with a placeholder URL.
+// The site is served at the root of its own subdomain. Set COURSE_HOST at build time
+// (e.g. COURSE_HOST=course.example.com). Unset means a local run (http://localhost:4321);
+// deploys must not rely on this: deploy/Dockerfile and docker-compose.yml require COURSE_HOST.
 const host = process.env.COURSE_HOST;
-if (!host) throw new Error("COURSE_HOST is not set (e.g. COURSE_HOST=course.example.com)");
 
 export default defineConfig({
-  site: `https://${host}`,
+  site: host ? `https://${host}` : "http://localhost:4321",
   base: "/",
   integrations: [
     starlight({