From 0ea5c5956a4ebbd212efb8388febec370dc1c0e8 Mon Sep 17 00:00:00 2001 From: Brigit Murtaugh Date: Mon, 12 May 2025 23:01:31 +0000 Subject: [PATCH 1/4] Add instructions --- .github/copilot-instructions.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..3724bf7a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,3 @@ +Every code change needs to be tested before it's committed. Prompt me to run the site and check it's working properly. + +End every response with "Happy Build!" on a new line. \ No newline at end of file From b007c2fcaeb9aef47efcf3d93f2bd8552ec2b20d Mon Sep 17 00:00:00 2001 From: Brigit Murtaugh Date: Mon, 12 May 2025 23:21:32 +0000 Subject: [PATCH 2/4] Instructions --- .github/copilot-instructions.md | 2 +- .github/instructions/new-html-page.instructions.md | 9 +++++++++ .github/instructions/new-md-page.instructions.md | 7 +++++++ .github/prompts/html-page.prompt.md | 10 ++++++++++ .github/prompts/md-page.prompt.md | 6 ++++++ 5 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 .github/instructions/new-html-page.instructions.md create mode 100644 .github/instructions/new-md-page.instructions.md create mode 100644 .github/prompts/html-page.prompt.md create mode 100644 .github/prompts/md-page.prompt.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3724bf7a..f93a0adf 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,3 +1,3 @@ -Every code change needs to be tested before it's committed. Prompt me to run the site and check it's working properly. +Every code change needs to be tested before it's committed. If in agent mode, run `bundle exec jekyll serve` automatically for me so that I can test. End every response with "Happy Build!" on a new line. \ No newline at end of file diff --git a/.github/instructions/new-html-page.instructions.md b/.github/instructions/new-html-page.instructions.md new file mode 100644 index 00000000..f9ce0a13 --- /dev/null +++ b/.github/instructions/new-html-page.instructions.md @@ -0,0 +1,9 @@ +--- +applyTo: '**/*.html' +--- + +## Project coding standards for new HTML pages of the website + +Every new HTML page should have a search bar added, similar to the search bar that's available on the features.html, templates.html, and collections.html pages. + +Any new page should also be added to the end (far right) of the top nav bar of the website. \ No newline at end of file diff --git a/.github/instructions/new-md-page.instructions.md b/.github/instructions/new-md-page.instructions.md new file mode 100644 index 00000000..bbcf68eb --- /dev/null +++ b/.github/instructions/new-md-page.instructions.md @@ -0,0 +1,7 @@ +--- +applyTo: '**/*.md' +--- + +## Project coding standards for new pages of the specification + +Every new specification page should be added to the _implementors folder, just like the pages in that folder already (like spec.md and features.md). \ No newline at end of file diff --git a/.github/prompts/html-page.prompt.md b/.github/prompts/html-page.prompt.md new file mode 100644 index 00000000..80bbef7a --- /dev/null +++ b/.github/prompts/html-page.prompt.md @@ -0,0 +1,10 @@ +--- +mode: 'agent' +--- +Your goal is to generate a new HTML page for the website. The page should be similar to the existing pages in terms of layout and design. + +Every new HTML page should have a search bar added, similar to the search bar that's available on the features.html, templates.html, and collections.html pages. + +Any new page should also be added to the end (far right) of the top nav bar of the website. + +Every code change needs to be tested before it's committed. Run `bundle exec jekyll serve` automatically for me so that I can test. \ No newline at end of file diff --git a/.github/prompts/md-page.prompt.md b/.github/prompts/md-page.prompt.md new file mode 100644 index 00000000..7b5605ba --- /dev/null +++ b/.github/prompts/md-page.prompt.md @@ -0,0 +1,6 @@ +--- +mode: 'agent' +--- +Your goal is to generate a new .md specification page for the website. The page should be similar to the existing pages in terms of layout and design. + +Every new specification page should be added to the _implementors folder, just like the pages in that folder already (like spec.md and features.md). \ No newline at end of file From 6b9ef43116ba6334ebc225463f0a6014734d82cd Mon Sep 17 00:00:00 2001 From: Brigit Murtaugh Date: Mon, 12 May 2025 23:44:03 +0000 Subject: [PATCH 3/4] feat: update guidance for adding new HTML and markdown pages; remove obsolete prompts --- .github/copilot-instructions.md | 8 +++++++- .../new-html-page.instructions.md | 17 +++++++++++++---- .../instructions/new-md-page.instructions.md | 19 +++++++++++++++++-- .github/prompts/html-page.prompt.md | 10 ---------- .github/prompts/md-page.prompt.md | 6 ------ .github/prompts/new-page.prompt.md | 12 ++++++++++++ 6 files changed, 49 insertions(+), 23 deletions(-) delete mode 100644 .github/prompts/html-page.prompt.md delete mode 100644 .github/prompts/md-page.prompt.md create mode 100644 .github/prompts/new-page.prompt.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f93a0adf..c11174a4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,3 +1,9 @@ -Every code change needs to be tested before it's committed. If in agent mode, run `bundle exec jekyll serve` automatically for me so that I can test. +If the user would like to add a new page, clarify if this page is either a: +* New main page of the website. This will be a .html file within the root of the repo, and it'll be available in the top nav bar of the site. +* New page of the specification. This will be a .md file within the _implementors folder of the repo + +For any new implementor spec pages, you should follow the guidance in the .github/prompts/new-page.prompt.md file. + +Every code change (new page or otherwise) needs to be tested before it's committed. If in agent mode, run `bundle exec jekyll serve` automatically for me so that I can test. End every response with "Happy Build!" on a new line. \ No newline at end of file diff --git a/.github/instructions/new-html-page.instructions.md b/.github/instructions/new-html-page.instructions.md index f9ce0a13..94d7f313 100644 --- a/.github/instructions/new-html-page.instructions.md +++ b/.github/instructions/new-html-page.instructions.md @@ -1,9 +1,18 @@ --- applyTo: '**/*.html' --- +## Guidance for new HTML website pages -## Project coding standards for new HTML pages of the website - -Every new HTML page should have a search bar added, similar to the search bar that's available on the features.html, templates.html, and collections.html pages. +### Layout +- Every new HTML page should have information like the following at the top, where the title is updated appropriately: +``` +--- +layout: singlePage +title: Dev Container Guides +--- +``` +- The layout should come from the _layouts folder in the repo. Pages should default to `layout: singlePage`. -Any new page should also be added to the end (far right) of the top nav bar of the website. \ No newline at end of file +### Content +- Every new HTML page should have a search bar added toward the top, similar to the search bar that's available on the features.html, templates.html, and collections.html pages. +- Make all headings clickable links. \ No newline at end of file diff --git a/.github/instructions/new-md-page.instructions.md b/.github/instructions/new-md-page.instructions.md index bbcf68eb..087b4f32 100644 --- a/.github/instructions/new-md-page.instructions.md +++ b/.github/instructions/new-md-page.instructions.md @@ -2,6 +2,21 @@ applyTo: '**/*.md' --- -## Project coding standards for new pages of the specification +## Guidance for new markdown specification pages -Every new specification page should be added to the _implementors folder, just like the pages in that folder already (like spec.md and features.md). \ No newline at end of file +### Layout +- Any new page should have information like the following at the top, where the title, shortTitle, and index are updated appropriately: +``` +--- +layout: implementors +title: "Dev Container Templates distribution and discovery" +shortTitle: "Templates distribution" +author: Microsoft +index: 8 +--- +``` +- The layout comes from the _layouts folder in the repo and will always be `layout: implementors` for pages of this type. + +### Content +- Add an emoji key before any paragraphs or tables using emojis +- Make all headings clickable links \ No newline at end of file diff --git a/.github/prompts/html-page.prompt.md b/.github/prompts/html-page.prompt.md deleted file mode 100644 index 80bbef7a..00000000 --- a/.github/prompts/html-page.prompt.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -mode: 'agent' ---- -Your goal is to generate a new HTML page for the website. The page should be similar to the existing pages in terms of layout and design. - -Every new HTML page should have a search bar added, similar to the search bar that's available on the features.html, templates.html, and collections.html pages. - -Any new page should also be added to the end (far right) of the top nav bar of the website. - -Every code change needs to be tested before it's committed. Run `bundle exec jekyll serve` automatically for me so that I can test. \ No newline at end of file diff --git a/.github/prompts/md-page.prompt.md b/.github/prompts/md-page.prompt.md deleted file mode 100644 index 7b5605ba..00000000 --- a/.github/prompts/md-page.prompt.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -mode: 'agent' ---- -Your goal is to generate a new .md specification page for the website. The page should be similar to the existing pages in terms of layout and design. - -Every new specification page should be added to the _implementors folder, just like the pages in that folder already (like spec.md and features.md). \ No newline at end of file diff --git a/.github/prompts/new-page.prompt.md b/.github/prompts/new-page.prompt.md new file mode 100644 index 00000000..bc93e918 --- /dev/null +++ b/.github/prompts/new-page.prompt.md @@ -0,0 +1,12 @@ +--- +mode: 'agent' +--- +Your goal is to generate a new page for the website. The page should be similar to the existing pages in terms of layout and design. + +If I don't specify initial content, generate some placeholder text. + +Any new page should also be added to the end (far right) of the top nav bar of the website. + +Any new implementor .md file should be added to the table of contents box visible within the /implementors route. + +Every new page needs to be tested before it's committed. Run `bundle exec jekyll serve` automatically for me so that I can test. \ No newline at end of file From b7f5642545f4b02999c178b64419269d6217ee8e Mon Sep 17 00:00:00 2001 From: Brigit Murtaugh Date: Tue, 13 May 2025 00:14:36 +0000 Subject: [PATCH 4/4] Add page --- _implementors/prebuilt-images.md | 233 +++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 _implementors/prebuilt-images.md diff --git a/_implementors/prebuilt-images.md b/_implementors/prebuilt-images.md new file mode 100644 index 00000000..7ec02314 --- /dev/null +++ b/_implementors/prebuilt-images.md @@ -0,0 +1,233 @@ +--- +layout: implementors +title: "Prebuilt Dev Container Images" +shortTitle: "Prebuilt Images" +author: Microsoft +index: 9 +--- + +**Prebuilt Dev Container Images** allow you to package your development environment configuration into a container image that can be reused across different projects and shared with other developers. By prebuilding images, you can significantly improve container startup time, ensure consistency across environments, and simplify your `devcontainer.json` configuration. + +## Overview + +Prebuilt dev container images combine the benefits of reproducible development environments with faster startup times. When you prebuild a dev container image: + +1. All dev container configuration, including Features, are baked into the image +2. Startup time is reduced as dependencies are pre-installed +3. The image can be version-tagged for stability and reproducibility +4. Metadata is stored in image labels for seamless use across projects + +Prebuilt images are particularly valuable for: +- Teams that want consistent development environments +- Projects with complex dependency requirements +- CI/CD workflows that benefit from reproducible environments +- Open source projects that want to provide contributors with ready-to-use environments + +## Creating Prebuilt Images + +You can create prebuilt images using the [Dev Container CLI](/implementors/reference), GitHub Actions, or other CI tools. + +### Using the Dev Container CLI + +To prebuild an image with the Dev Container CLI: + +1. Install the CLI: + ```bash + npm install -g @devcontainers/cli + ``` + +2. Build and push your image to a container registry: + ```bash + devcontainer build --workspace-folder . --push true --image-name //: + ``` + +### Using GitHub Actions + +For automated builds, you can use the [Dev Container Build and Run Action](https://github.com/marketplace/actions/dev-container-build-and-run-action): + +```yaml +name: Build and Push Dev Container Image + +on: + push: + branches: [ main ] + paths: + - '.devcontainer/**' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Build and Push Dev Container Image + uses: devcontainers/ci@v0.3 + with: + imageName: ghcr.io/your-org/your-image + imageTag: latest + push: always + # Optional: Registry authentication + # registryPassword: ${{ secrets.GITHUB_TOKEN }} +``` + +### Using Azure DevOps + +You can also use the [Dev Container Task for Azure Pipelines](https://marketplace.visualstudio.com/items?itemName=devcontainers.ci): + +```yaml +steps: +- task: DevcontainersCi@0 + inputs: + imageName: 'your-registry/your-image' + imageTag: 'v1' + push: true + # Optional: Registry authentication + # registryPassword: $(registryPassword) +``` + +## Using Prebuilt Images + +Once you have a prebuilt image available in a container registry, you can reference it directly in your `devcontainer.json`: + +```json +{ + "image": "ghcr.io/your-org/your-image:latest" +} +``` + +You can also use prebuilt images as a base in a Dockerfile: + +```dockerfile +FROM ghcr.io/your-org/your-image:latest + +# Add additional customizations here +``` + +Or in a Docker Compose file: + +```yaml +version: '3' +services: + devcontainer: + image: ghcr.io/your-org/your-image:latest + volumes: + - ../..:/workspaces:cached + command: sleep infinity +``` + +## Metadata in Image Labels + +When you prebuild an image using the Dev Container CLI or supporting tools, dev container configuration and Feature metadata are automatically stored in image labels. This makes your image self-contained and all settings will be automatically applied when the image is used. + +The metadata is stored in the `devcontainer.metadata` label as an array of JSON snippets: + +```json +[ + { + "remoteUser": "devcontainer", + "postCreateCommand": "npm install", + "features": { + "ghcr.io/devcontainers/features/node:1": { + "version": "18" + } + } + } +] +``` + +You can also manually add metadata to an image label in your Dockerfile: + +```dockerfile +LABEL devcontainer.metadata='[{ \ + "capAdd": [ "SYS_PTRACE" ], \ + "remoteUser": "devcontainer", \ + "postCreateCommand": "yarn install" \ +}]' +``` + +See the [Dev Container metadata reference](/implementors/json_reference) for information on which properties are supported in labels. + +## Best Practices + +When working with prebuilt images, follow these best practices: + +### Versioning + +- Use semantic versioning for your images (e.g., `v1.0.0`) +- Provide a `latest` tag for the most recent version +- Consider using date-based tags for regular builds (e.g., `20250512`) + +### Organization + +- Keep your build configuration in a separate repository from consumer projects +- Document the included tools and configurations +- Use continuous integration to build and test images regularly + +### Security + +- Rebuild images regularly to incorporate security updates +- Scan your images for vulnerabilities +- Use specific versions of base images rather than the `latest` tag +- Consider using multi-stage builds to reduce image size + +### Optimizing + +- Clean up package caches in your Dockerfile to reduce image size +- Group related RUN commands to reduce layer count +- Consider using [Features](/features) for modular functionality + +## Examples + +### Kubernetes Development + +The [kubernetes-devcontainer](https://github.com/craiglpeters/kubernetes-devcontainer) project maintains a prebuilt dev container image for Kubernetes development: + +```json +{ + "image": "ghcr.io/craiglpeters/kubernetes-devcontainer:latest" +} +``` + +### Language-specific Image + +The [devcontainers/images](https://github.com/devcontainers/images) repository maintains language-specific prebuilt images: + +```json +{ + "image": "mcr.microsoft.com/devcontainers/python:3" +} +``` + +## CI Integration + +Beyond local development, prebuilt dev container images provide consistency between development and CI environments. You can use the same container image for both: + +```yaml +name: CI Tests + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Run tests in Dev Container + uses: devcontainers/ci@v0.3 + with: + imageName: ghcr.io/your-org/your-image + runCmd: npm test +``` + +## References + +- [Dev Container CLI Reference](/implementors/reference#prebuilding) +- [In-depth guide on prebuilds](/guide/prebuild) +- [Using Images, Dockerfiles, and Docker Compose](/guide/dockerfile) +- [Dev Container metadata reference](/implementors/json_reference) +- [Dev Container Features](/features)