SETUP-YOUR-PROJECT.md

Adding the DevContainer to Your Project

You can add this OCaml devcontainer to your own repository so that contributors (and you) get a working environment via GitHub Codespaces, VS Code Dev Containers, or the DevContainer CLI.

Minimal setup

Create .devcontainer/devcontainer.json in your project root:

{
  "name": "OCaml Development",
  // Pre-built image from Docker Hub
  "image": "cuihtlauac/ocaml-devcontainer:latest",

  "customizations": {
    "vscode": {
      "extensions": ["ocamllabs.ocaml-platform"],
      "settings": {
        "ocaml.sandbox": {
          "kind": "opam",
          "switch": "ocaml"
        }
      }
    }
  },

  "postCreateCommand": "opam install . --deps-only -y"
}

Commit this file and push. The "Create codespace" button will appear on your repository's Code tab automatically.

What each field does

Field	Purpose
image	Pre-built image with OCaml 5.4, dune, ocaml-lsp-server, utop, and more
customizations.vscode	Installs the OCaml extension and configures it for the ocaml switch
postCreateCommand	Installs your project's opam dependencies on first start. Runs once when the container is created

Optional additions

Dune build cache

Persist the dune cache across container rebuilds so incremental builds stay fast:

{
  "mounts": [
    "source=dune-cache,target=/home/vscode/.cache/dune,type=volume"
  ],
  "remoteEnv": {
    "DUNE_CACHE_ROOT": "/home/vscode/.cache/dune"
  }
}

Codespace machine size

Request minimum resources for Codespaces (useful for large projects):

{
  "hostRequirements": {
    "cpus": 4,
    "memory": "8gb",
    "storage": "32gb"
  }
}

Claude Code

Add Claude Code as a DevContainer Feature:

{
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1": {}
  }
}

Post-start commands

Run commands every time the container starts (not just on creation):

{
  "postStartCommand": "dune build"
}

Full example

A complete .devcontainer/devcontainer.json with all optional additions:

{
  "name": "OCaml Development",
  "image": "cuihtlauac/ocaml-devcontainer:latest",

  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1": {}
  },

  "customizations": {
    "vscode": {
      "extensions": ["ocamllabs.ocaml-platform"],
      "settings": {
        "ocaml.sandbox": {
          "kind": "opam",
          "switch": "ocaml"
        }
      }
    }
  },

  "postCreateCommand": "opam install . --deps-only -y",

  "mounts": [
    "source=dune-cache,target=/home/vscode/.cache/dune,type=volume"
  ],

  "remoteEnv": {
    "DUNE_CACHE_ROOT": "/home/vscode/.cache/dune"
  },

  "hostRequirements": {
    "cpus": 4,
    "memory": "8gb",
    "storage": "32gb"
  }
}

For projects with heavy dependencies

If your project has many opam dependencies, postCreateCommand will run on every new container creation, which can be slow. In that case, build a project-specific image instead:

FROM cuihtlauac/ocaml-devcontainer:latest
COPY *.opam /tmp/project/
RUN cd /tmp/project && opam install . --deps-only -y && rm -rf /tmp/project

Then reference it in your devcontainer.json:

{
  "build": {
    "dockerfile": "Dockerfile"
  }
}

This bakes your dependencies into the image so container startup is fast.

Using the devcontainer

Once .devcontainer/devcontainer.json is committed:

• GitHub Codespaces: Click "Code" > "Codespaces" > "Create codespace" on your repo page
• VS Code: Open the repo folder and click "Reopen in Container" when prompted
• CLI: devcontainer up --workspace-folder . && devcontainer exec --workspace-folder . bash

See the Codespaces guide, VS Code guide, or CLI guide for details on each workflow.