gecko-dev/testing/docker
Ralph Giles c3d36f874d Bug 1289605 - Update gecko-rust-build to v0.3.0. r=dustin
- Separate build, package, and upload steps into separate scripts.
- Rewrite repack in python to use rust's internal install scripts.
- Add support for cargo as well as the rust compiler and std library.

MozReview-Commit-ID: EI9M8ayEptA

--HG--
extra : rebase_source : 4457c074396e5c733158d304c2aebe0f811a9d7e
2016-07-26 14:49:09 -07:00
..
android-gradle-build Bug 1275409: move legacy taskcluster-related scripts to taskcluster/scripts; r=wcosta 2016-06-04 22:57:41 +00:00
b2g-build Bug 1274765: Upgrade mercurial on docker images. r=garndt 2016-05-23 10:45:00 +02:00
base-build
base-test Bug 1237987 - Update mulet mochitests to use tester image r=wcosta 2016-01-08 11:26:28 -06:00
builder Bug 1284447 - Cleanup Gecko and mozharness configs r=jlund,wcosta 2016-07-05 13:10:08 +02:00
centos6-build Backed out changeset 66c7af8b2654 (bug 1272629) for failing valgrind tests 2016-07-22 08:35:19 +02:00
centos6-build-upd Backed out changeset 66c7af8b2654 (bug 1272629) for failing valgrind tests 2016-07-22 08:35:19 +02:00
decision Bug 1247168 - Tag and use version 0.1.2 of the decision image; r=dustin 2016-07-21 11:32:07 -07:00
desktop-build Backed out changeset 66c7af8b2654 (bug 1272629) for failing valgrind tests 2016-07-22 08:35:19 +02:00
desktop-l10n Bug 1248713 - add docker container for l10n repacks r=catlee DONTBUILD 2016-03-04 13:30:59 -05:00
desktop-test Bug 1281179 - Create a docker image for Ubuntu 16.04 for use in tests. r=dustin 2016-07-25 10:44:37 -04:00
desktop1604-test Bug 1281179 - Create a docker image for Ubuntu 16.04 for use in tests. r=dustin 2016-07-25 10:44:37 -04:00
image_builder Bug 1275276 - Fail if image context cannot be downloaded r=jhford 2016-05-24 08:57:18 -05:00
lint Bug 1247168 - Add a script to perform a checkout then run a command; r=dustin 2016-07-21 14:57:37 -07:00
phone-builder Backed out changeset 320ee1117179 (bug 1284005) for gecko-decision task failures. 2016-07-07 00:16:45 -04:00
recipes Bug 1247168 - Add a script to perform a checkout then run a command; r=dustin 2016-07-21 14:57:37 -07:00
rust-build Bug 1289605 - Update gecko-rust-build to v0.3.0. r=dustin 2016-07-26 14:49:09 -07:00
tester Bug 1275409: move legacy taskcluster-related scripts to taskcluster/scripts; r=wcosta 2016-06-04 22:57:41 +00:00
tester-device Bug 1225461 - [tc-gip] test_login_bzlite.py is failing because of missing configuration r=garndt 2016-01-13 15:08:56 +01:00
ubuntu1204-test Bug 1280178 - Update desktop-test images to node 5.0.0. r=dustin 2016-06-28 20:50:28 +09:00
ubuntu1204-test-upd Bug 1280178 - Update desktop-test images to node 5.0.0. r=dustin 2016-06-28 20:50:28 +09:00
ubuntu1604-test Bug 1281179 - Create a docker image for Ubuntu 16.04 for use in tests. r=dustin 2016-07-25 10:44:37 -04:00
README.md Bug 1223123 - Enable pulse_audio for Linux64 TC desktop jobs + proper window manager. r=dustin 2015-11-25 14:56:02 -05:00
REGISTRY
build.sh Bug 1237740 - Fix build.sh error message typo. r=wcosta DONTBUILD 2016-01-07 12:41:00 -08:00

README.md

Docker Images for use in TaskCluster

This folder contains various docker images used in taskcluster as well as other misc docker images which may be useful for hacking on gecko.

Organization

Each folder describes a single docker image. We have two types of images that can be defined:

  1. Task Images (build-on-push)
  2. Docker Images (prebuilt)

These images depend on one another, as described in the FROM line at the top of the Dockerfile in each folder.

