Docker images¶
Each Stackage LTS release has two corresponding docker images in the fpco/stack-build and 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. There is also a build.sh script to help with building and pushing the images (see the README 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 <N>.<M>
with the minor LTS snapshot version.
-
Check out the
stable
branch of the stack repo. -
Build and push the images (both standard and
small
variants) using the build.sh script:./build.sh --push lts-<N>.<M> && ./build.sh --push --small lts-<N>.<M>
.
Patch images for new minor LTS snapshot¶
Below, replace <N>.<M>
with the minor LTS snapshot version. and <N>.<M-1>
with the previous minor LTS snapshot version.
-
Check out the
stable
branch of the stack repo. -
In
stackage/automated/dockerfiles
, create a newlts-<N>.<M>
directory. -
Create
lts-<N>.<M>/Dockerfile
, starting with:FROM $DOCKER_REPO:lts-<N>.<M-1>
-
Add layers for any changes that need to be made to the image.
-
Build the new image using the build.sh script:
./build.sh lts-<N>.<M> && ./build.sh --small lts-<N>.<M>
-
Test the new image. For example,
(stack --resolver=lts-<N>.<M> 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 <N>
with major version of new LTS snapshot, and <N-1>
with previous major LTS snapshot version.
-
Check out the
stable
branch of the stack repo. -
In
stackage/automated/dockerfiles
, create a newlts-<N>.0
directory. -
Copy
lts-<N-1>.0/Dockerfile
tolts-<N>.0/Dockerfile
. -
Check the
FROM
statement, make sure the Ubuntu version matches the Ubuntu version used in the Stackage Dockerfile. -
Update
GHC_VERSION
to match the version used by the latest nightly snapshot. -
Set
LTS_SLUG
to the latest nightly snapshot (this will be temporary until the major LTS snapshot is actually released, at which point it will be updated tolts-<N>.0
). -
Update
PID1_VERSION
andSTACK_VERSION
to the latest versions of those tools. -
Make sure
CUDA_VERSION
andJVM_PATH
match what 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 inCLANG_PURE_LLVM_INCLUDE_DIR
in debian-bootstrap.sh (leaving off the/include
suffix). -
Update
BOOTSTRAP_COMMIT
to the git commit ID of the latest debian-bootstrap.sh. -
Check for any other
lts-<N>.*/Dockerfile
s and make surelts-<N>.0/Dockerfile
includes anything that was updated in those, if they're still relevant for LTS-15 (note that a newer 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-<N>.0/
. -
Ensure that all the directories listed in
PATH
,CUDA_PATH
, andCPATH
and any other path-like environment variables actually exist in the image. -
Try building a test package with the new image:
(stack --resolver=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:
docker build -t local/stack-build-small --build-arg "VARIANT=small" lts-<N>.0/
. -
Try building a test package with the new small image:
(stack --resolver=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
tolts-<N>.0
-
Update
BOOTSTRAP_COMMIT
to the git commit ID of the latest debian-bootstrap.sh. -
Repeat the tests above, except use
lts-<N>.0
instead ofnightly
. -
Build and push the real images (both standard and
small
variants) using the build.sh script:./build.sh --push lts-<N>.0 && ./build.sh --push --small lts-<N>.0
-
Commit and push the new Dockerfile to the
stable
branch.