🛠 Setup: your local forge

Phases 1–2 mostly run in the browser. But real projects — the canvas starter, the snake port, domains, the capstone — need OCaml on your machine. Twenty minutes, once.

The toolchain, in one table

Tool	What it is	Game analogy
`opam`	OCaml's package & compiler manager	the item shop
`ocaml 5.5.0`	the compiler + toplevel	the game engine itself
`dune`	the build system	the crafting bench
`utop`	a deluxe toplevel for your terminal	the training arena
`js_of_ocaml`	compiles OCaml bytecode to JavaScript	the portal to the browser world

1 · Install opam

Linux / macOS — official installer script (or your package manager: apt install opam, dnf install opam, brew install opam; make sure you get opam ≥ 2.1):

Windows — two good options: WSL2 with Ubuntu, then follow the Linux steps inside it (recommended — it matches every terminal block on this site), or native opam ≥ 2.2 from ocaml.org/install.

ℹ️ opam init asks about modifying your shell profile — say yes, or remember to run eval $(opam env) in each new terminal. Forgetting that eval is the #1 beginner trap: the symptom is command not found: dune right after installing it.

2 · Create the OCaml 5.5 switch and install the tools

Verify the loot:

(Later versions are fine.)

3 · Editor

VS Code with the OCaml Platform extension gives inline types, errors and formatting. Install the extension, then:

4 · The canvas starter (your first portal)

Download canvas-starter.zip — a minimal dune project that compiles OCaml to JavaScript and animates a square on an HTML canvas. It's the skeleton every local project in this course grows from.

Open http://localhost:8000 — a bouncing square you steer with the arrow keys. The project layout:

canvas-starter/
├── dune-project      # project manifest (one line of config)
├── bin/
│   ├── dune          # "build main.ml to JavaScript"
│   └── main.ml       # ALL the game logic — yours to edit
└── web/
    ├── dune          # copies the compiled JS next to the page
    ├── index.html    # the page: canvas + HUD (Maks's territory)
    └── style.css     # the look (also Maks's territory)

Edit bin/main.ml, run dune build again, refresh the browser. That's the whole loop. (Try dune build -w for auto-rebuild on save.)

5 · Hosting this site (localhost or homelab)

The site is pure static files in site/. Simplest:

For the homelab, a tiny nginx container (Dockerfile included in the repo — nginx also gzips the 11 MB engine down to ~3 MB on the wire):

Then any device on your network can play at http://<server-ip>:8043.

ℹ️ Family accounts: the full deployment (make compose-up in the repo) also runs the state server, so everyone signs in and their progress follows them between devices. Without it, progress is per-browser — the Progress page can export/import it manually. Admin guides live in the repo under docs/how-to/ (deployment, updates & backups, accounts).

🎮 Side quest: deploy Maks's built games the same way — copy a project's _build/default/web/ into any static server and send the link to the family group chat.

6 · Rebuilding the in-page engine (optional)

The engine at site/assets/toplevel/toplevel.js is an OCaml 5.5 toplevel compiled with js_of_ocaml (source in playground-src/). It ships prebuilt; rebuild only if you upgrade OCaml or hack on it:

Troubleshooting

command not found: dune → run eval $(opam env) (or open a fresh terminal).
opam switch create 5.5.0 says unknown compiler → opam update first.
Port already in use → change 8000/8043 to anything free.
Engine pill says "unavailable" → the site was copied without site/assets/toplevel/toplevel.js; rebuild it (section 6) or re-copy.
The page froze after Run → an infinite loop in the code (it happens to everyone); reload the tab — exercise code is autosaved.