Add debug containers for distroless containers

.github/workflows/release-debug.yml

@@ -0,0 +1,126 @@
+name: Release debugging image
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+on:
+  push:
+    branches: [ "main" ]
+    tags: [ "*" ]
+    paths: [ "images/debug/**" ]
+  pull_request:
+    branches: [ "main" ]
+    paths: [ "images/debug/**" ]
+
+env:
+  # Use docker.io for Docker Hub if empty
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/distroless-debug
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      # This is used to complete the identity challenge
+      # with sigstore/fulcio when running outside of PRs.
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Get image tag
+        id: get_image_tag
+        run: |
+          VERSION=$(grep "^ARG VERSION=" images/debug/Dockerfile \
+            | cut -d'=' -f2 \
+            | tr -d '"' \
+            | tr -d "'" \
+            | tr -d [:space:])
+          echo $VERSION
+          echo "image_tag=${VERSION}" >> $GITHUB_OUTPUT
+
+      # Install the cosign tool except on PR
+      # https://github.com/sigstore/cosign-installer
+      - name: Install cosign
+        if: github.event_name != 'pull_request'
+        uses: sigstore/cosign-installer@59acb6260d9c0ba8f4a2f9d9b48431a222b68e20 #v3.5.0
+        with:
+          cosign-release: 'v2.5.3'
+
+      # Set up BuildKit Docker container builder to be able to build
+      # multi-platform images and export cache
+      # https://github.com/docker/setup-buildx-action
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226 # v3.0.0
+
+      # Login against a Docker registry except on PR
+      # https://github.com/docker/login-action
+      - name: Log into registry ${{ env.REGISTRY }}
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Extract metadata (tags, labels) for Docker
+      # https://github.com/docker/metadata-action
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@96383f45573cb7f253c731d3b3ab81c87ef81934 # v5.0.0
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          # tag image with version specified in ARG VERSION in Dockerfile if event is a push
+          # or with given tag if event is tag
+          tags: |
+            type=semver,pattern={{version}},value=${{ steps.get_image_tag.outputs.image_tag }},enable=${{ github.event_name == 'push' && startsWith(github.ref, 'refs/heads/') }}
+            type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'main') }}
+            type=ref,event=tag,enable=${{ startsWith(github.ref, 'refs/tags/') }}
+          flavor: |
+            latest=false
+
+      # Build and push Docker image with Buildx (don't push on PR)
+      # https://github.com/docker/build-push-action
+      - name: Build and push Docker image
+        id: build-and-push
+        uses: docker/build-push-action@0565240e2d4ab88bba5387d719585280857ece09 # v5.0.0
+        with:
+          context: images/debug
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      # Sign the resulting Docker image digest except on PRs.
+      # This will only write to the public Rekor transparency log when the Docker
+      # repository is public to avoid leaking data.  If you would like to publish
+      # transparency data even for private images, pass --force to cosign below.
+      # https://github.com/sigstore/cosign
+      - name: Sign the published Docker image
+        if: ${{ github.event_name != 'pull_request' }}
+        env:
+          # https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable
+          TAGS: ${{ steps.meta.outputs.tags }}
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        # This step uses the identity token to provision an ephemeral certificate
+        # against the sigstore community Fulcio instance.
+        run: echo "${TAGS}" | xargs -I {} cosign sign --yes {}@${DIGEST}
+
+      - name: Verify ghcr image signatures
+        if: ${{ github.event_name != 'pull_request' }}
+        shell: bash
+        env:
+          COSIGN_EXPERIMENTAL: 1
+          TAGS: ${{ steps.meta.outputs.tags }}
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        run: |
+          echo "${TAGS}" | xargs -I {} cosign verify \
+          --certificate-identity=https://github.com/${{ github.repository }}/.github/workflows/release-debug.yml@${{ github.ref }} \
+          --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
+          "{}@${DIGEST}"

README.md

@@ -75,6 +75,50 @@ docker compose stop bitcoin
 
 You can check the bootstrap process with the `hc.sh` script. `./hc <your-provided-password>`
 
