README: Instructions on construction of new MRtrix3 tag

[Lestropie]

Using this PR to set up the plan for how this repo should be updated whenever there is a new MRtrix3 tag.

What I'm planning currently is:

• On MRtrix3/containers:master, Dockerfile will always checkout MRtrix3/mrtrix3:master, and so manual construction of a container based on the master branch here will always result in the most up-to-date stable version of MRtrix3.

• For every unique MRtrix3 tag, there should be:

  • A corresponding MRtrix3/containers tag, which, when utilised, is hard-coded to always checkout the corresponding MRtrix3 tag.

  • An image on DockerHub with the corresponding tag.

These instructions are intended to reach that result. However I have a couple of other issues to raise before pushing a 3.0.2 image to the MRtrix3 DockerHub repo and announcing.

[kaczmarj]

It might be possible to use automated builds on DockerHub in conjuction with build hooks to build images, set tags, and distribute via DockerHub. The build hooks are bash scripts, and perhaps we could query for the available mrtrix3 tags and build (and name) a Docker image accordingly. I have never done this, but there are helpful examples online, like this blog post and this GitHub repo.

[Lestropie]

Automated builds would indeed be good. I had one slight concern with that sort of approach, which maybe I should have discussed in order to justify why I added the gymnastics I did. They're not necessarily one-and-the-same though, so I'll just explain my thinking and we'll see where we end up.

Let's say that this repo contains only a master branch and no tags. On an MRtrix3 tag update, the relevant black magic occurs such that, at some point shortly thereafter, an image appears on DockerHub with the equivalent tag, that includes all of the dependencies and configuration as specified in this repo at the moment said black magic occurred. This happens for a few MRtrix3 tag updates in sequence, with each new image in turn potentially including new versions of external software dependencies or changes to recipe configuration.

Now some time in the far future, somebody wants to reproduce an experiment that was done e.g. using the MRtrix 3.0.2 container. The problem then is that neither the MRtrix3 repository nor this repository would explicitly state the version of the container recipe that was utilised in construction of the container in conjunction with MRtrix 3.0.2. The image would hopefully still be there on DockerHub, along with the recipe file used to generate it, but the MRtrix3 team would be relying on a third party to retain that version history.

For this reason, I wanted a workflow that would result in an explicit tag on this repository corresponding to each MRtrix3 tag, each of which would explicitly reference the corresponding MRtrix3 tag in the container recipe.

---

In fact, writing this out, I'm wondering if the solution is to walk back on our prior decision regarding having Dockerfile in a separate repository. If specifically Dockerfile were to be in the main MRtrix3 repository, and the MRTRIX3_GIT_COMMITISH environment variable were to be updated at the relevant location in the publishing a new release wiki instructions, then the version of the container recipe at the point of each tag would be there embedded within the repository. This repository could still be used, but for generating the minified external dependency tarballs only. I might raise this in our next team meeting.

[kaczmarj]

In fact, writing this out, I'm wondering if the solution is to walk back on our prior decision regarding having Dockerfile in a separate repository.

I agree completely. To be reproducible, it would be ideal in my opinion to have the Dockerfile in the mrtrix3 repository. That is why I initially created https://github.com/MRtrix3/mrtrix3/pull/1372. There would be no MRTRIX3_GIT_COMMITISH either -- the current source code would be copied into the Docker image, and the Dockerfile would be stored in version control.

[Lestropie]

There would be no MRTRIX3_GIT_COMMITISH either -- the current source code would be copied into the Docker image, and the Dockerfile would be stored in version control.

While true for the container that is built on DockerHub (as long as the image recipe doesn't wipe cmd/ / core/ / src/ after building), it would mean that if someone were to:

git checkout -b 3.0.2 git@github.com:MRtrix3/mrtrix3
docker build . -t mrtrix3

, it would use the recipe from 3.0.2, but the actual version of MRtrix3 downloaded and built within that local image would in fact be the master branch, which will no longer correspond to 3.0.2 at some point in the future. Therefore if someone were to do the above commands in the future, they'd end up with a version of MRtrix3 other than what they requested. Unless I'm overlooking something (wouldn't be the first time :roll_eyes: :rofl: ), hard-coding the MRtrix3 tag in the recipe file feels like the more robust long-term solution to me.

[Lestropie]

Given MRtrix3/mrtrix3#2279, these instructions no longer belong in this repository, but should instead be principally reflected in the relevant Wiki page on the primary MRtrix3 repository.