Dockerizing legacy applications with confd

Andreas Wittig – 19 Jul 2019

This blog post is an excerpt of our book Rapid Docker on AWS.

A legacy application typically uses files to read configuration parameters. But working with configuration files is cumbersome when building Docker images for the use with ECS (EC2 or Fargate). In theory, you could copy configuration files to the EC2 instances and mount them into your containers. However, this approach is cumbersome and does not work with Fargate at all. Alternatively, you could create a Docker image for every configuration. Building and managing so many different Docker images for each application will cause a lot of headaches.

Dockerizing legacy applications with confd

It is a best practice to use environment variables to configure an application running inside a Docker container. Doing so allows you to start the Docker image with a customized configuration on any platform.

You could rewrite your application to read configuration parameters from environment variables instead of files. However, there is a much simpler way. The tool confd generates configuration files based on templates and inserts configuration parameters handed over via environment variables.

You will learn how to dockerize your legacy application with little effort next. Let’s start with creating a Dockerfile.

FROM amazonlinux:2

The following section installs and configures confd. You will learn more about how to create configuration files with confd in a second — no need to change anything here.

# confd
RUN curl -s -L -o /usr/local/bin/confd && chmod +x /usr/local/bin/confd
COPY docker/confd /etc/confd
RUN mkdir /var/www/html/conf
COPY docker/custom-entrypoint /usr/local/bin/
RUN chmod u+x /usr/local/bin/custom-entrypoint
ENTRYPOINT ["custom-entrypoint"]

In the following steps, you will learn how to write configuration files on container startup based on environment variables with confd.

The legacy application uses a configuration file to configure the database connection: conf/app.ini

Looking for a new challenge?

  • tecRacer

    Cloud Consultant • AWS Migrations

    tecRacer • Premier AWS Consulting Partner • Germany, Austria, Portugal, and Switzerland
    Assessment Transformation Change Management

    Senior Lead Full Stack Developer

    DEMICON • AWS Advanced Consulting Partner • Remote
    AWS JavaScript/TypeScript Angular React


Our goal is to use environment variables for each property. To do so with confd, we need to create a configuration template. The following snippet shows the template docker/confd/templates/app.ini.tmpl for our conf/app.ini configuration file.

In the template, each value has been replaced with a placeholder.

host="{{getv "/database/host"}}"
name="{{getv "/database/name"}}"
user="{{getv "/database/user"}}"
password="{{getv "/database/password"}}"

For example, the following example references the environment variable DATABASE_HOST.

{{getv "/database/host"}}

Besides the template you need to create a confd configuration file as shown in the following snippet from docker/confd/conf.d/app.toml:

  • src the template file
  • dest the destination path for the generated configuration file
  • keys the keys used within the template file
src = "app.ini.tmpl"
dest = "/var/www/html/conf/app.ini"
keys = [

One last step, the script custom-entrypoint is executed whenever you start a container. The script runs confd and executes the CMD afterward.

set -e

echo "generating config"
confd -onetime -backend env
echo "executing $@"
exec "$@"

When dockerizing your application, you need to create your configuration files with confd?: Create a new template file .tmpl and store it at docker/confd/templates/. Next, create a new configuration file .toml and store it at docker/confd/conf.d/. Finally, modify the template and configuration file according to this example.

Looking for the source code of an end-to-end example? Check out our book Rapid Docker on AWS.


By using confd, it is simple to build a Docker image reading configuration parameters from environment variables. No need for rebuilding the way your legacy application reads configuration files.

Want to learn more about how to dockerize your application and run containers on AWS? Our book Rapid Docker on AWS is designed for web developers and DevOps engineers who want to dockerize their web applications and run their Docker containers on Amazon Web Services.

Become a cloudonaut supporter

Andreas Wittig

Andreas Wittig ( Email, Twitter, or LinkedIn )

We launched the cloudonaut blog in 2015. Since then, we have published 360 articles, 50 podcast episodes, and 48 videos. It's all free and means a lot of work in our spare time. We enjoy sharing our AWS knowledge with you.

Please support us

Have you learned something new by reading, listening, or watching our content? With your help, we can spend enough time to keep publishing great content in the future. Learn more

Amount must be a multriply of 5. E.g, 5, 10, 15.

Thanks to Alan Leech, Alex DeBrie, ANTHONY RAITI, Christopher Hipwell, Jaap-Jan Frans, Jason Yorty, Jeff Finley, Jens Gehring, jhoadley, Johannes Grumböck, Johannes Konings, John Culkin, Jonas Mellquist, Juraj Martinka, Kamil Oboril, Ken Snyder, Markus Ellers, Ross Mohan, Ross Mohan, sam onaga, Satyendra Sharma, Shawn Tolidano, Simon Devlin, Thorsten Hoeger, Todd Valentine, Victor Grenu, and all anonymous supporters for your help! We also want to thank all supporters who purchased a cloudonaut t-shirt.