This is the source for creating the nextstrain/base Docker image. Currently
the image is published as nextstrain/base.
Ideally most pathogen builds are supported by this base image without further customization. The possibility remains, however, for pathogens to define and use an image derived from this base layer. This would be desirable for pathogen builds requiring custom external software, like Python modules or tree-builders.
The image includes the standard Nextstrain components Fauna, Augur, and Auspice, as well as other bioinformatics tools like MAFFT, RAxML, FastTree, IQ-TREE, and TreeTime.
This image is best interacted with using the Nextstrain command-line tool.
To rebuild the image with the latest versions of its software and push to Docker Hub, go to the GitHub Actions workflow, select Run workflow, and confirm.
This is most helpful when you want the image to contain the latest version of a tool whose release does not automatically trigger a new build of the image and you do not need to modify the Dockerfile.
To build this image locally, first pull down the latest image from Docker Hub:
./devel/pull
This will save you time by taking advantage of layer caching. Then build the image with:
./devel/build
On each subsequent change during your development iterations, you can run just
the ./devel/build command again.
If you need to force the cached Nextstrain layers to rebuild to, for example,
pick up a new version of augur or auspice, set the CACHE_DATE environment
variable to a new timestamp first:
export CACHE_DATE=$(date --utc +%Y%m%dT%H%M%SZ)
Otherwise, letting the build process use the cached layers will save you time during development iterations.
To push images you've built locally to Docker Hub, you can run:
./devel/push latest
This will publish your local nextstrain/base:latest image. This is also what
happens if you run ./devel/push with no tags specified. If you have images
with other tags, you may provide those tags in addition to or instead of
latest.
The smaller the image size, the better. To this end we build upon a "slim" Python image and use a multi-stage build where only artifacts are included in the final image without any of the software required only for compiling, installing, building, etc.
Try to follow Docker best practices for images, although not all apply to our use case, which is somewhat atypical.
The Dockerfile reference documentation is quite handy for looking up the
details of each Dockerfile command (COPY, ADD, etc).
Every push to this repository triggers a new build of the image [a GitHub Actions workflow][]. This helps ensure the image builds successfully with the new commits.
Images built from the master branch are additionally pushed to the Docker
registry. The build instructions used by the workflow are in
this repo's .github/workflows/ci.yml.