Simple python library for building docker images.
Switch branches/tags
1.6.23.x 343-align-commits-and-branch-names 424-more-metadata add_filesystem/gather_platforms allow-implicit-latest-tag arrangement-6-fixes autopub_fix autopublish build-resource-limits check_and_set_rebuild/from_latest compare-pkg-whitelist debug-import-image debug/non-x86_64-single-arch dest-registries-org docker-build-error-reporting dockpulp-new-certs-api dont-fail-when-base-image-has-wrong-metadata email_log enhance-compose-error-msg fix-koji-import-str-type fix-log-level-run-exit-plugin fix/logger-in-locked-pulp-repo fix/update-labels force-explicit-tags hotfix/odcs-arches image-name-enclose import_image/fix-docker-image-repo improve-nfs increase-pulp-timeout input_osv3/fix-pulp_push-removal isolated_kp isolated_meta koji-ssl-auth-cleanup koji_upload/optional-params master mmilata-next next no-force-remove no-log-password non-amd64-build oc-dockerbuild odcs-integration orchestrate_build/optional-platforms owner2 parentcg perf/push_to_pulp plugin_refactor plugin_refactor2 prevent-repo-name-collision pulp-pull-workaround reactor-config-mixins reactor_config/koji-path-info registry-delete release_1.6.24 release_1.6.25 release_1.6.26 release_1.6.27 release_1.6.28 release_1.6.29 release_1.6.30 release_1.6.31 release_1.6.32 release_1.6.33 release_1.6.34 release_1.6.35 release_1.6.36 resolve_composes/module-support retries retries3 retry_log revert-748-master rpmqa/check-and-retry-run-output scratch-builds source-registry-org support-basic-auth-osv3-plugin tag-and-push-http-registry test-plugin-failure test/steve tests/disable-rawhide tox use-correct-content-sets utf8-logs validate-base-image-manifest-list
Nothing to show
Clone or download
mlangsdorf custom base images: return early from plugins that can't handle them
add a utility function to detect a custom base image and stash whether
the base image is a custom base in the Builder.

In pre_add_filesystem, check if the base image is a custom base and
return immediately if it isn't.  In the other 4 plugins, return
immediately if the base image is a custom base image.

Signed-off-by: Mark Langsdorf <>
Latest commit e8294b8 Nov 28, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
atomic_reactor custom base images: return early from plugins that can't handle them Dec 7, 2018
docs flatpak_create_dockerfile: allow overriding the name and com.redhat.c… Nov 12, 2018
images Move to using flatpak-module-tools as a library Aug 16, 2018
rel-eng Fix rel-eng/packages/atomic-reactor May 5, 2017
tests custom base images: return early from plugins that can't handle them Dec 7, 2018
.coveragerc Add coverage config file Jul 6, 2016
.flake8 Add .flake8 file so that Stickler CI would know about agreed settings May 5, 2017
.gitignore add resurrection, EXTRA_MOUNT, htmlcov Jun 4, 2018
.landscape.yml Add a .landscape.yml to add checks in Python 3 mode May 22, 2016
.pylintrc pylint: disable score reporting Oct 24, 2018
.stickler.yml Configure Stickler-CI Aug 25, 2017
.travis.yml Travis: add install section Oct 24, 2018 Update development environment setup Oct 18, 2018
Dockerfile Add plugins for Flatpak creation Sep 14, 2017
LICENSE Remove the remaining mentions of dock Oct 29, 2015 Add new reactor_config pre-build plugin Feb 20, 2017 Add code quality badges Oct 18, 2018
atomic-reactor.spec Fix RPM spec file bogus dates Dec 6, 2018
requirements-devel.txt Update development environment setup Oct 18, 2018
requirements-flatpak.txt Get module information from Koji instead of the PDC Sep 7, 2018
requirements-py2.txt Create post_compress plugin, fixes #191 Jul 28, 2015
requirements.txt from scratch base image Nov 20, 2018 release Nov 22, 2018 Drop integration-tests dir Oct 24, 2018

Atomic Reactor

Build Status Code Health Coverage Status Code Quality: Python Total Alerts

