Skip to content

Commit

Permalink
feat: lino devcontainer
Browse files Browse the repository at this point in the history
  • Loading branch information
youen committed Sep 25, 2023
1 parent b8745b9 commit 57c87eb
Show file tree
Hide file tree
Showing 12 changed files with 33 additions and 257 deletions.
123 changes: 2 additions & 121 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,122 +1,3 @@
# Dev Container Templates: Self Authoring Guide
# LINO devcontainer template

> 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).
## 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`.
Lino devcontainer template to start with LINO, PIMO, SIGO tools.
18 changes: 0 additions & 18 deletions src/color/.devcontainer/devcontainer.json

This file was deleted.

17 changes: 0 additions & 17 deletions src/color/README.md

This file was deleted.

32 changes: 0 additions & 32 deletions src/color/devcontainer-template.json

This file was deleted.

4 changes: 0 additions & 4 deletions src/hello/.devcontainer/Dockerfile

This file was deleted.

17 changes: 0 additions & 17 deletions src/hello/README.md

This file was deleted.

34 changes: 0 additions & 34 deletions src/hello/devcontainer-template.json

This file was deleted.

4 changes: 4 additions & 0 deletions src/lino/.devcontainer/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
FROM cgifr/lino-toolbox:${templateOption:imageVariant}

CMD [ "sleep", "infinity" ]

Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"name": "Hello, World",
"name": "LINO",
"build": {
"dockerfile": "Dockerfile"
},
}

// 👇 Features to add to the Dev Container. More info: https://containers.dev/implementors/features.
// "features": {},
Expand All @@ -11,7 +11,7 @@
// "forwardPorts": [],

// 👇 Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "cat /usr/local/etc/greeting.txt"
// "postCreateCommand": ""

// 👇 Configure tool-specific properties.
// "customizations": {},
Expand Down
21 changes: 21 additions & 0 deletions src/lino/devcontainer-template.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"id": "lino",
"version": "1.0.0",
"name": "LINO",
"description": "A LINO workspace with all LINO tools",
"documentationURL": "https://github.com/CGI-FR/lino-devcontainer/tree/main/src/lino",
"licenseURL": "https://github.com/CGI-FR/lino-devcontainer/blob/main/LICENSE",
"options": {
"imageVariant": {
"type": "string",
"description": "version of the lino's toolbox image",
"proposals": [
"v1.3.0 # (lino:V2.4.0, pimo:v1.19.0)"
],
"default": "v1.3.0"
}
},
"platforms": [
"Any"
]
}
10 changes: 0 additions & 10 deletions test/hello/test.sh

This file was deleted.

4 changes: 3 additions & 1 deletion test/color/test.sh → test/lino/test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ source test-utils.sh

# Template specific tests
check "distro" lsb_release -c
check "color" [ $(cat /tmp/color.txt | grep red) ]
check "lino" [ $(lino --version) ]
check "pimo" [ $(pimo --version) ]
check "sigo" [ $(sigo --version) ]

# Report result
reportResults

0 comments on commit 57c87eb

Please sign in to comment.