- integrations
- Dev Containers
- Guides
- Pin or upgrade the ocx version
Pin or upgrade the ocx version
This page shows how to set the ocx version a dev container installs and how to read the installed version back.
The version option takes pinned, an exact X.Y.Z or latest.
Know what the default installs
The default is "version": "pinned".
It installs the ocx version that the feature release was tested with, so each feature version maps to one ocx version (why).
Feature 1.0.0 installs ocx 0.6.8.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": {} }}A new feature patch version is released for every ocx release.
The tag :1 therefore follows ocx, and a rebuild takes the highest patch.
Pin an exact version
Set version to an X.Y.Z value.
The feature installs that release from the release manifest bundled with it, which lists past ocx releases.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": { "version": "0.6.7" } }}A version that the bundled manifest does not list stops the build with exit code 2. The message names the highest version it has.
ocx-feature: error: no ocx 9.9.9 build for x86_64-unknown-linux-musl in the release manifest (newest available: 0.6.8); set version: latest or distUrl to a manifest that has itA value that is not pinned, latest or three dot-separated numbers also fails with exit code 2.
For example, banana stops with option version must be pinned, latest or X.Y.Z (got: banana).
To install a version that the bundled manifest lacks, point distUrl at a manifest that lists it.
The feature installs .tar.gz releases only, so the oldest installable ocx version is 0.4.3 on x86_64 with musl.
An older version such as 0.4.2 stops the build with exit code 2 before any download, and the message names the oldest version for your platform.
ocx-feature: error: ocx 0.4.2 ships as ocx-x86_64-unknown-linux-musl.tar.xz; this feature installs .tar.gz releases only. The oldest x86_64-unknown-linux-musl .tar.gz build is 0.4.3: set version to 0.4.3 or newerFollow every new release
Set version to latest.
The build reads the live release manifest from setup.ocx.sh and installs the highest stable release.
That read needs network access at build time, and two builds on different days can install different versions.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": { "version": "latest" } }}If the manifest cannot be fetched, the build stops with exit code 3. This option trusts the HTTPS endpoint that serves the manifest, while the default pin verifies the archive against a checksum bundled in the feature. What the feature trusts explains the difference.
Pin the feature tag
The feature tag decides which feature release, and so which default ocx version, a rebuild gets.
A full tag freezes the feature and the ocx version it pins.
To freeze it by content instead, reference the feature by digest as ocx@sha256:<digest>.
{ "features": { // follows every minor and patch release of major version 1 "ghcr.io/ocx-sh/devcontainer-features/ocx:1": {}, // follows patch releases of 1.0 "ghcr.io/ocx-sh/devcontainer-features/ocx:1.0": {}, // stays on this exact feature release "ghcr.io/ocx-sh/devcontainer-features/ocx:1.0.0": {} }}Upgrade on purpose
To move to another ocx version, change the value and rebuild the container.
- With
pinned, move to a higher feature tag or release. - With an exact version, edit the
versionvalue. - With
latest, rebuild the container.
Check the installed version
Run ocx version in the container.
The feature also records the version it installed in a file.
ocx versioncat /usr/local/share/ocx-feature/ocx-versionBoth commands print the same version, for example 0.6.7 after the exact pin above.
Next steps
- Add ocx to a dev container is the first-run walk-through.
- Use ocx on a minimal base image covers images without the usual tools.
- Changelog lists the ocx version each feature release pins.
- Fix a rejected option or version matches each version error to its fix.