into-docker

into-docker lets you build and run applications relying on common frameworks or build tools without ever having to write another Dockerfile. It allows you to bundle up your build environments and processes for others to reuse.

This tool is inspired by s2i and shares some concepts, ideas and goals. However, it targets one specific use case, the classic multi-stage build where artifacts are created in a fat build environment before being injected into a leaner runner environment.

Check out the whitepaper for more details!

Demo

Goals

• Minimum-configuration builds: Rather than providing infinite ways to configure your builds, we encourage the use of defaults and rely on convention over configuration when creating builder images.
• Promote best practices: Instead of creating a multitude of Docker images of varying quality, developers can benefit from the work of the community in a non-copy/paste fashion. This includes image labels and automatic application of ignore rules.
• Reproducible builds: By packaging your build environment as a Docker image, it can be versioned just like your source code. The same builder image should, given a specific set of inputs, always produce the same output.
• Small footprint: Images created by this tool will only differ in one layer from the base image, reducing bandwidth usage when pushing and pulling similar images.
• Compliance: As maintainer of a build platform you can curate a list of official build environments. Not only do platform users no longer have to write their own Dockerfile - they easily benefit from updates and patches to the build environment.
• Control the execution environment: Everything above also applies to runner images, allowing platform users to benefit from improvements to the execution environment while complying with regulations and best practices.

Installation

Using Homebrew:

brew install into-docker/brew/into-docker

All releases can be found on the Releases page.

Usage

Make sure to have docker engine running on your machine!

Run Build

To build local sources using an into-docker builder image use the build command and supply the desired target image name and tag:

into build -t <name:tag> <builder> [<path>]

Learn how to create your own builder image or check out existing builder images on Github.

Build Profiles

Builder images can supply multiple build profiles to allow for fine-tuning of the build process. This could, for example, allow you to use the same builder image for your React application whether you're relying on npm or yarn.

You can choose a build profile using the -p/--profile command line argument:

into build -t <name:tag> -p <profile> <builder>

Learn how to add build profiles to your builder image.

Caching

Repeated builds of the same codebase can usually be sped up by caching intermediate build results like downloaded dependencies. By default, into runs a fresh build each time but by supplying the --cache command line argument a cache archive (tar+gzip) will be created at the desired path.

into build -t <name:tag> --cache <path> <builder>

Subsequent builds will use the archive (if it exists) to seed the builder container.

Alternatively, you can rely on a Docker volume for caching. This is an experimental feature and most useful for iterating on builds locally. Note that you'll be responsible yourself for cleaning up the volume.

into build -t <name:tag> --incremental <builder>

Learn how to add caching to your builder image.

Build Artifacts

An into-docker build consists of two stages: build and assemble. To access the artifacts created by the build stage you can write them to a path of your choice using the --write-artifacts flag:

into build --write-artifacts <target-path> <builder> [<path>]

If you omit the -t/--tag flag, only the artifacts will be created, no Docker image.

Secrets (experimental)

When using e.g. private artifact registries, passing environment variables to your build tooling is usually the best way to provide credentials. To do this with into-docker, create a file .buildenv in your source directory that contains the names of the variables you want to pass.

When running a build, those values will be imported from your shell's environment and made available to the build script:

echo "SECRET_PASSWORD" > ".buildenv"
export SECRET_PASSWORD=12345
into build ...

You can read about the mechanism (and the rationale) in the WHITEPAPER.

Platforms

If you're targeting multiple platforms or platforms different from your build machine, you can use the --platform CLI options:

into build -t <name:tag> --platform linux/arm64 <builder>

By default, this will only impact the target image - the build itself will be run on your host's platform. You can use the environment variable DOCKER_DEFAULT_PLATFORM to adapt the builder container's platform. Check out the WHITEPAPER for more insights.

Usage on CI

Due to the minimal-configuration approach of into-docker, it can be easily used on the CI environment of your choice. Check out the following pre-packaged build steps:

• Github Actions

Use the --ci flag to direct the CLI tool to use CI-specific assumptions when building images. This allows you, for example, to use environment variables to fill image labels.

Check out the into.build.ci namespace if you want to add more environments.

License

MIT License

Copyright (c) 2020-2021 Yannick Scherer

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.