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


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’m the author of Amazon Web Services in Action. I work as a software engineer, and independent consultant focused on AWS and DevOps.

You can contact me via Email, Twitter, and LinkedIn.

Briefcase icon
Hire me
Cover of Rapid Docker on AWS

New book: Rapid Docker on AWS

A rapid way to get your web application up and running on AWS. Made for web developers and DevOps engineers who want to dockerize their web applications and run their containers on Amazon Web Services. Prior knowledge of Docker and AWS is not required.

Buy icon
Buy now
Marbot Logo

Incident Management for Slack

Team up to solve incidents with our chatbot marbot. Never miss a critical alert. Escalate alerts from your AWS infrastructure among your team members. Strong integrations with all parts of your AWS infrastructure: CloudWatch, Elastic Beanstalk, RDS, EC2, ...

Slack icon
Try for free
🎉 Rapid Docker on AWS out now
Learn to bundle your application into Docker containers and run them on AWS. Get the eBook or join the Online Seminar.