diff --git a/.github/workflows/release-debug.yml b/.github/workflows/release-debug.yml new file mode 100644 index 0000000..17dc9d1 --- /dev/null +++ b/.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}" \ No newline at end of file diff --git a/README.md b/README.md index 475ea2b..05ca5da 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,50 @@ docker compose stop bitcoin You can check the bootstrap process with the `hc.sh` script. `./hc ` +# 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: --pid=container: \ + 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=` (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 -m "" +git push origin +``` + # Logs ``` diff --git a/docker-compose-testnet.yml b/docker-compose-testnet.yml index 32d5a09..3ac5361 100644 --- a/docker-compose-testnet.yml +++ b/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: diff --git a/docker-compose.yml b/docker-compose.yml index d86591d..d49a5d2 100644 --- a/docker-compose.yml +++ b/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: diff --git a/images/debug/Dockerfile b/images/debug/Dockerfile new file mode 100644 index 0000000..9acd16e --- /dev/null +++ b/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"] \ No newline at end of file diff --git a/images/debug/build.sh b/images/debug/build.sh new file mode 100755 index 0000000..128da07 --- /dev/null +++ b/images/debug/build.sh @@ -0,0 +1 @@ +docker build -t flarefoundation/distroless-debug:1.0.0 .