This repository has been archived by the owner on Mar 26, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
2 additions
and
119 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,122 +1,5 @@ | ||
| # Dev Container Templates: Self Authoring Guide | ||
| # Wpdevenv Container Templates: Self Authoring Guide | ||
|
|
||
| > This repo provides a starting point and example for creating your own custom [Dev Container Templates](https://containers.dev/implementors/templates), hosted for free on GitHub Container Registry. The example in this repository follows the [Dev Container Template distribution specification](https://containers.dev/implementors/templates-distribution/). | ||
| > | ||
| > To provide feedback on the distribution spec, please leave a comment [on spec issue #71](https://github.com/devcontainers/spec/issues/71). | ||
| > This repo provides a starting point and example for creating your own custom [Dev Container Templates](https://containers.dev/implementors/templates), hosted for free on GitHub Container Registry. This repository follows the [Dev Container Template distribution specification](https://containers.dev/implementors/templates-distribution/). | ||
| ## Repo and Template Structure | ||
|
|
||
| This repository contains a _collection_ of two Templates - `hello` and `color`. These Templates serve as simple template implementations which helps containerize the project. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `src` folder. Each Template has its own sub-folder, containing at least a `devcontainer-template.json` and `.devcontainer/devcontainer.json`. | ||
|
|
||
| ``` | ||
| ├── src | ||
| │ ├── color | ||
| │ │ ├── devcontainer-template.json | ||
| │ │ └──| .devcontainer | ||
| │ │ └── devcontainer.json | ||
| │ ├── hello | ||
| │ │ ├── devcontainer-template.json | ||
| │ │ └──| .devcontainer | ||
| │ │ ├── devcontainer.json | ||
| │ │ └── Dockerfile | ||
| | ├── ... | ||
| │ │ ├── devcontainer-template.json | ||
| │ │ └──| .devcontainer | ||
| │ │ └── devcontainer.json | ||
| ├── test | ||
| │ ├── color | ||
| │ │ └── test.sh | ||
| │ ├── hello | ||
| │ │ └── test.sh | ||
| │ └──test-utils | ||
| │ └── test-utils.sh | ||
| ... | ||
| ``` | ||
|
|
||
| ### Options | ||
|
|
||
| All available options for a Template should be declared in the `devcontainer-template.json`. The syntax for the `options` property can be found in the [devcontainer Template json properties reference](https://containers.dev/implementors/templates#devcontainer-templatejson-properties). | ||
|
|
||
| For example, the `color` Template provides three possible options (`red`, `gold`, `green`), where the default value is set to "red". | ||
|
|
||
| ```jsonc | ||
| { | ||
| // ... | ||
| "options": { | ||
| "favorite": { | ||
| "type": "string", | ||
| "description": "Choose your favorite color." | ||
| "proposals": [ | ||
| "red", | ||
| "gold", | ||
| "green" | ||
| ], | ||
| "default": "red" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| An [implementing tool](https://containers.dev/supporting#tools) will use the `options` property from [the documented Dev Container Template properties](https://containers.dev/implementors/templates#devcontainer-templatejson-properties) for customizing the Template. See [option resolution example](https://containers.dev/implementors/templates#option-resolution-example) for details. | ||
|
|
||
| ## Distributing Templates | ||
|
|
||
| **Note**: *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/<template>/README.md` per Template (which merges any existing `src/<template>/NOTES.md`). | ||
|
|
||
| ### Versioning | ||
|
|
||
| Templates are individually versioned by the `version` attribute in a Template's `devcontainer-template.json`. Templates are versioned according to the semver specification. More details can be found in [the Dev Container Template specification](https://containers.dev/implementors/templates-distribution/#versioning). | ||
|
|
||
| ### Publishing | ||
|
|
||
| > NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/templates-distribution/). | ||
| > | ||
| > While any registry [implementing the OCI Distribution spec](https://github.com/opencontainers/distribution-spec) can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry. | ||
| Templates are source files packaged together that encode configuration for a complete development environment. | ||
|
|
||
| This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will publish each template to GHCR. By default, each Template will be prefixed with the `<owner/<repo>` namespace. For example, the two Templates in this repository can be referenced by an [implementing tool](https://containers.dev/supporting#tools) with: | ||
|
|
||
| ``` | ||
| ghcr.io/devcontainers/template-starter/color:latest | ||
| ghcr.io/devcontainers/template-starter/hello:latest | ||
| ``` | ||
|
|
||
| The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: `ghcr.io/devcontainers/template-starter`. This contains information useful for tools aiding in Template discovery. | ||
|
|
||
| '`devcontainers/template-starter`' is known as the template collection namespace. | ||
|
|
||
| ### Marking Template Public | ||
|
|
||
| For your Template to be used, it currently needs to be available publicly. By default, OCI Artifacts in GHCR are marked as `private`. | ||
|
|
||
| To make them public, navigate to the Template's "package settings" page in GHCR, and set the visibility to 'public`. | ||
|
|
||
| ``` | ||
| https://github.com/users/<owner>/packages/container/<repo>%2F<templateName>/settings | ||
| ``` | ||
|
|
||
| ### Adding Templates to the Index | ||
|
|
||
| Next you will need to add your Templates collection to our [public index](https://containers.dev/templates) so that other community members can find them. Just follow these steps once per collection you create: | ||
|
|
||
| * Go to [github.com/devcontainers/devcontainers.github.io](github.com/devcontainers/devcontainers.github.io) | ||
| * This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site | ||
| * Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file | ||
|
|
||
| This index is from where [supporting tools](https://containers.dev/supporting) like [VS Code Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [GitHub Codespaces](https://github.com/templates/codespaces) surface Templates for their Dev Container Creation Configuration UI. | ||
|
|
||
| ### Testing Templates | ||
|
|
||
| This repo contains a GitHub Action [workflow](.github/workflows/test-pr.yaml) for testing the Templates. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `test` folder. Each Template has its own sub-folder, containing at least a `test.sh`. | ||
|
|
||
| For running the tests locally, you would need to execute the following commands - | ||
|
|
||
| ``` | ||
| ./.github/actions/smoke-test/build.sh ${TEMPLATE-ID} | ||
| ./.github/actions/smoke-test/test.sh ${TEMPLATE-ID} | ||
| ``` | ||
|
|
||
| ### Updating Documentation | ||
|
|
||
| This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will automatically generate documentation (ie. `README.md`) for each Template. This file will be auto-generated from the `devcontainer-template.json` and `NOTES.md`. |