Dockerizing legacy applications with confd

Andreas Wittig – 19 Jul 2019

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.


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.

Andreas Wittig

Andreas Wittig

I’ve been building on AWS since 2012 together with my brother Michael. We are sharing our insights into all things AWS on cloudonaut and have written the book AWS in Action. Besides that, we’re currently working on bucketAV,HyperEnv for GitHub Actions, and marbot.

Here are the contact options for feedback and questions.