Setting up a Project Atomic host

6 min read

With DockerTM, containers are becoming mainstream and enterprises are ready to use them. Docker and its ecosystem are evolving at a very high pace, so it is very important to understand the basics and build group up to adopt to new concepts and tools.

In this article, we will cover the following recipes:

  • Setting up a Project Atomic host
  • Doing atomic update/rollback with Project Atomic

(For more resources related to this topic, see here.)

Setting up a Project Atomic host

Project Atomic facilitates application-centric IT architecture by providing an end-to-end solution to deploy containerized applications quickly and reliably, with atomic update and rollback for the application and host alike.

This is achieved by running applications in containers on a Project Atomic host, which is a lightweight operating system specially designed to run containers. The hosts can be based on Fedora, CentOS, or Red Hat Enterprise Linux.

Next, we will elaborate on the building blocks of the Project Atomic host.

  • OSTree and rpm-OSTree

    OSTree ( is a tool to manage bootable, immutable, and versioned filesystem trees. Using this, we can build client-server architecture in which the server hosts an OSTree repository and the client subscribed to it can incrementally replicate the content.

    rpm-OSTree is a system to decompose RPMs on the server side into the OSTree repository to which the client can subscribe and perform updates. With each update, a new root is created, which is used for the next reboot. During updates, /etc is rebased and /var is untouched.

  • Container runtime

    As of now Project Atomic only supports Docker as container runtime.

  • systemd

    Project Atomic uses Kubernetes ( for application deployment over clusters of container hosts. Project Atomic can be installed on bare metal, cloud providers, VMs, and so on. In this recipe, let’s see how we can install it on a VM using virt-manager on Fedora.

Getting ready

  1. Download the image:
    $ wget

    I have downloaded the beta image for Fedora 22 Cloud image For Containers. You should look for the latest cloud image For Containers at

  2. Uncompress this image by using the following command:
    $ xz -d Fedora-Cloud-Atomic-22_Beta-20150415.x86_64.raw.xz

How to do it…

  • We downloaded the cloud image that does not have any password set for the default user fedora. While booting the VM, we have to provide a cloud configuration file through which we can customize the VM. To do this, we need to create two files, meta-data and user-data, as follows:
    $ cat  meta-data
    instance-id: iid-local01 
    local-hostname: atomichost
    $ cat user-data 
    password: atomic 
    ssh_pwauth: True 
    chpasswd: { expire: False } 
    - ssh-rsa AAAAB3NzaC1yc.........

    In the preceding code, we need to provide the complete SSH public key. We then need to create an ISO image consisting of these files, which we will use to boot to the VM. As we are using a cloud image, our setting will be applied to the VM during the boot process. This means the hostname will be set to atomichost, the password will be set to atomic, and so on. To create the ISO, run the following command:

    $ genisoimage -output init.iso -volid cidata -joliet -rock user-data meta-data
  • Start virt-manager.
  • Select New Virtual Machine and then import the existing disk image. Enter the image path of the Project Atomic image we downloaded earlier. Select OS type as Linux and Version as Fedora 20/Fedora 21 (or later), and click on Forward. Next, assign CPU and Memory and click on Forward. Then, give a name to the VM and select Customize configuration before install. Finally, click on Finish and review the details.
  • Next, click on Add Hardware, and after selecting Storage, attach the ISO (init.iso) file we created to the VM and select Begin Installation:

    Docker Cookbook

    Once booted, you can see that its hostname is correctly set and you will be able to log in through the password given in the cloud init file. The default user is fedora and password is atomic as set in the user-data file.

How it works…

In this recipe, we took a Project Atomic Fedora cloud image and booted it using virt-manager after supplying the cloud init file.

There’s more…

  • After logging in, if you do file listing at /, you will see that most of the traditional directories are linked to /var because it is preserved across upgrades.

    Docker Cookbook

  • After logging in, you can run the Docker command as usual
    $sudo docker run -it fedora bash

See also

Doing atomic update/rollback with Project Atomic

To get to the latest version or to roll back to the older version of Project Atomic, we use the atomic host command, which internally calls rpm-ostree.

Getting ready

Boot and log in to the Atomic host.

How to do it…

  1. Just after the boot, run the following command:
    $ atomic host status

    You will see details about one deployment that is in use now.

    Docker Cookbook

    To upgrade, run the following command:

    Docker Cookbook

  2. This changes and/or adds new packages. After the upgrade, we will need to reboot the system to use the new update. Let’s reboot and see the outcome:

    Docker Cookbook

    As we can see, the system is now booted with the new update. The *, which is at the beginning of the first line, specifies the active build.

  3. To roll back, run the following command:
    $ sudo atomic host rollback

    We will have to reboot again if we want to use older bits.

How it works…

For updates, the Atomic host connects to the remote repository hosting the newer build, which is downloaded and used from the next reboot onwards until the user upgrades or rolls back. In the case rollback older build available on the system used after the reboot.

See also


Docker and its ecosystem are evolving at a very high pace, so it is very important to understand the basics and build group up to adopt to new concepts and tools.

Additional information on Docker can be gained be referring to:

Resources for Article:

Further resources on this subject:

Subscribe to the weekly Packt Hub newsletter

* indicates required


Please enter your comment!
Please enter your name here