The top level folder with the docker files is release. This should only have folders under it. The three folders are:

• stable - Images for the current stable release of PowerShell Core.
• preview - Images for the current preview release of PowerShell Core.
• community-stable - Images for the current release of PowerShell Core that are not officially supported.

Under each of these, will be a folder for each image. The name of the folder will be the name of the image in the build system, but does not translate into anything in docker. For example, the stable Ubuntu 16.04 image is in release/stable/ubuntu16.04. In this folder, there are 4 items:

• docker - a folder containing the Dockerfile to build the image and any other files needed in the Docker build context
• meta.json - This is required for Linux images. It should contain the following:

{
    "IsLinux" : true,
    "tagTemplates": [
        "my-tag",
        "my-other-tag"
    ]
}

Tags are a JSON array that describes the tags the image should have.

Tags you can use:

• #psversion# is replaced by the version of PowerShell used to build the image.
• #tag# is replaced by all tags generated by the getLatestTag.ps1 script.
• #shorttag# is replaced by short tags generated by the getLatestTag.ps1 script.
• #longtag# is replaced by long tags generated by the getLatestTag.ps1 script.

Example

"tagTemplates": [
    "#psversion#-windowsservercore-#tag#",
    "windowsservercore-#tag#"
]

• getLatestTag.ps1 - This script should use the Get-DockerTags command from tools\getDockerTags to get the tags that should be used as the tag in the FROM statement in the Dockerfile.

The Dockerfile should follow certain standards:

• The following comments should be applied at the beginning of the dockerfile to all images:

  • Copyright notice
  • Software license
  • A brief description should be applied after a new line.

  For example:

# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.
#
# Docker image file that describes a brief description of the image to describe
# this image

• All arguments should be defaulted if needed to successfully build without specifying the argument

• The FROM statement should use an argument.

  For example:

ARG fromTag=16.04

FROM ubuntu:${fromTag}

• A PS_VERSION argument should be defined, and used wherever the version is needed.

  For example:

ARG PS_VERSION=6.0.4

• An IMAGE_NAME argument should be defined, and used in the labels where the image name is needed.

  For example:

ARG IMAGE_NAME=mcr.microsoft.com/powershell:ubuntu16.04

• A VCS_REF argument should be defined, and used wherever the git commit hash is needed.

  For example:

ARG VCS_REF="none"

• The following labels should be applied to all images:

LABEL maintainer="PowerShell Team <powershellteam@hotmail.com>" \
      readme.md="https://github.com/PowerShell/PowerShell/blob/master/docker/README.md" \
      description="This Dockerfile will install the latest release of PowerShell." \
      org.label-schema.usage="https://github.com/PowerShell/PowerShell/tree/master/docker#run-the-docker-image-you-built" \
      org.label-schema.url="https://github.com/PowerShell/PowerShell/blob/master/docker/README.md" \
      org.label-schema.vcs-url="https://github.com/PowerShell/PowerShell-Docker" \
      org.label-schema.name="powershell" \
      org.label-schema.vendor="PowerShell" \
      org.label-schema.vcs-ref=${VCS_REF} \
      org.label-schema.version=${PS_VERSION} \
      org.label-schema.schema-version="1.0" \
      org.label-schema.docker.cmd="docker run ${IMAGE_NAME} pwsh -c '$psversiontable'" \
      org.label-schema.docker.cmd.devel="docker run ${IMAGE_NAME}" \
      org.label-schema.docker.cmd.test="docker run ${IMAGE_NAME} pwsh -c Invoke-Pester" \
      org.label-schema.docker.cmd.help="docker run ${IMAGE_NAME} pwsh -c Get-Help"

You should not have to write any specific tests for your image, but you should consider if it needs to be added to the CI system.

The CI definition is here at vsts-ci.yml.

Here is a template for an image build job:

- template: .vsts-ci/phase.yml
  parameters:
    name: insertImageNameHere
    imagename: insertImageNameHere
    stable: false
    preview: false
    communityStable: true
    continueonerror: false