Docker image improvements

.github/workflows/docker-image.yml

@@ -16,7 +16,11 @@ name: Build Docker
 
 on:
   push:
-    branches: [ "main" ]
+    branches:
+      - 'main'
+      - 'release/*'
+    tags:
+      - 'v*.*'
 
   # Can be run manually
   workflow_dispatch:
@@ -26,7 +30,7 @@ env:
   # Github runner is running out of space when we are building for multiple architectures in single runner
   BUILD_PLATFORMS: linux/amd64
   DOCKERHUB_REPO: ${{ github.repository }}
-  TAG_NAME: latest
+  REQUIRED_IDF_VERSION: v5.1.1
 
 jobs:
   build:
@@ -36,6 +40,24 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      # Depending on the branch/tag, set TAG_NAME (used when tagging the image).
+      #
+      # The following 3 steps cover the alternatives (tag, release branch, main branch):
+      - run: sudo rm -rf /usr/share/dotnet
+      - run: sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+      - name: Set variables (tags)
+        if: ${{ github.ref_type == 'tag' }}
+        run: |
+          echo "TAG_NAME=$GITHUB_REF_NAME" >> $GITHUB_ENV
+      - name: Set variables (release branches)
+        if: ${{ github.ref_type == 'branch' && startsWith(github.ref_name, 'release/') }}
+        run: |
+          echo "TAG_NAME=release-${GITHUB_REF_NAME##release/}" >> $GITHUB_ENV
+      - name: Set variables (main branch)
+        if: ${{ github.ref_type == 'branch' && github.ref_name == 'main' }}
+        run: |
+          echo "TAG_NAME=latest" >> $GITHUB_ENV
+
       # The following steps are the standard boilerplate from
       # https://github.com/marketplace/actions/build-and-push-docker-images
       - name: Checkout
@@ -55,5 +77,11 @@ jobs:
           context: tools/docker
           file: tools/docker/matter-builds
           push: true
-          tags: ${{ env.DOCKERHUB_REPO }}:${{ env.TAG_NAME }}
+          tags: |
+            ${{ env.DOCKERHUB_REPO }}:${{ env.TAG_NAME }}
+            ${{ env.DOCKERHUB_REPO }}:${{ env.TAG_NAME }}_idf_${{ env.REQUIRED_IDF_VERSION }}
           platforms: ${{ env.BUILD_PLATFORMS }}
+          build-args: |
+            ESP_MATTER_CLONE_URL=${{ github.server_url }}/${{ github.repository }}.git
+            ESP_MATTER_CHECKOUT_REF=${{ GITHUB_REF_NAME  }}
+            IDF_CHECKOUT_REF=${{ env.REQUIRED_IDF_VERSION }}

tools/docker/README.md

