Skip to content

Commit

Permalink
Create initial template;
Browse files Browse the repository at this point in the history
  • Loading branch information
alexanderilyin committed Aug 22, 2024
1 parent 0f6eedf commit a6c2633
Show file tree
Hide file tree
Showing 24 changed files with 356 additions and 294 deletions.
45 changes: 45 additions & 0 deletions .devcontainer/devcontainer-lock.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
{
"features": {
"ghcr.io/deep-space-cartel/devcontainers-features/apt:1": {
"version": "1.1.0",
"resolved": "ghcr.io/deep-space-cartel/devcontainers-features/apt@sha256:3a8ef060a682ecded4d2b68c951a4f58d22629df4f169534ae9b4e647a60e8d2",
"integrity": "sha256:3a8ef060a682ecded4d2b68c951a4f58d22629df4f169534ae9b4e647a60e8d2"
},
"ghcr.io/deep-space-cartel/devcontainers-features/pip:1": {
"version": "1.0.0",
"resolved": "ghcr.io/deep-space-cartel/devcontainers-features/pip@sha256:9e68548232099e2fa129723ae3c0962b59416c16028c8d7c1a10d963a3ff05ac",
"integrity": "sha256:9e68548232099e2fa129723ae3c0962b59416c16028c8d7c1a10d963a3ff05ac",
"dependsOn": [
"ghcr.io/deep-space-cartel/devcontainers-features/apt:1"
]
},
"ghcr.io/deep-space-cartel/devcontainers-features/starship:1": {
"version": "1.2.0",
"resolved": "ghcr.io/deep-space-cartel/devcontainers-features/starship@sha256:70ae84bb250918d1da871ca6e2bdc7017ff420cc7dd04bafc0ec6ecb8527e4ef",
"integrity": "sha256:70ae84bb250918d1da871ca6e2bdc7017ff420cc7dd04bafc0ec6ecb8527e4ef",
"dependsOn": [
"ghcr.io/devcontainers/features/common-utils"
]
},
"ghcr.io/devcontainers/features/common-utils": {
"version": "2.5.1",
"resolved": "ghcr.io/devcontainers/features/common-utils@sha256:9da676524999513412f2c27604d786ba0bbf3575eb1859166c5a1233f037fc08",
"integrity": "sha256:9da676524999513412f2c27604d786ba0bbf3575eb1859166c5a1233f037fc08"
},
"ghcr.io/devcontainers/features/docker-in-docker:2": {
"version": "2.11.0",
"resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:503f23cd692325b3cbb8c20a0ecfabb3444b0c786b363e0c82572bd7d71dc099",
"integrity": "sha256:503f23cd692325b3cbb8c20a0ecfabb3444b0c786b363e0c82572bd7d71dc099"
},
"ghcr.io/devcontainers/features/git:1": {
"version": "1.3.2",
"resolved": "ghcr.io/devcontainers/features/git@sha256:63c96e8ac33f5630300d8883e2ec3123278de70d318589af596ea1954846014d",
"integrity": "sha256:63c96e8ac33f5630300d8883e2ec3123278de70d318589af596ea1954846014d"
},
"ghcr.io/devcontainers/features/github-cli:1": {
"version": "1.0.13",
"resolved": "ghcr.io/devcontainers/features/github-cli@sha256:13b301a039ce9e0bb07d45ea0c106c946cfff01c3b9844bbec6b0c7bacba8de3",
"integrity": "sha256:13b301a039ce9e0bb07d45ea0c106c946cfff01c3b9844bbec6b0c7bacba8de3"
}
}
}
151 changes: 138 additions & 13 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
@@ -1,16 +1,141 @@
// More info: https://containers.dev/implementors/json_reference/
{
"image": "mcr.microsoft.com/devcontainers/javascript-node:1-18-bullseye",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
},
"customizations": {
"vscode": {
"extensions": [
"mads-hartmann.bash-ide-vscode",
"dbaeumer.vscode-eslint"
]
}
},
"postCreateCommand": "npm install -g @devcontainers/cli"
"image": "mcr.microsoft.com/devcontainers/javascript-node:1-18-bullseye",
"remoteEnv": {
"WAKATIME_API_KEY": "${localEnv:WAKATIME_API_KEY}",
"PATH": "${containerEnv:PATH}:/opt/pip/bin"
},
"features": {
"ghcr.io/devcontainers/features/git:1": {},
"ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/devcontainers/features/docker-in-docker:2": {},
"ghcr.io/deep-space-cartel/devcontainers-features/starship:1": {},
"ghcr.io/deep-space-cartel/devcontainers-features/apt:1": {
"packages": "bash-completion shellcheck mc python3-pip python3-venv" // shfmt
},
"ghcr.io/deep-space-cartel/devcontainers-features/pip:1": {
"packages": "pre-commit",
"location": "/opt/pip"
}
},
"customizations": {
"vscode": {
"settings": {
"tasks": {
"version": "2.0.0",
"tasks": [
{
"label": "pre-commit: manual",
"type": "shell",
"command": "pre-commit",
"args": [
"run",
"--hook-stage",
"manual"
],
"group": {
"kind": "test",
"isDefault": false
}
},
{
"label": "Dev Containers: Build ubik",
"type": "shell",
"command": ".github/actions/smoke-test/build.sh",
"args": [
"ubik"
],
"group": {
"kind": "build",
"isDefault": false
}
},
{
"label": "Starship: Install Completions",
"type": "shell",
"command": "sudo",
"args": [
"bash",
"-c",
"starship completions $(basename $SHELL) > /etc/bash_completion.d/99-starship-completions.sh"
],
"group": {
"kind": "build",
"isDefault": false
}
},
{
"label": "Dev Containers: Publish Templates",
"type": "shell",
"command": "devcontainer",
"args": [
"templates",
"publish",
"--namespace",
"deep-space-cartel/devcontainers-templates",
"src/"
],
"group": {
"kind": "build",
"isDefault": false
}
},
{
"label": "Dev Containers: Upgrade lockfile",
"type": "shell",
"command": "devcontainer",
"args": [
"upgrade",
"--workspace-folder",
"."
],
"group": {
"kind": "build",
"isDefault": false
}
},
{
"label": "Dev Container Feature: Generate Docs",
"type": "shell",
"command": "devcontainer",
"args": [
"templates",
"generate-docs",
"--github-owner",
"deep-space-cartel",
"--github-repo",
"devcontainers-templates",
"--project-folder",
"src/"
],
"group": {
"kind": "build",
"isDefault": false
}
}
]
},
"editor.fontFamily": "'Hack Nerd Font Mono'",
"terminal.integrated.fontFamily": "'Hack Nerd Font Mono'",
"files.insertFinalNewline": true,
"dotfiles.repository": "deep-space-cartel/dotfiles",
"cSpell.enableFiletypes": [
"*"
],
"remote.extensionKind": {
"ms-vscode.PowerShell": [
"ui"
],
"1Password.op-vscode": [
"ui"
]
}
},
"extensions": [
"mads-hartmann.bash-ide-vscode",
"dbaeumer.vscode-eslint"
]
}
},
"postCreateCommand": "npm install -g @devcontainers/cli"
}
1 change: 1 addition & 0 deletions .env
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
GITHUB_TOKEN = "op://DeepSpaceCartel/GITHUB_TOKEN/CLASSIC"
2 changes: 1 addition & 1 deletion .github/actions/smoke-test/action.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ runs:
- name: Test template
id: test_template
shell: bash
run: ${{ github.action_path }}/test.sh ${{ inputs.template }}
run: ${{ github.action_path }}/test.sh ${{ inputs.template }}
2 changes: 1 addition & 1 deletion .github/actions/smoke-test/build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ pushd "${SRC_DIR}"
# Configure templates only if `devcontainer-template.json` contains the `options` property.
OPTION_PROPERTY=( $(jq -r '.options' devcontainer-template.json) )

