Skip to main content

TRG 4.06 - Notice for docker images

StatusCreatedPost-History
Draft04-May-2023Initial release

Why​

Due to legal constrains we need to annotate the released container images to make it clear that we do our best to provide good images for demo purposes, but we do not provide any legal guarantee. This has to be defined in a dedicated 'Notice for docker image' section in our repositories and on the respective image page on DockerHub.

Description​

There are a few properties and links, that must be present on each notice, but they do vary for each image and product. The minimum set of information is:

  • Link to the source of your base image (Container registry and GitHub if available)
  • Link to your product image on DockerHub
  • Link to your repository on GitHub
  • Direct link to the Dockerfile used to build your image
  • Link to LICENCE file in your repo as 'Project License' (make clear, that this is the PROJECT licence, not an image license)

The above information must be provided as dedicated Markdown file in your repository. It should be located next to the Dockerfile, that is used to build the image you are annotating. Provide a dedicated notice file for every image, that is published. It must be linked in your top-level README.md. Link all notice files, in case you publish multiple images.

The notice must follow a specific structure, starting with a specific headline, a reference to your image on DockerHub and information about your product. You can use the following example as a starting point. Remember to update the placeholders indicated by <> brackets.

## Notice for Docker image

DockerHub: [https://hub.docker.com/r/tractusx/<your-image>](https://hub.docker.com/r/tractusx/<your-image>)

Eclipse Tractus-X product(s) installed within the image:

__<your product name>__

- GitHub: https://github.com/eclipse-tractusx/<your-product-repo>
- Project home: https://projects.eclipse.org/projects/automotive.tractusx
- Dockerfile: https://github.com/eclipse-tractusx/<your-product-repo>/blob/main/<path-to-Dockerfile>
- Project license: [Apache License, Version 2.0](https://github.com/eclipse-tractusx/<your-product-repo>/blob/main/LICENSE)

The last bits of information you must provide is related to your used base image. As previously described, the following information should be provided, if available:

  • DockerHub links
  • GitHub repo
  • direct links to Dockerfile

The following example is taken from the IRS product:

**Used base image**

- [eclipse-temurin:20-jre-alpine](https://github.com/adoptium/containers)
- Official Eclipse Temurin DockerHub page: https://hub.docker.com/_/eclipse-temurin
- Eclipse Temurin Project: https://projects.eclipse.org/projects/adoptium.temurin
- Additional information about the Eclipse Temurin images: https://github.com/docker-library/repo-info/tree/master/repos/eclipse-temurin

Closing the notice, we provide a general statement about potentially contained other tools and the demo/experimental purpose of our images. We use the following text:

As with all Docker images, these likely also contain other software which may be under other licenses 
(such as Bash, etc. from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Best practice and examples​

  • Use "Container images" as headline to link to the container image notice files from the repositories README.md file
  • Name the notice file "notice.md"
  • Provide important information about your image with your notice. Examples:
    • Available volumes
    • Default port the service is listening on

GitHub workflow step​

Keeping the DockerHub description up-to-date with the latest notice content is crucial. The following workflow step can be used as part of the DockerHub publishing workflow to ensure that:

# DockerHub publishing worklflow

...

# https://github.com/peter-evans/dockerhub-description
- name: Update Docker Hub description
  # Ensure the DockerHub description is updated with contents from a PR (usually images are not published on PR)
  if: github.event_name != 'pull_request'
  uses: peter-evans/dockerhub-description@v3
  with:
    username: ${{ secrets.DOCKER_HUB_USER }}
    password: ${{ secrets.DOCKER_HUB_TOKEN }}
    repository: ${{ env.IMAGE_NAMESPACE }}/${{ env.IMAGE_NAME }}
    # IMPORTANT: Adjust this to the actual path of your container image notice
    readme-filepath: <path/to/your/notice.md>

Examples​

The following examples are shown as reference, to see already existing and complete versions of a 'Notice for docker images'. They can not be used for your product without modifications.

Already collected base image information​

The following sections contain information, that already has been collected on base images, that are used in Eclipse Tractus-X. You can use that information for your own notice. Be careful, when it comes to version, like JRE versions for example. You have to adapt some of the provided links to match your used version.

Eclipse Temurin (JRE)​

Nginx-unprivileged (serve static HTML and JS bundles)​

.NET runtime​

ASP.NET core runtime​

Linux​