@@ -0,0 +1,25 @@
+# Espressif's SDK for Matter Docker Image
+
+This is a Docker image for the [Espressif's SDK for Matter (ESP-MATTER)](https://github.com/espressif/esp-matter). It is intended for building applications of ESP-IDF that uses Espressif's SDK for Matter, when doing automated builds.
+
+This image contains a copy of the Espressif's SDK for Matter, a copy of ESP-IDF and the required tools for Matter to build ESP-IDF projects that use Espressif's SDK for Matter.
+
+## Basic Usage
+
+Build a project located in the current directory using `idf.py build` command:
+
+```bash
+docker run --rm -v $PWD:/project -w /project espressif/esp-matter:latest idf.py build
+```
+## Building custom images
+
+The Dockerfile in Espressif's SDK for Matter repository provides several build arguments which can be used to customize the Docker image:
+
+These are the different build arguments that can be used:
+- ``ESP_MATTER_CLONE_URL``: URL of the repository to clone Espressif's SDK for Matter. Can be set to a custom URL when working with a fork of Espressif's SDK for Matter. Default is ``https://github.com/espressif/esp-matter.git``.
+- ``ESP_MATTER_CHECKOUT_REF``: If this argument is set to a non-empty value, the given ``ESP_MATTER_CHECKOUT_REF`` will be fetched and checkout. This argument can be set to a tag, a branch or the SHA of the specific commit to check out. Default is ``main``.
+
+You can also use build arguments to control the ESP-IDF download:
+- ``IDF_CLONE_URL``: URL of the repository to clone ESP-IDF from. Can be set to a custom URL when working with a fork of ESP-IDF. Default is ``https://github.com/espressif/esp-idf.git``.
+- ``IDF_CHECKOUT_REF``: If this argument is set to a non-empty value, the given ``ESP_MATTER_CHECKOUT_REF`` will be fetched and checkout. This argument can be set to a tag, a branch or the SHA of the specific commit to check out. Default is ``v5.1`` tag.
+- ``IDF_CLONE_SHALLOW``: If this argument is set to a non-empty value, ``--depth=1 --shallow-submodules`` arguments will be used when performing ``git clone``. This significantly reduces the amount of data downloaded and the size of the resulting Docker image. However, if switching to a different branch in such a "shallow" repository is necessary, an additional ``git fetch origin <branch>`` command must be executed first.

tools/docker/entrypoint.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -e
+
+source $IDF_PATH/export.sh
+source $ESP_MATTER_PATH/export.sh
+
+exec "$@"

tools/docker/matter-builds

@@ -1,12 +1,47 @@
 ARG VERSION=latest
-FROM connectedhomeip/chip-build-esp32:${VERSION} as build
+FROM ghcr.io/project-chip/chip-build:${VERSION} as build
+
+# Use IDF_CHECKOUT_REF to specify a tag, a branch or a specific commit ID.
+
+ARG IDF_CLONE_URL=https://github.com/espressif/esp-idf.git
+ARG IDF_CHECKOUT_REF=v5.1
+
+RUN set -x \
+    && mkdir -p /tmp/esp-idf \
+    && cd /tmp/esp-idf \
+    && git init \
+    && git remote add origin $IDF_CLONE_URL \
+    && git fetch origin --depth=1 --recurse-submodules ${IDF_CHECKOUT_REF} \
+    && git checkout FETCH_HEAD \
+    && git submodule update --init --recursive  --depth 1 \
+    && : # last line
+
+FROM ghcr.io/project-chip/chip-build:${VERSION}
+
+ENV IDF_PATH=/opt/espressif/esp-idf/
+ENV IDF_TOOLS_PATH=/opt/espressif/tools
+
+COPY --from=build /tmp/esp-idf /opt/espressif/esp-idf
+
+# Setup the ESP-IDF
+WORKDIR /opt/espressif/esp-idf
+RUN set -x \
+    && ./install.sh \
+    && : # last line
+
+ARG ESP_MATTER_CLONE_URL=https://github.com/espressif/esp-matter.git
+ARG ESP_MATTER_CHECKOUT_REF=main
 
 WORKDIR /opt/espressif
 ENV ESP_MATTER_PATH=/opt/espressif/esp-matter
 
 RUN set -x \
-    && git clone --depth 1 https://github.com/espressif/esp-matter.git \
-    && cd esp-matter \
+    && mkdir -p $ESP_MATTER_PATH \
+    && cd $ESP_MATTER_PATH \
+    && git init \
+    && git remote add origin $ESP_MATTER_CLONE_URL \
+    && git fetch origin --depth=1 ${ESP_MATTER_CHECKOUT_REF} \
+    && git checkout FETCH_HEAD \
     && git submodule update --init --depth 1 \
     && cd ./connectedhomeip/connectedhomeip \
     && ./scripts/checkout_submodules.py --platform esp32 linux --shallow \
@@ -15,4 +50,8 @@ RUN set -x \
     && ./install.sh \
     && : # last line
 
+COPY entrypoint.sh /opt/esp/entrypoint.sh
+ENTRYPOINT [ "/opt/esp/entrypoint.sh" ]
+CMD [ "/bin/bash" ]
+
 WORKDIR /opt/espressif/esp-matter