Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Create initial template; #1

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Create initial template; #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .devcontainer/devcontainer-lock.json
View file
Open in desktop
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"
}
}
}
152 changes: 139 additions & 13 deletions .devcontainer/devcontainer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,142 @@
// 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",
"GITHUB_TOKEN": "${localEnv:GITHUB_TOKEN}"
},
"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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
Loading