Skip to main content
Skip table of contents

Docker Image Requirements

OnFinality Requirements

For a Docker container to run on OnFinality the image must:

  • Have an entrypoint set with command to run the node daemon

  • The daemon must not be wrapped in a startup script

  • Avoid using tini


Besides the above, we advise you to read the following from :

Best Practice Automated Docker Deployment

From the official Substrate Node Template substrate-developer-hub/substrate-node-template


This should work with any image built off the standard Substrate Node Image, you will just need to replace the image metadata in the 2nd stage (e.g. image.vendor)


# This is an example build stage for the node template. Here we create the binary in a temporary image.

# This is a base image to build substrate nodes
FROM as builder

WORKDIR /node-template
COPY . .
RUN cargo build --locked --release

# This is the 2nd stage: a very small image where we copy the binary."
LABEL description="Multistage Docker image for Substrate Node Template" \
  image.type="builder" \
  image.authors="" \
  image.vendor="Substrate Developer Hub" \
  image.description="Multistage Docker image for Substrate Node Template" \
  image.source="" \

# Copy the node binary.
COPY --from=builder /node-template/target/release/node-template /usr/local/bin

RUN useradd -m -u 1000 -U -s /bin/sh -d /node-dev node-dev && \
  mkdir -p /chain-data /node-dev/.local/share && \
  chown -R node-dev:node-dev /chain-data && \
  ln -s /chain-data /node-dev/.local/share/node-template && \
  # unclutter and minimize the attack surface
  rm -rf /usr/bin /usr/sbin && \
  # check if executable works in this container
  /usr/local/bin/node-template --version

USER node-dev

EXPOSE 30333 9933 9944 9615
VOLUME ["/chain-data"]

ENTRYPOINT ["/usr/local/bin/node-template"]

Automated Docker Build

This is designed to work with the Dockerfile above. It will build a new image, then publish it to DockerHub and can be run as an automated GitHub action.

Most teams will trigger this either on a manual workflow, or when a new release is published. You will need to save the credentials for your DockerHub account in your GitHub secrets.

If you instead want to use another image repository (e.g. GitHub image registry), you can amend the Build and push Docker images step.


# This is an example GitHub action that will build and publish a Docker image to DockerHub
# You need to add the following secrets to your GitHub Repository or Organization to make this work
# - DOCKER_USERNAME: The username of the DockerHub account. E.g. parity
# The following are setup as an environment variable below
# - DOCKER_REPO: The unique name of the DockerHub repository. E.g. parity/polkadot

name: Build & Publish Docker Image

# Controls when the action will run.
  # Triggers the workflow on push events but only for the main branch
  # push:
    # branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
# Set an environment variable (that can be overriden) for the Docker Repo
  DOCKER_REPO: parity/polkadot

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
    # The type of runner that the job will run on
    runs-on: ubuntu-20.04

    # Steps represent a sequence of tasks that will be executed as part of the job
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - name: Check out the repo
        uses: actions/checkout@v2.5.0
      # Login to Docker hub using the credentials stored in the repository secrets
      - name: Log in to Docker Hub
        uses: docker/login-action@v2.1.0
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}
      # Get the commit short hash, to use as the rev
      - name: Calculate rev hash
        id: rev
        run: echo "value=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT

      # Build and push 2 images, One with the version tag and the other with latest tag
      - name: Build and push Docker images
        uses: docker/build-push-action@v3.2.0
          context: .
          push: true
          tags: ${{ env.DOCKER_REPO }}:v${{ steps.rev.outputs.value }}, ${{ secrets.DOCKER_REPO }}:latest

Automated OnFinality Network Spec Update

This can be combined with our automated deployment tooling to automatically publish a new version to OnFinality. We can add an additional step in the end that will push the new image version to an existing OnFinality Network Spec.


# You need to add the following secrets to your GitHub Repository or Organization to make this work
# OnFinality access credential instructions
# - ONF_ACCESS_KEY: The unique access key to OnFinality
# - ONF_SECRET_KEY: A secret access key to OnFinality
# - ONF_WORKSPACE_ID: The workspace ID of your OnFinality workspace, you can retrieve this from your workspace settings. E.g. 6683212593101979648
# - ONF_NETWORK_KEY: The network ID of your OnFinality workspace, you can retrieve this from the URL when viewing the network. E.g. f987705c-fe75-4069-99b4-77d62c4fe58k

      - name: Update image version of the existing network spec
        uses: "OnFinality-io/action-onf-release@v1"
          # These keys should be in your GitHub secrets
          onf-access-key: ${{ secrets.ONF_ACCESS_KEY }}
          onf-secret-key: ${{ secrets.ONF_SECRET_KEY }}
          onf-workspace-id: ${{ secrets.ONF_WORKSPACE_ID }}
          onf-network-key: ${{ secrets.ONF_NETWORK_KEY }}
          # Add a new image version to network spec
          onf-sub-command: image
          onf-action: add
          image-version: v${{ steps.rev.outputs.value }}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.