Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/into-docker/into-docker
Never write another Dockerfile
https://github.com/into-docker/into-docker
best-practices builder-image docker multi-stage s2i
Last synced: about 2 months ago
JSON representation
Never write another Dockerfile
- Host: GitHub
- URL: https://github.com/into-docker/into-docker
- Owner: into-docker
- License: mit
- Created: 2020-04-04T13:22:54.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-10-18T10:49:11.000Z (about 1 year ago)
- Last Synced: 2024-08-01T00:41:06.839Z (5 months ago)
- Topics: best-practices, builder-image, docker, multi-stage, s2i
- Language: Clojure
- Homepage:
- Size: 413 KB
- Stars: 85
- Watchers: 4
- Forks: 5
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# into-docker
[](https://spiceprogram.org)
[](https://github.com/into-docker/into-docker/releases/latest)
[](https://github.com/into-docker/into-docker/actions?query=workflow%3ACI)
[](https://codecov.io/gh/into-docker/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`][s2i] and shares some concepts, ideas and goals.
However, it targets one specific use case, the classic
[multi-stage][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!
[whitepaper]: doc/WHITEPAPER.md
## Demo
[](https://asciinema.org/a/450632)
## 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][oci] and automatic
application of [ignore rules][di].
- **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][homebrew]:
```sh
brew install into-docker/brew/into-docker
```
All releases can be found on the [Releases][releases] page.
[homebrew]: https://brew.sh
[releases]: https://github.com/into-docker/into-docker/releases
## Usage
Make sure to have [docker engine][docker-engine] running on your machine!
[docker-engine]: https://docs.docker.com/engine/install/
### 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:
```sh
into build -t []
```
Learn how to [create your own builder image][builder-images] or check out
[existing builder images][gh-builder-images] on Github.
[gh-builder-images]: https://github.com/topics/into-docker-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:
```sh
into build -t -p
```
Learn how to [add build profiles to your builder image][build-profiles].
### 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.
```sh
into build -t --cache
```
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.
```sh
into build -t --incremental
```
Learn how to [add caching to your builder image][builder-caching].
### 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:
```sh
into build --write-artifacts []
```
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:
```sh
echo "SECRET_PASSWORD" > ".buildenv"
export SECRET_PASSWORD=12345
into build ...
```
You can read about the mechanism (and the rationale) in the
[WHITEPAPER][buildenv].
### Platforms
If you're [targeting multiple platforms][docker-arch] or platforms different
from your build machine, you can use the `--platform` CLI options:
```sh
into build -t --platform linux/arm64
```
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][platforms] for more insights.
[di]: https://codefresh.io/docker-tutorial/not-ignore-dockerignore-2/
[oci]: https://github.com/opencontainers/image-spec/blob/master/annotations.md
[s2i]: https://github.com/openshift/source-to-image
[multi-stage]: https://docs.docker.com/develop/develop-images/multistage-build/
[builder-images]: doc/WHITEPAPER.md#builder-images
[build-profiles]: doc/WHITEPAPER.md#build-profiles
[builder-caching]: doc/WHITEPAPER.md#caching
[buildenv]: doc/WHITEPAPER.md#user-provided-environment-variables
[platforms]: doc/WHITEPAPER.md#platforms
[docker-arch]: https://docs.docker.com/desktop/multi-arch/
## 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](https://github.com/marketplace/actions/into-docker)
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-2023 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.
```