+# Debugging
+
+Distroless images do not contain a shell to run commands for debugging. Sidecar debug containers, attached to the main container through shared namespaces, need to be used.
+
+Attaching a debug container:
+```
+docker run \
+  --rm -it --privileged \
+  --net=container:<node-name> --pid=container:<node-name> \
+  ghcr.io/flare-foundation/connected-chains-docker/distroless-debug:1.0.0
+```
+
+Example commands:
+```
+# attach to running bitcoin node's namespaces
+# and open an interactive terminal
+docker run \
+  --rm -it --privileged \
+  --net=container:bitcoin --pid=container:bitcoin \
+  ghcr.io/flare-foundation/connected-chains-docker/distroless-debug:1.0.0
+
+# show processes of main and debug container
+ps aux
+
+# show contents of PID 1 (main container process) root directory
+ls -lha /proc/1/root/
+
+# show contents of bitcoin node directory
+ls -lha /proc/1/root/opt/bitcoin/
+```
+
+Add tools by specifying them in `./images/debug/Dockerfile` or use your own debugging image.
+
+## Releasing debug image with Github Actions
+
+Commits to main with changes to `images/debug/**` context will automatically trigger a rebuild and push of image, with tag sourced from `ARG VERSION=<semver>` (suffixes and prefix 'v' allowed) in Dockerfile. 
+
+For development purposes, you can also trigger the pipeline with a custom tag like so (the commit still needs to have made changes to `images/debug/**` context):
+
+```
+git tag -a <tag-name> -m "<message>"
+git push origin <tag-name>
+```
+
 # Logs
 
 ```

docker-compose-testnet.yml

@@ -1,5 +1,6 @@
 services:
   bitcoin:
+    container_name: bitcoin
     image: flarefoundation/bitcoin:29.0
     restart: on-failure:3
     environment:
@@ -12,6 +13,7 @@ services:
       - ./config-testnet/bitcoin/bitcoin.conf:/opt/bitcoin/.bitcoin/bitcoin.conf
 
   litecoin:
+    container_name: litecoin
     image: flarefoundation/litecoin:0.21.4
     restart: on-failure:3
     environment:
@@ -24,6 +26,7 @@ services:
       - ./config-testnet/litecoin/litecoin.conf:/opt/litecoin/.litecoin/litecoin.conf
 
   dogecoin:
+    container_name: dogecoin
     image: flarefoundation/dogecoin:1.14.9
     restart: on-failure:3
     environment:
@@ -36,6 +39,7 @@ services:
       - ./config-testnet/dogecoin/dogecoin.conf:/opt/dogecoin/.dogecoin/dogecoin.conf
 
   rippled:
+    container_name: rippled
     image: flarefoundation/rippled:2.5.0
     restart: on-failure:3
     environment:
@@ -53,6 +57,7 @@ services:
       - ./config-testnet/ripple/validators.txt:/opt/ripple/.ripple/validators.txt
 
   algorand:
+    container_name: algorand
     image: flarefoundation/algorand:4.1.2
     restart: on-failure:3
     ports:

docker-compose.yml

@@ -1,5 +1,6 @@
 services:
   bitcoin:
+    container_name: bitcoin
     image: flarefoundation/bitcoin:29.0
     restart: on-failure:3
     environment:
@@ -11,6 +12,7 @@ services:
       - ./config/bitcoin/bitcoin.conf:/opt/bitcoin/.bitcoin/bitcoin.conf
 
   litecoin:
+    container_name: litecoin
     image: flarefoundation/litecoin:0.21.4
     restart: on-failure:3
     environment:
@@ -22,6 +24,7 @@ services:
       - ./config/litecoin/litecoin.conf:/opt/litecoin/.litecoin/litecoin.conf
 
   dogecoin:
+    container_name: dogecoin
     image: flarefoundation/dogecoin:1.14.9
     restart: on-failure:3
     environment:
@@ -33,6 +36,7 @@ services:
       - ./config/dogecoin/dogecoin.conf:/opt/dogecoin/.dogecoin/dogecoin.conf
 
   rippled:
+    container_name: rippled
     image: flarefoundation/rippled:2.5.0
     restart: on-failure:3
     environment:
@@ -50,6 +54,7 @@ services:
       - ./config/ripple/validators.txt:/opt/ripple/.ripple/validators.txt
 
   algorand:
+    container_name: algorand
     image: flarefoundation/algorand:4.1.2
     restart: on-failure:3
     ports:

images/debug/Dockerfile

@@ -0,0 +1,20 @@
+# syntax=docker/dockerfile:1.3-labs
+FROM debian:12@sha256:b6507e340c43553136f5078284c8c68d86ec8262b1724dde73c325e8d3dcdeba as final
+
+ARG VERSION=v1.0.0
+
+RUN apt-get update && apt-get install -y \
+    curl \
+    jq \
+    procps \
+    netcat-openbsd \
+    tcpdump \
+    strace \
+    net-tools \
+    iproute2 \
+    vim \
+    nano \
+    less \
+    tree
+
+ENTRYPOINT ["/bin/bash"]

images/debug/build.sh

@@ -0,0 +1 @@
+docker build -t flarefoundation/distroless-debug:1.0.0 .