# Docker images Each Stackage LTS release has two corresponding docker images in the [fpco/stack-build](https://hub.docker.com/r/fpco/stack-build/) and [fpco/stack-build-small](https://hub.docker.com/r/fpco/stack-build-small/) repositories. The former contains every system library needed to build any package in the snapshot, while the latter only contains a minimal set of system libraries for basic programs. The Dockerfiles for building these images are in [stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/). There is also a [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh) script to help with building and pushing the images (see the [README](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/README.md) for usage instructions). ## Build images for new minor LTS snapshot In most cases, a new minor LTS snapshot just needs the previous LTS image to be re-tagged and pushed. If the image needs a patch for the new minor LTS snapshot, see the next section. Below, replace `.` with the minor LTS snapshot version. - Check out the `stable` branch of the [Stack repository](https://github.com/commercialhaskell/stack/). - Build and push the images (both standard and `small` variants) using the [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh) script: ~~~text ./build.sh --push lts-. ./build.sh --push --small lts-. ~~~ ## Patch images for new minor LTS snapshot Below, replace `.` with the minor LTS snapshot version. and `.` with the previous minor LTS snapshot version. - Check out the `stable` branch of the [Stack repository](https://github.com/commercialhaskell/stack/). - In `stackage/automated/dockerfiles`, create a new `lts-.` directory. - Create `lts-./Dockerfile`, starting with: ~~~dockerfile FROM $DOCKER_REPO:lts-. ~~~ - Add layers for any changes that need to be made to the image. - Build the new image using the [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh) script: ~~~text ./build.sh lts-. ./build.sh --small lts-. ~~~ - Test the new image. For example, command: ~~~text stack --snapshot=lts-. new image-test cd image-test stack --docker build ~~~ This should use the image you just built. Make sure you test that the new image actually contains the desired changes. - Follow the process in the previous section to push the images. ## Build images for new major LTS snapshot release ### Test a Dockerfile prior to new major LTS snapshot release Replace `` with major version of new LTS snapshot, and `` with previous major LTS snapshot version. - Check out the `stable` branch of the [Stack repository](https://github.com/commercialhaskell/stack/). - In `stackage/automated/dockerfiles`, create a new `lts-.0` directory. - Copy `lts-.0/Dockerfile` to `lts-.0/Dockerfile`. - Check the `FROM` statement, make sure the Ubuntu version matches the Ubuntu version used in the [Stackage Dockerfile](https://github.com/commercialhaskell/stackage/blob/master/Dockerfile). - Update `GHC_VERSION` to match the version used by the [latest nightly snapshot](https://www.stackage.org/nightly). - Set `LTS_SLUG` to the [latest nightly snapshot](https://www.stackage.org/nightly) (this will be temporary until the major LTS snapshot is actually released, at which point it will be updated to `lts-.0`). - Update `PID1_VERSION` and `STACK_VERSION` to the latest versions of those tools. - Make sure `CUDA_VERSION` and `JVM_PATH` match what [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh) uses. - Update `LLVM_PATH` to the version required for the GHC version. This will be shown on the download page for the GHC version, which you can reach from https://www.haskell.org/ghc/. It should match the base directory used in `CLANG_PURE_LLVM_INCLUDE_DIR` in [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh) (leaving off the `/include` suffix). - Update `BOOTSTRAP_COMMIT` to the Git commit ID of the latest [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh). - Check for any other `lts-.*/Dockerfile`s and make sure `lts-.0/Dockerfile` includes anything that was updated in those, if they're still relevant for LTS-15 (note that a newer [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh) may already include those changes, so check there first). ### Perform basic tests - Build the image: `docker build -t local/stack-build lts-.0/`. - Ensure that all the directories listed in `PATH`, `CUDA_PATH`, and `CPATH` and any other path-like environment variables actually exist in the image. - Try building a test package with the new image. Command: ~~~text stack --snapshot=nightly new image-test` cd image-test stack --docker --docker-image=local/stack-build build ~~~ This should build without needing to install GHC. - Build the "small" variant. Command: ~~~text docker build -t local/stack-build-small --build-arg "VARIANT=small" lts-.0/ ~~~ - Try building a test package with the new small image. Command: ~~~text stack --snapshot=nightly new small-image-test cd small-image-test stack --docker --docker-image=local/stack-build-small build ~~~ This should build without needing to install GHC. ### Build real image once major LTS snapshot has been released - Update `LTS_SLUG` to `lts-.0` - Update `BOOTSTRAP_COMMIT` to the git commit ID of the latest [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh). - Repeat the tests above, except use `lts-.0` instead of `nightly`. - Build and push the real images (both standard and `small` variants) using the [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh) script: ~~~text ./build.sh --push lts-.0 ./build.sh --push --small lts-.0 ~~~ - Commit and push the new Dockerfile to the `stable` branch.