From 9c3bdb4aec2af06b4332f166e93f075aa9d3b62e Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 17:53:10 +0000 Subject: [PATCH 01/14] refactor(docker): move compose file to root easier to interact with Docker Compose this way --- .devcontainer/devcontainer.json | 2 +- .devcontainer/compose.yml => compose.yml | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) rename .devcontainer/compose.yml => compose.yml (71%) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 68b8f47..ba9feb4 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,6 +1,6 @@ { "name": "compilerla/template-devcontainer", - "dockerComposeFile": ["compose.yml"], + "dockerComposeFile": ["../compose.yml"], "service": "dev", "runServices": ["dev", "docs"], "workspaceFolder": "/home/compiler/src", diff --git a/.devcontainer/compose.yml b/compose.yml similarity index 71% rename from .devcontainer/compose.yml rename to compose.yml index 774513e..efae428 100644 --- a/.devcontainer/compose.yml +++ b/compose.yml @@ -1,13 +1,13 @@ -name: compilerla/template-devcontainer +name: template-devcontainer services: dev: build: - context: .. + context: . dockerfile: .devcontainer/Dockerfile image: compilerla/template-devcontainer:main volumes: - - ../:/home/compiler/src + - ./:/home/compiler/src docs: image: compilerla/template-devcontainer:main @@ -16,4 +16,4 @@ services: ports: - "8000" volumes: - - ../:/home/compiler/src + - ./:/home/compiler/src From a6f67c1e9d3b5e0bce2384e798de50f81f8dbd92 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 17:57:46 +0000 Subject: [PATCH 02/14] refactor(devcontainer): update customizations syntax --- .devcontainer/devcontainer.json | 36 +++++++++++++---------- .devcontainer/devcontainer.pre-built.json | 36 +++++++++++++---------- 2 files changed, 40 insertions(+), 32 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index ba9feb4..d1f7668 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -5,21 +5,25 @@ "runServices": ["dev", "docs"], "workspaceFolder": "/home/compiler/src", "postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"], - // Set *default* container specific settings.json values on container create. - "settings": { - "terminal.integrated.defaultProfile.linux": "bash", - "terminal.integrated.profiles.linux": { - "bash": { - "path": "/bin/bash" - } + "customizations": { + "vscode": { + // Set *default* container specific settings.json values on container create. + "settings": { + "terminal.integrated.defaultProfile.linux": "bash", + "terminal.integrated.profiles.linux": { + "bash": { + "path": "/bin/bash" + } + } + }, + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "bpruitt-goddard.mermaid-markdown-syntax-highlighting", + "DavidAnson.vscode-markdownlint", + "eamodio.gitlens", + "esbenp.prettier-vscode", + "mhutchie.git-graph" + ] } - }, - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "bpruitt-goddard.mermaid-markdown-syntax-highlighting", - "DavidAnson.vscode-markdownlint", - "eamodio.gitlens", - "esbenp.prettier-vscode", - "mhutchie.git-graph" - ] + } } diff --git a/.devcontainer/devcontainer.pre-built.json b/.devcontainer/devcontainer.pre-built.json index 7bda4a7..06faa75 100644 --- a/.devcontainer/devcontainer.pre-built.json +++ b/.devcontainer/devcontainer.pre-built.json @@ -2,21 +2,25 @@ "name": "compilerla/template-devcontainer-pre-built", "image": "ghcr.io/compilerla/template-devcontainer:main", "postAttachCommand": "pre-commit install --overwrite", - // Set *default* container specific settings.json values on container create. - "settings": { - "terminal.integrated.defaultProfile.linux": "bash", - "terminal.integrated.profiles.linux": { - "bash": { - "path": "/bin/bash" - } + "customizations": { + "vscode": { + // Set *default* container specific settings.json values on container create. + "settings": { + "terminal.integrated.defaultProfile.linux": "bash", + "terminal.integrated.profiles.linux": { + "bash": { + "path": "/bin/bash" + } + } + }, + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "bpruitt-goddard.mermaid-markdown-syntax-highlighting", + "DavidAnson.vscode-markdownlint", + "eamodio.gitlens", + "esbenp.prettier-vscode", + "mhutchie.git-graph" + ] } - }, - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "bpruitt-goddard.mermaid-markdown-syntax-highlighting", - "DavidAnson.vscode-markdownlint", - "eamodio.gitlens", - "esbenp.prettier-vscode", - "mhutchie.git-graph" - ] + } } From 6321314d01ab34f7b414f23c1164a1fed4d70427 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 17:59:37 +0000 Subject: [PATCH 03/14] fix(devcontainer): git safe directory in postAttach --- .devcontainer/postAttach.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/.devcontainer/postAttach.sh b/.devcontainer/postAttach.sh index ba38c5d..2e748e6 100644 --- a/.devcontainer/postAttach.sh +++ b/.devcontainer/postAttach.sh @@ -2,4 +2,5 @@ set -eux # initialize pre-commit +git config --global --add safe.directory /home/$USER/src pre-commit install --overwrite From d798191602189593876c5ccb51a1e8a2d7f43839 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 11:06:40 -0700 Subject: [PATCH 04/14] feat(docker): update base image to python 3.11 make python version a build arg --- .devcontainer/Dockerfile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index e316fbc..9e34475 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,4 +1,6 @@ -FROM python:3.10 +ARG PYTHON_VERSION=3.11 + +FROM python:${PYTHON_VERSION} ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ From 511b551980e69f4340bdf353f59a4fe9908ba5bc Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 11:07:13 -0700 Subject: [PATCH 05/14] chore(docker): update env syntax --- .devcontainer/Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 9e34475..bb9e11e 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -17,7 +17,7 @@ USER $USER WORKDIR /home/$USER/src # update PATH for local pip installs -ENV PATH "$PATH:/home/$USER/.local/bin" +ENV PATH="$PATH:/home/$USER/.local/bin" # upgrade pip RUN python -m pip install --upgrade pip From 75418af8fd1219e66248b57048bda43d60ae0285 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 18:15:46 +0000 Subject: [PATCH 06/14] feat(ci): build multiple python version images 3.11 is the default --- .github/workflows/publish-devcontainer.yml | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/.github/workflows/publish-devcontainer.yml b/.github/workflows/publish-devcontainer.yml index d72a4fa..bb12954 100644 --- a/.github/workflows/publish-devcontainer.yml +++ b/.github/workflows/publish-devcontainer.yml @@ -13,12 +13,15 @@ defaults: jobs: publish: runs-on: ubuntu-latest + strategy: + matrix: + python-version: ["3.10", "3.11", "3.12"] steps: - name: Checkout uses: actions/checkout@v4 - - name: Docker Login to GitHub Container Registry + - name: Docker Login to GHCR uses: docker/login-action@v3 with: registry: ghcr.io @@ -29,16 +32,18 @@ jobs: id: buildx uses: docker/setup-buildx-action@v3 - - name: Build, tag, and push image to GitHub Container Registry + - name: Build, tag, and push image to GHCR [python ${{ matrix.python-version }}] uses: docker/build-push-action@v6 with: builder: ${{ steps.buildx.outputs.name }} - build-args: GIT-SHA=${{ github.sha }} + build-args: | + GIT-SHA=${{ github.sha }} + PYTHON_VERSION=${{ matrix.python-version }} cache-from: type=gha,scope=compilerla cache-to: type=gha,scope=compilerla,mode=max context: . file: .devcontainer/Dockerfile push: true tags: | - ghcr.io/${{ github.repository }}:${{ github.ref_name }} - ghcr.io/${{ github.repository }}:${{ github.sha }} + ${{ matrix.python-version == '3.11' && format('ghcr.io/{0}:main', github.repository) || format('ghcr.io/{0}:main_{1}', github.repository, matrix.python-version) }} + ${{ matrix.python-version == '3.11' && format('ghcr.io/{0}:{1}', github.repository, github.sha) || format('ghcr.io/{0}:{1}_{2}', github.repository, github.sha, matrix.python-version) }} From 4e68d7a145b5e787439ce085dd6a4ed503bf3adb Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 18:24:44 +0000 Subject: [PATCH 07/14] chore(docs): add mdx_truly_sane_lists extension --- docs/requirements.txt | 1 + mkdocs.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index c35ca8d..028622c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +mdx_truly_sane_lists mkdocs mkdocs-awesome-pages-plugin mkdocs-macros-plugin diff --git a/mkdocs.yml b/mkdocs.yml index 643f83c..546dd55 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,7 @@ markdown_extensions: - attr_list - codehilite: linenums: true + - mdx_truly_sane_lists - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg From 41de862e21dc804e1bfd087caf02c00477da3a50 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 18:32:30 +0000 Subject: [PATCH 08/14] docs: link to devcontainers blog post --- README.md | 4 ++++ docs/README.md | 2 ++ 2 files changed, 6 insertions(+) diff --git a/README.md b/README.md index 2e658d0..53a919c 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ A [template repository][template-repo] with a minimal [VS Code devcontainer][dev Read the full documentation online: +## Why? + +Read more in our blog post: [How to support a platform-agnostic engineering team with VS Code Dev Containers](https://compiler.la/blog/2024/devcontainer-platform-agnostic-team). + ## Features - Base Docker image `python:3.10` includes support for common dev tooling like `git`, `curl`, `pip`, and `pre-commit` diff --git a/docs/README.md b/docs/README.md index ef312cd..6642cc9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,6 +20,8 @@ Docs are built using [`mkdocs`](https://www.mkdocs.org/). This site is built usi In no particular order, here are some reasons Compiler likes to use devcontainers as part of our software engineering workflow: +_Read more in our blog post: [How to support a platform-agnostic engineering team with VS Code Dev Containers](https://compiler.la/blog/2024/devcontainer-platform-agnostic-team)_. + | Reason | More | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Cross-platform** | With only VS Code and Docker as dependencies, devcontainers allow developers on Linux, Mac, and Windows to work in a consistent environment, no matter the project's stack | From 5830bda6de90390cdde85fa856ba0ee0619f0df2 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 18:32:57 +0000 Subject: [PATCH 09/14] docs: update default python version --- README.md | 2 +- docs/features/devcontainer.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 53a919c..5247326 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Read more in our blog post: [How to support a platform-agnostic engineering team ## Features -- Base Docker image `python:3.10` includes support for common dev tooling like `git`, `curl`, `pip`, and `pre-commit` +- Base Docker image `python:3.11` includes support for common dev tooling like `git`, `curl`, `pip`, and `pre-commit` - Includes VS Code extensions like [`GitLens`][gitlens] and [`Prettier`][prettier] and good default settings for the editor - The [`pre-commit` configuration][pre-commit-config] includes a number of useful [`pre-commit-hooks`][pre-commit-hooks] and Compiler's [`conventional-pre-commit`][conventional-pre-commit] hook diff --git a/docs/features/devcontainer.md b/docs/features/devcontainer.md index 64dffa6..37e8e7a 100644 --- a/docs/features/devcontainer.md +++ b/docs/features/devcontainer.md @@ -24,7 +24,7 @@ The devcontainer's image is called `compilerla/template-devcontainer`. ### Base -The image is based on [`python:3.10`](https://hub.docker.com/_/python), to ease installation of common tooling like +The image is based on [`python:3.11`](https://hub.docker.com/_/python), to ease installation of common tooling like [`mkdocs`](docs.md) and [`pre-commit`](pre-commit.md). ### Setup From 5f2094322ce90e4b16beb92b2df021b9976208ea Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 18:33:46 +0000 Subject: [PATCH 10/14] docs: update list of recent devcontainer projects --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 6642cc9..8163e6d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,7 +39,7 @@ Some of our recent work built on the devcontainer pattern includes: - [`cal-itp/benefits`](https://github.com/cal-itp/benefits) (Python/Django web app) - [`cal-itp/eligibility-api`](https://github.com/cal-itp/eligibility-api) (Python API library) - [`cal-itp/eligibility-server`](https://github.com/cal-itp/eligibility-server) (Python/Flask API server) -- [`cal-itp/hashfields`](https://github.com/cal-itp/hashfields) (.NET core CLI tool) +- [`cal-itp/hashfields`](https://github.com/cal-itp/hashfields) (Python CLI tool) +- [`cal-itp/mobility-marketplace`](https://github.com/cal-itp/mobility-marketplace) (Jekyll static site) - [`compilerla/compiler.la`](https://github.com/compilerla/compiler.la) (Jekyll static site) - [`compilerla/conventional-pre-commit`](https://github.com/compilerla/conventional-pre-commit) (Python pre-commit hook) -- [`compilerla/intake-html-table`](https://github.com/compilerla/intake-html-table) (Python intake plugin) From 8ca3f3bed291aa20faabf6274ee2bcfbb87641db Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 18:34:55 +0000 Subject: [PATCH 11/14] docs: update note about apple silicon --- docs/usage/run-local.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/usage/run-local.md b/docs/usage/run-local.md index 59d6e6f..e452ee9 100644 --- a/docs/usage/run-local.md +++ b/docs/usage/run-local.md @@ -8,8 +8,7 @@ ### Docker -Docker is required; the easiest way to get Docker is by downloading and installing [Docker Desktop](https://www.docker.com/products/docker-desktop/) -for Linux, Mac (including M2!), and Windows. +Docker is required; the easiest way to get Docker is by downloading and installing [Docker Desktop](https://www.docker.com/products/docker-desktop/) for Linux, Mac (including Apple Silicon!) and Windows. ### VS Code From 0bf3bbde45d5b2e9e42a1d6e2ff41cf4391bc2ae Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 18:39:20 +0000 Subject: [PATCH 12/14] docs: update list of GHCR image tags --- docs/usage/reference-image.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/usage/reference-image.md b/docs/usage/reference-image.md index 2ad92a2..23cb16c 100644 --- a/docs/usage/reference-image.md +++ b/docs/usage/reference-image.md @@ -6,11 +6,17 @@ - **GHCR Packages:** [`compilerla/template-devcontainer`](https://github.com/compilerla/template-devcontainer/pkgs/container/template-devcontainer) - **Minimal devcontainer.json:** [`devcontainer.pre-built.json`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/devcontainer.pre-built.json) -`template-devcontainer` maintains a [GitHub Actions](https://github.com/features/actions) workflow that publishes the Docker -image to [GitHub Container Registry (GHCR)](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). +`template-devcontainer` maintains a [GitHub Actions](https://github.com/features/actions) workflow that publishes Docker +images to [GitHub Container Registry (GHCR)](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). -The publish is triggered for every push to the `main` branch, and the image tag `:main` always represents the latest commit on -that branch. +The publish is triggered for every push to the `main` branch, and multiple image tags are created: + +- `main` uses the default Python version of 3.11 +- `main_3.10` uses Python 3.10 +- `main_3.12` uses Python 3.12 + +There are also corresponding tags for the git SHA of the commit on `main` that triggered the build +(e.g. `sha`, `sha_3.10`, and `sha_3.12`). This makes the pre-built devcontainer image available for use in other projects, potentially decreasing startup and onboarding time even further. From c57883c2bffd25b8992feb4a0ebe063b46033964 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 12 Jul 2024 19:19:13 +0000 Subject: [PATCH 13/14] feat(github): add CODEOWNERS for engineering team --- .github/CODEOWNERS | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .github/CODEOWNERS diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..9afb1d5 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# default to engineering team +* @compilerla/engineering From 6008fc16d37d96b051747b404106f06ef4c33402 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Mon, 29 Jul 2024 23:24:33 +0000 Subject: [PATCH 14/14] feat(ci): build multi-platform images better support for engineers across Windows, Mac (incl Apple Silicon), and Linux --- .github/workflows/publish-devcontainer.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/publish-devcontainer.yml b/.github/workflows/publish-devcontainer.yml index bb12954..31df1fe 100644 --- a/.github/workflows/publish-devcontainer.yml +++ b/.github/workflows/publish-devcontainer.yml @@ -28,6 +28,9 @@ jobs: username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + - name: Set up Docker Buildx id: buildx uses: docker/setup-buildx-action@v3 @@ -43,6 +46,7 @@ jobs: cache-to: type=gha,scope=compilerla,mode=max context: . file: .devcontainer/Dockerfile + platforms: linux/amd64,linux/arm64 push: true tags: | ${{ matrix.python-version == '3.11' && format('ghcr.io/{0}:main', github.repository) || format('ghcr.io/{0}:main_{1}', github.repository, matrix.python-version) }}