if [ "${OPTION_PROPERTY}" != "" ] && [ "${OPTION_PROPERTY}" != "null" ] ; then
if [ "${OPTION_PROPERTY}" != "" ] && [ "${OPTION_PROPERTY}" != "null" ] ; then
OPTIONS=( $(jq -r '.options | keys[]' devcontainer-template.json) )

if [ "${OPTIONS[0]}" != "" ] && [ "${OPTIONS[0]}" != "null" ] ; then
Expand Down
5 changes: 2 additions & 3 deletions .github/workflows/test-pr.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,7 @@ jobs:
id: filter
with:
filters: |
color: ./**/color/**
hello: ./**/hello/**
ubik: ./**/ubik/**
test:
needs: [detect-changes]
Expand All @@ -23,7 +22,7 @@ jobs:
matrix:
templates: ${{ fromJSON(needs.detect-changes.outputs.templates) }}
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4

- name: Smoke test for '${{ matrix.templates }}'
id: smoke_test
Expand Down
12 changes: 12 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v3.2.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
- id: mixed-line-ending
args: ['--fix=lf']
113 changes: 2 additions & 111 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,100 +1,6 @@
# Dev Container Templates: Self Authoring Guide
# Dev Containers Templates

> 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
```
[![CI - Test Templates](https://github.com/deep-space-cartel/devcontainers-templates/actions/workflows/test-pr.yaml/badge.svg)](https://github.com/deep-space-cartel/devcontainers-templates/actions/workflows/test-pr.yaml)

### Adding Templates to the Index

Expand All @@ -105,18 +11,3 @@ Next you will need to add your Templates collection to our [public index](https:
* 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`.
11 changes: 11 additions & 0 deletions op.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Usage: Run PowerShell as Administrator and execute this:
# Set-ExecutionPolicy RemoteSigned

# Define the path to your .env file
$envFilePath = "./.env"

# Define the command to execute
$command = "op run --env-file='$envFilePath' -- code --new-window ."

# Execute the command
Invoke-Expression $command
Loading

0 comments on commit a6c2633

Please sign in to comment.