Skip to content

Add ocx to a dev container

This page takes you from a plain devcontainer.json to a container where ocx is installed and one project tool runs through it.

Before you start

You need Docker, the Dev Containers extension for VS Code or the devcontainer command-line tool, and network access to GitHub and the ocx registry.

Add the feature

Add the feature reference to the features object of .devcontainer/devcontainer.json.

{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/ocx-sh/devcontainer-features/ocx:1": {}
}
}

Rebuild and check ocx

Rebuild the container. In VS Code, run Dev Containers: Rebuild Container from the command palette. With the command-line tool, run devcontainer up --workspace-folder . --remove-existing-container.

Open a terminal in the container and print the version.

Terminal window
ocx version

The output is the ocx version this feature release was tested with.

Terminal window
0.6.8

Add a tool

Create a project file, add the jq tool to it, and run it through ocx exec. The ocx add command fetches the tool and writes ocx.lock, which pins the exact build.

Terminal window
ocx init
ocx add jqlang/jq:1.8
ocx exec -- jq --version

The last command prints the version of the pinned tool.

Terminal window
jq-1.8.2

ocx init writes ocx.toml into the current folder, and ocx add records the tool in it.

[tools]
jq = "ocx.sh/jqlang/jq:1.8"

The command ocx exec -- <command> always finds the project tools. A terminal that starts after the add inside a project under /workspaces also has them on its PATH, so jq runs without the prefix there. That default comes from the consentPaths option.

Commit the project files

Commit ocx.toml and ocx.lock to your repository. The next time the container is created, the feature reads both files and fetches the locked tools before you open a terminal. The .ocx/toolchain folder holds its own .gitignore, so it stays out of your commits.

Next steps