Images could either be an image intended for pushing to a docker registry, or one that is meant either for local testing or being built as an artifact when pushed to vcs.

Task Images (build-on-push)

Images can be uploaded as a task artifact, indexed under a given namespace, and used in other tasks by referencing the task ID.

Important to note, these images do not require building and pushing to a docker registry, and are build per push (if necessary) and uploaded as task artifacts.

The decision task that is run per push will determine if the image needs to be built based on the hash of the context directory and if the image exists under the namespace for a given branch.

As an additional convenience, and a precaution to loading images per branch, if an image has been indexed with a given context hash for mozilla-central, any tasks requiring that image will use that indexed task. This is to ensure there are not multiple images built/used that were built from the same context. In summary, if the image has been built for mozilla-central, pushes to any branch will use that already built image.

To use within an in-tree task definition, the format is:

image:
  type: 'task-image'
  path: 'public/image.tar'
  taskId: '{{#task_id_for_image}}builder{{/task_id_for_image}}'
Context Directory Hashing

Decision tasks will calculate the sha256 hash of the contents of the image directory and will determine if the image already exists for a given branch and hash or if a new image must be built and indexed.

Note: this is the contents of only the context directory, not the image contents.

The decision task will:

  1. Recursively collect the paths of all files within the context directory
  2. Sort the filenames alphabetically to ensure the hash is consistently calculated
  3. Generate a sha256 hash of the contents of each file.
  4. All file hashes will then be combined with their path and used to update the hash of the context directory.

This ensures that the hash is consistently calculated and path changes will result in different hashes being generated.

Task Image Index Namespace

Images that are built on push and uploaded as an artifact of a task will be indexed under the following namespaces.

  • docker.images.v1.{project}.{image_name}.latest
  • docker.images.v1.{project}.{image_name}.pushdate.{year}.{month}-{day}-{pushtime}
  • docker.images.v1.{project}.{image_name}.hash.{context_hash}

Not only can images be browsed by the pushdate and context hash, but the 'latest' namespace is meant to view the latest built image. This functions similarly to the 'latest' tag for docker images that are pushed to a registry.

Docker Registry Images (prebuilt)

Deprecation Warning: Use of prebuilt images should only be used for base images (those that other images will inherit from), or private images that must be stored in a private docker registry account. Existing public images will be converted to images that are built on push and any newly added image should follow this pattern.

These are images that are intended to be pushed to a docker registry and used by specifying the folder name in task definitions. This information is automatically populated by using the 'docker_image' convenience method in task definitions.

Example: image: {#docker_image}builder{/docker_image}

Each image has a version, given by its VERSION file. This should be bumped when any changes are made that will be deployed into taskcluster. Then, older tasks which were designed to run on an older version of the image can still be executed in taskcluster, while new tasks can use the new version.

Each image also has a REGISTRY, defaulting to the REGISTRY in this directory, and specifying the image registry to which the completed image should be uploaded.

Building images

Generally, images can be pulled from the registry rather than built locally, however, for developing new images it's often helpful to hack on them locally.

To build an image, invoke build.sh with the name of the folder (without a trailing slash):

./build.sh base

This is a tiny wrapper around building the docker images via docker build -t $REGISTRY/$FOLDER:$FOLDER_VERSION

Note: If no "VERSION" file present in the image directory, the tag 'latest' will be used and no registry user will be defined. The image is only meant to run locally and will overwrite any existing image with the same name and tag.

On completion, if the image has been tagged with a version and registry, build.sh gives a command to upload the image to the registry, but this is not necessary until the image is ready for production usage. Docker will successfully find the local, tagged image while you continue to hack on the image definitions.

Adding a new image

The docker image primitives are very basic building block for constructing an "image" but generally don't help much with tagging it for deployment so we have a wrapper (./build.sh) which adds some sugar to help with tagging/versioning... Each folder should look something like this:

  - your_amazing_image/
    - your_amazing_image/Dockerfile: Standard docker file syntax
    - your_amazing_image/VERSION: The version of the docker file
      (required* used during tagging)
    - your_amazing_image/REGISTRY: Override default registry
      (useful for secret registries)

Conventions

In some image folders you will see .env files these can be used in conjunction with the --env-file flag in docker to provide a environment with the given environment variables. These are primarily for convenience when manually hacking on the images.

You will also see a system-setup.sh script used to build the image. Do not replicate this technique - prefer to include the commands and options directly in the Dockerfile.