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 repository. -
Build and push the images (both standard and
small
variants) using the build.sh script:
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 repository. -
In
stackage/automated/dockerfiles
, create a newlts-<N>.<M>
directory. -
Create
lts-<N>.<M>/Dockerfile
, starting with: -
Add layers for any changes that need to be made to the image.
-
Build the new image using the build.sh script:
-
Test the new image. For example, command:
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 repository. -
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. Command:
This should build without needing to install GHC.
-
Build the "small" variant. Command:
-
Try building a test package with the new small image. Command:
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: -
Commit and push the new Dockerfile to the
stable
branch.