Prerequisites

Ensure that you have Go installed on your machine and properly set up. The project relies on several Go modules, so make sure your Go environment is configured correctly. Ensure you have the Docker CLI installed if you intend to work with Docker-related functionalities.

Clone the Repository

First, clone the repository to your local machine:

git clone https://github.com/docker/docker-credential-helpers.git
cd docker-credential-helpers

Build the Project

You can build the project using the provided Makefile, which includes several useful commands. To execute the build command, use:

make build

This command will compile the project using the Go build system. The output binaries will be placed in the current directory.

Running Tests

Before starting the project, it is advised to run tests to ensure everything is functioning correctly. You can do this by executing the following command:

make test

If all tests pass, you can proceed to start the project.

Building Binaries for Different Platforms

If you need to cross-compile for different operating systems, you can use the make cross command. For example, to build binaries for macOS, Linux, and Windows, run:

make cross

This will generate binaries for each target platform, allowing you to run the credential helpers on multiple systems.

Clean Up

Before starting, it might be useful to clean up any previous builds. Use the following command:

make clean

This will remove all binaries and any intermediary files created during the build process.

Starting the Project

This project itself does not run as a standalone application, as it provides credential storage helpers for Docker. However, you can start using the binaries generated from the build process with Docker. For example, if you built a credential helper (say macOS Keychain), you can test it with Docker by setting the credStore option in your Docker configuration file.

Here’s how to do that:

1. Edit or create the Docker configuration file located at ~/.docker/config.json.

2. Add the following configuration:

{
  "credHelpers": {
    "registry.example.com": "osxkeychain"
  }
}

Replace registry.example.com with your actual registry URL and osxkeychain with the appropriate credential helper you built.

After setting this up, Docker will use the specified credential helper the next time you authenticate against the given registry.

Validating the Build

To ensure that your build adheres to the project’s style guidelines, you can run the validation command:

make validate

This will check for common issues and ensure that the code follows the intended formatting and style.

Release Build

If you are preparing a release version of your credential helpers, use the following command to create the release binaries:

make release

This will prepare the binaries and package them appropriately, ready for distribution.

Additional Makefile Functions

The Makefile provides several additional functions that can be useful in various development scenarios:

make fmt        # Format the code with gofmt
make lint       # Run linter checks
make deb        # Build a Debian package
make osxkeychain  # Build the osxkeychain credential helper
make wincred    # Build the Windows credential helper
make pass       # Build the pass credential helper
make secretservice # Build the Secret Service credential helper

Utilize these commands as necessary based on your specific needs and environment.

Conclusion

Follow these steps to build and start using the docker/docker-credential-helpers project effectively in your development environment. Ensure that you refer back to the functionalities in the Makefile for additional commands that can streamline your development process.

Source: Makefile