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!
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.
Usage
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.
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.
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.
Use 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:
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 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.