{{ load:.config/docs/readme/header.md }}

A Docker-in-Docker container for testing with ContainerStructureTest and GitLab Runner

Table of Contents

• Overview
• Requirements
  • Development Requirements
• Example Usage
  • Integrating with GitLab CI
  • Building the Docker Container
  • Building a Slim Container
  • Build Tools

Overview

Utilizing Continuous Integration (CI) tools can improve developer efficiency drastically. They allow you to do things like scan new code for possible errors and automatically deploy new software.

This repository is home to the build instructions for a Docker container that is just one piece to the CI puzzle. Nearly all of our CI pipeline Docker projects serve a single purpose.

Instead of using one of the countless pretty_name public Docker images available, we create it in-house so we know exactly what code is present in the container. We also ensure that all of our CI pipeline images are as small as possible so that our CI environment can download and run the specific task as quickly as possible. Using this repository as a base, you too can easily create your own in-house CI pipeline container image.

At first glance, you might notice that there are many files in this repository. Nearly all the files and folders that have a period prepended to them are development configurations. The tools that these files and folders configure are meant to make development easier and faster. They are also meant to improve team development by forcing developers to follow strict standards so that the same design patterns are used across all of our repositories.

Requirements

• Docker

Development Requirements

• DockerSlim - Used for generating compact, secure images
• jq - Used for interacting with JSON
• Node.js (>=14.18) - Utilized to add development features like a pre-commit hook and maintenance tasks
• Many more requirements that are dynamically installed as they are needed by our Taskfile.yml via our custom go-task/task fork named Bodega

If you choose to utilize the development tools provided by this project then at some point you will have to run bash start.sh (or npm i which calls bash start.sh after it is done). The start.sh script will attempt to automatically install any requirements (without sudo) that are not already present on your build system to the user's ~/.local/bin folder. The start.sh script also takes care of other tasks such as generating the documentation by calling tasks defined in the Taskfile.yml. For more details on how the optional requirements are used and set up, check out the CONTRIBUTING.md guide.

When you are ready to start development, run task --menu to open an interactive dialog that will help you understand what build commands we have already engineered for you.

Example Usage

There are several different ways you can use the Docker container provided by this project. For starters, you can test the feature out locally by running:

1docker run -v ${PWD}:/work -w /work megabytelabs/docker-test:preferred_tag docker_command

This allows you to run pretty_name without installing it locally. This could be good for security since the application is within a container and also keeps your file system clean.

You can also add a bash alias to your ~/.bashrc file so that you can run the pretty_name command at any time. To do this, add the following snippet to your ~/.bashrc file (or ~/.bash_profile if you are on macOS):

1docker_command_alias() {
2  docker run -v ${PWD}:/work -w /work megabytelabs/docker-test:preferred_tag "$@"
3}

Note: Some CLI tools run without any arguments passed in. For example, the CLI tool ansible-lint runs by simply entering ansible-lint in the terminal. Our Docker images default command is to show the version so to get around this quirk you would run ansible-lint ..

Integrating with GitLab CI

The main purpose of this project is to build a Docker container that can be used in CI pipelines. For example, if you want to incorporate this CI pipeline tool into GitLab CI project then your first step would be to create a .gitlab-ci.yml file in the root of your repository that is hosted by GitLab. Your .gitlab-ci.yml file should look something like this:

1---
2stages:
3  - lint
4
5include:
6  - remote: https://gitlab.com/megabyte-space/gitlab-ci-templates/-/raw/master/docker-test.gitlab-ci.yml

That is it! pretty_name will now run anytime you commit code (that matches the parameters laid out in the remote: file above). Ideally, for production, you should copy the source code from the remote: link above to another location and update the remote: link to the file's new location. That way, you do not have to worry about any changes that are made to the remote: file by our team.

Building the Docker Container

You may have a use case that requires some modifications to our Docker image. After you make changes to the Dockerfile, you can upload your custom container to Docker Hub using the following code:

1export DOCKERHUB_USERNAME=Your_DockerHub_Username_Here
2export DOCKERHUB_PASSWORD=Your_DockerHub_Password_Here
3docker login -u "$DOCKERHUB_USERNAME" -p "$DOCKERHUB_PASSWORD" docker.io
4docker build --pull -t "$DOCKERHUB_USERNAME/docker-test:latest" .
5docker push "$DOCKERHUB_USERNAME/docker-test:latest"

After setting your DockerHub username and password, the commands above will build the Docker image and upload it to Docker Hub where it will be publicly accessible. You can see this logic being implemented as a GitLab CI task here. This GitLab CI task works in conjunction with the .gitlab-ci.yml file in the root of this repository.

Building a Slim Container

Some of our repositories support creating a slim build via DockerSlim. According to DockerSlim's GitHub page, slimming down containers reduces the final image size and improves the security of the image by reducing the attack surface. It makes sense to create a slim build for anything that supports it, including Alpine images. On their GitHub page, they report that some images can be reduced in size by up to 448.76X. This means that if your image is naturally 700MB then it can be reduced to 1.56MB! It works by removing everything that is unnecessary in the container image.

This repository, however, is not currently configured to build a slim build. If you think you can improve this container by making it smaller and more secure by utilizing DockerSlim, please check out our CONTRIBUTING.md guide and open a pull request. Once you come up with the options for the slim build, place them in .blueprint.json under the key "dockerslim_command" and then run bash .start.sh. When .start.sh is run, it will add useful build commands to the package.json file and even regenerate this README to reflect the fact that the repository houses a slim build. You can find an example of a repository that houses a slim build by checking out our Updater container.

Build Tools

You might notice that we have a lot of extra files considering that this repository basically boils down to a single Dockerfile. These extra files are meant to make team development easier, predictable, and enjoyable. If you have a recent version of Node.js installed, you can get started using our build tools by running npm i (or by running bash start.sh if you do not currently have Node.js installed) in the root of this repository. After that, you can run task --list to see a list of the available development features. Alternatively, you can run task --menu to view an interactive menu that will guide you through the development process.

Note: We use a custom-built version of go-task/task so if you already have it installed then you should either replace it with our version or use a different bin name for task.

For more details, check out the CONTRIBUTING.md file.

{{ load:.config/docs/readme/contributing-details.md }} {{ load:.config/docs/readme/license.md }}