Choosing a Docker SDK version

This document describes why and how to select a particular version of the Docker SDK and use it in your project.

Why should I use a particular version of the Docker SDK?

You should use a particular Docker SDK version for:

• Compatibility: project configuration is compatible with the selected Docker SDK version.
• Consistency: the same Docker SDK version is used in development, integration, and deployment pipelines.
• Control: control when and how you switch the Docker SDK version of the project.
• Stability: avoid unexpected behavior in pipelines.

Choosing a versioning approach

To choose a versioning approach, consider the following:

• What kind of project do you have? For example, Long-term, short-term, production, demo.
• What will you use the Docker SDK for? For example, for development, operations, CI/CD management.
• Do you need to customize the Docker SDK?

Depending on your project requirements, choose one of the versioning approaches:

Configuring a project to use the chosen version of the Docker SDK

Depending on your project requirements, choose one of the following ways to configure a Docker SDK version:

• Git submodule:
  • To contribute in the Docker SDK.
  • To have a simple way to fetch a particular version of the Docker SDK.
  • To use the hash as a versioning approach.
• Reference file:
  • To use a branch as a versioning approach.
  • When Git Submodule is not supported.

Configuring git submodule

To configure git submodule:

1. Using a terminal, navigate to your project root folder. You can find the src/ directory and composer.json file there.

2. Create a git submodule:

git submodule add git@github.com:spryker/docker-sdk.git ./docker

3. Check out the local clone of the repository to a specific hash, branch, or tag:

cd docker
git checkout my-branch
cd ..

4. Commit and push:

git add .gitmodules docker
git commit -m "Added docker submodule"
git push

git add docker
git commit -m "Updated docker submodule"
git push

See 7.11 Git Tools - Submodules and git-submodule reference for more information about git submodule.

Using git submodule to stick to the chosen version

To fetch the chosen version of the Docker SDK, init or update the Docker SDK submodule:

git submodule update --init --force docker

Configuring a reference file

To configure a reference file:

1. Using a terminal, navigate to your project root folder. You can find the src/ directory and composer.json file there.

2. Create .git.docker in the project root.

3. Depending on the chosen versioning approach, add one of the following to the file:

4. Commit and push:

git add .git.docker
git commit -m "Added .git.docker"
git push

git add .git.docker
git commit -m "Updated .git.docker"
git push

Using a reference file to stick to the chosen version

Do the following to fetch the chosen version of the Docker SDK:

1. Clone the Docker SDK repository.
2. Read the reference from the file.
3. According to the reference, check out the local clone of the repository to the hash, branch, or tag.

An example of a pipeline to fetch the chosen version of the Docker SDK:

git clone git@github.com:spryker/docker-sdk.git .docker
cd docker
git checkout "$(cat ../.git.docker | tr -d '\n\r')"
cd ..

CI validation

If you’re using CI, we highly recommend you ensure that the reference and submodule hashes are matching.

The following is an example of what the code can look like:

- git submodule | grep docker | grep `cat .git.docker` || (echo "Installed submodule hash doesn't match the reference hash from .git.docker"; exit 1)