Dev Container Features: Self Authoring Template

This repo provides a starting point and example for creating your own custom dev container Features, hosted for free on GitHub Container Registry. The example in this repository follows the dev container Feature distribution specification.

To provide feedback to the specification, please leave a comment on spec issue #70. For more broad feedback regarding dev container Features, please see spec issue #61.

latex

Running latex inside the built container will install Tex Live latex compiler with tlmgr package manager, alongside LaTeX Workshop extension.

{
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "features": {
        "ghcr.io/rnicrosoft-studio/devcontainer-features/latex": {
            "scheme": "full" // may take about 30+ minutes
        }
    }
}

$ hello

Hello, user.

Repo and Feature Structure

Similar to the devcontainers/features repo, this repository has a src folder. Each Feature has its own sub-folder, containing at least a devcontainer-feature.json and an entrypoint script install.sh.

├── src
│   ├── hello
│   │   ├── devcontainer-feature.json
│   │   └── install.sh
|   ├── ...
│   │   ├── devcontainer-feature.json
│   │   └── install.sh
...

An implementing tool will composite the documented dev container properties from the feature's devcontainer-feature.json file, and execute in the install.sh entrypoint script in the container during build time. Implementing tools are also free to process attributes under the customizations property as desired.

Options

All available options for a Feature should be declared in the devcontainer-feature.json. The syntax for the options property can be found in the devcontainer Feature json properties reference.

Options are exported as Feature-scoped environment variables. The option name is captialized and sanitized according to option resolution.

Distributing Features

Versioning

Features are individually versioned by the version attribute in a Feature's devcontainer-feature.json. Features are versioned according to the semver specification. More details can be found in the dev container Feature specification.

Publishing

NOTE: The Distribution spec can be found here.

While any registry implementing the OCI Distribution spec can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry.

Features are meant to be easily sharable units of dev container configuration and installation code.

This repo contains a GitHub Action workflow that will publish each Feature to GHCR.

Allow GitHub Actions to create and approve pull requests should be enabled in the repository's Settings > Actions > General > Workflow permissions for auto generation of src/<feature>/README.md per Feature (which merges any existing src/<feature>/NOTES.md).

By default, each Feature will be prefixed with the <owner/<repo> namespace.

Marking Feature Public

Note that by default, GHCR packages are marked as private. To stay within the free tier, Features need to be marked as public.

This can be done by navigating to the Feature's "package settings" page in GHCR, and setting the visibility to 'public`. The URL may look something like:

https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/settings