Python library with command line interface for building docker images.


  • push image to registry when it's built
  • build inside a docker container (so your builds are separated between each other)
  • git as a source to your Dockerfile (you may specify commit/branch and path to Dockerfile within the git repo)
  • collect build logs
  • integration with koji build system
  • integration with fedora packaging system
  • inject arbitrary yum repo inside Dockerfile (change source of your packages)
  • retag base image so it matches FROM instruction in Dockerfile
  • change base image (FROM) in your Dockerfile
  • run simple tests after your image is built

There are several build modes available:

  • building within a docker container using docker from host by mounting docker.sock inside the container
  • building within a privileged docker container (new instance of docker is running inside)
  • executing build within current environment


for Fedora users

$ sudo dnf install atomic-reactor python-atomic-reactor-koji

from git

Clone this git repo and install Atomic Reactor using python installer:

$ git clone
$ cd atomic-reactor
$ sudo pip install .

You don't even need to install it. You may use it straight from git:

$ alias atomic-reactor="python ${REACTOR_PATH}/atomic-reactor/cli/"


  • docker-py.
  • koji plugin requires koji package, which is not available on PyPI: you have to install it manually:
$ sudo dnf install koji


If you would like to build your images within build containers, you need to obtain images for those containers. We call them build images. Atomic Reactor is installed inside and used to take care of build itself.

You can either get the build image from Dockerhub or create it yourself.

getting build image from Dockerhub

Just use

$ docker pull slavek/atomic-reactor

This will pull the buildroot image with the latest Atomic Reactor commits. Images with stable releases are available since version 1.3.3 and you can access them by using the version specifier as a tag, such as

$ docker pull slavek/atomic-reactor:1.3.3

installation from git

$ atomic-reactor create-build-image --reactor-local-path ${PATH_TO_REACTOR_GIT} ${PATH_TO_REACTOR_GIT}/images/dockerhost-builder buildroot

Why is it so long? Okay, let's get through. First thing is that Atomic Reactor needs to install itself inside the build image. You can pick several sources for Atomic Reactor: your local copy, (this) official upstream repo, your forked repo or even distribution tarball. In the example above, we are using our locally cloned git repo (--reactor-local-path ${PATH_TO_REACTOR_GIT}).

You have to provide Dockerfile too. Luckily these are part of upstream repo (see folder images). It's the first argument: ${PATH_TO_REACTOR_GIT}/images/dockerhost-builder.

And finally, you need to name the image: buildroot.

installation from RPM

$ atomic-reactor create-build-image --reactor-tarball-path /usr/share/atomic-reactor/atomic-reactor.tar.gz /usr/share/atomic-reactor/images/dockerhost-builder buildroot-fedora

Section above contains detailed description. Let's make this short.

  1. --reactor-tarball-path — Atomic Reactor needs to install itself into build image: this is how you specify where Atomic Reactor gets its own sources (when installed via RPM, Atomic Reactor provides itself packaged as tarball at /usr/share/atomic-reactor/atomic-reactor.tar.gz)
  2. first argument is path do dockerfile — dockerfiles for both methods are available at /usr/share/atomic-reactor/images/, just pick one
  3. and finally, second argument names the build image

getting Atomic Reactor from distribution

Or you can build the image using docker and install Atomic Reactor directly from distribution:

FROM fedora:latest
RUN dnf -y install docker-io git python-docker-py python-setuptools koji atomic-reactor && dnf clean all
CMD ["atomic-reactor", "-v", "inside-build", "--input", "path"]

and command:

$ docker build -t buildroot-hostdocker .

And now you can build your images!

As soon as our build image is built, we can start building stuff in it:

$ atomic-reactor build git --method hostdocker --build-image buildroot-hostdocker --image test-image --uri ""

The built image will be in the build container. Therefore, this example doesn't make much sense. If you would like to access the built image, you should probably push it to your registry and build it like this:

$ atomic-reactor build git --method hostdocker \
             --build-image buildroot-hostdocker \
             --image test-image \
             --target-registries \
             --uri ""

Both of these examples use the git source provider (atomic-reactor build git), which gets the source code to put in the image from a git repo. There are also other providers:

  • path - uses source code from local path
  • json - accepts a path to build json file with all info needed for build

IP address should be address of docker0 network interface. Update it if yours is different. Also, don't forget to start the registry.

Bear in mind that you shouldn't mix build methods. If you use hostdocker method with build image for privileged method, then it won't work.

Further reading


Get in touch with us via mailing list.