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

Cover of Rapid Docker on AWS

Become a Docker on AWS professional!

Our book Rapid Docker on AWS is designed for DevOps engineers and web developers who want to run dockerized web applications on AWS. We lead you with many examples: From dockerizing your application to Continuous Deployment and Infrastructure as Code on AWS. No prior knowledge of Docker and AWS is required. Get the first chapter for free!


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.

Tags: aws docker
Andreas Wittig

Andreas Wittig

I launched in 2015 with my brother Michael. Since then, we have published hundreds of articles, podcast episodes, and videos. It’s all free and means a lot of work in our spare time. We enjoy sharing our AWS knowledge with you.
Have you learned something new by reading, listening, or watching our content? If so, we kindly ask you to support us in producing high-quality & independent AWS content. We look forward to sharing our AWS knowledge with you.

Support us

Feedback? Questions? You can reach me via Email, Twitter, or LinkedIn.