Skip to end of metadata
Go to start of metadata


With the advent of container technology, Repose can be fully encapsulated and run as a service. By bundling the environment with the software itself, deploying Repose becomes a much quicker, simpler process. Docker boasts security through isolation, and when run on platforms with native support, it requires very little overhead. To make everything as easy and versatile as possible, the Repose team will release Docker images on Docker Hub alongside every release of Repose.


To run Repose in Docker, there are just two basic steps:

  1. Acquire a Repose Docker image.
    1. Download the Docker image. See: Docker Image
    2. Build the Docker image. See: Dockerfile
  2. Run the Repose Docker image in a Docker container. See: Docker Container

To find out more about Docker, including how to install and operate it, visit the official Docker documentation at:


The Dockerfile used to build the Docker images that we publish can be found in the Repose GitHub repository.

The Dockerfile may move over time, but its current location in the repository is:

To modify and/or build a Repose Docker image from the Dockerfile, follow these steps:

  1. Acquire a Repose Dockerfile.
  2. (Optional) Modify the Dockerfile.
  3. Run the following command to build the Dockerfile:

    docker build --build-arg REPOSE_VERSION= -t my_repose_image /path/to/

    Let's break that command down and take a closer look at what it is doing:

    1. docker build - This is the part of the command that tells Docker to build the image.

    2. --build-args REPOSE_VERSION= - This option defines the version of Repose that will be installed in the image. The REPOSE_VERSION key will be given a value of which can be used inside the Dockerfile. It exists so that we can build Docker images for any version of Repose using a single Dockerfile.

    3. -t my_repose_image - This option defines the tag (in repository:tag format) to apply to the image.

    4. /path/to/- This is the path to the Repose Dockerfile. The Dockerfile itself must exist as a child of the provided directory. Note that this directory will also be treated as the Docker build context.

  4. If the Dockerfile was successfully built, a Docker image should be available within Docker. Run the following command to show all available images:

    docker images

Docker Image

All official, published Docker images for Repose, can be found on Docker Hub at:

Docker Container


After you have acquired a Repose Docker image, you can run Repose by creating and starting a Docker container from that image. For example, the following command could be use:

docker run -d -v /my/config/directory:/etc/repose -p 8080:8080 --name my_repose rackerlabs/repose:latest

Let's break that command down and take a closer look at what it is doing:

  • docker run - This is the part of the command that tells Docker to create and start a container.
  • -d - This flag will run the container in detached mode. In detached mode, the container will run in the background. If we were to run in attached mode (the default) instead of detached mode, the terminal we used to execute this command would receive all of the output (i.e., STDIN, STDOUT, and STDERR) from the container.
  • -v /my/config/directory:/etc/repose - This option defines a volume that is mounted from the host (i.e., the OS running Docker) onto the Docker container. The volume mapping format is HOST_DIRECTORY:CONTAINER_DIRECTORY, so in this case, the contents of /my/config/directory on the host will be visible within the /etc/repose directory in the container. This allows us to modify configuration files without having to rebuild the Docker image or restart the Docker container!
  • -p 8080:8080 - This option defines a port mapping between the host (i.e., the OS running Docker) and the Docker container. Doing so allows Repose to accept traffic over the specified port from outside of Docker. The port mapping format is HOST_PORT:CONTAINER_PORT, so in this case, traffic on port 8080 of the host will be forwarded to port 8080 of the container.
  • --name my_repose - This option names the container so that it's easier to interact with.
  • rackerlabs/repose:latest - This is the image ID (in repository:tag format) to create a container from. Remember that Repose images are hosted at Docker Hub, which Docker can use implicitly.

Now if we wanted to, we could change the Docker options that define the environment that Repose will run in. If we wanted to forward the random ports instead of explicitly declaring the port mapping, we could drop the "-p 8080:8080" option and pass the "-P" flag instead.

After running that command, you should be able to see Repose running inside a Docker container! Use the following command to show all running containers:

docker ps


Once running, you may wish to inspect the internal state of the container. Well, the default command for the official Repose Docker images will run Repose in the foreground, and as a result, simply attaching to the container with a command like the following will only allow interaction with the Repose process:

docker attach container_name_or_id

Instead, you can use a command like the following to run a new bash session inside of your running container:

docker exec -it container_name_or_id /bin/bash

Log Files

If you need to access Repose log files, the recommended way of doing so would be to mount a Docker volume when starting the container using a command like the following:

docker run -d -v /my/config/directory:/etc/repose -v /var/log/repose:/var/log/repose -p 8080:8080 --name my_repose rackerlabs/repose:latest

You will notice that this command is very similar to the command provided in the #Running section, but with one more option: -v /var/log/repose:/var/log/repose. This option simply mounts the Repose log directory in the container to the same directory on the host.

How to Run Repose in Docker

See: Docker Container


Custom artifacts are not currently supported by our Docker images. If you would like to deploy custom code in Repose running in Docker, please Contact Us!

  • No labels


  1. Great effort!

    Few notes about the Dockerfile instructions (based on my results trying it):

    The link to the default repose filters doesn't include the filters "container.cfg.xml", "system-model.cfg.xml" and "response-messaging.cfg.xml". I had to copy them over from the core folder.

    Before Line #7  you may want to add "apt-get update" or it complains that wget is not found

    Line#15 Docker complains about using wildcards with ADD. So I replaced it with the following:

    COPY ./repose_configs /etc/repose

    Line# 18 this file exposes port 80. However, the default port in system-model.cfg.xml is 8080

  2. In Dockerfile

    CMD java -jar /usr/share/lib/repose/repose-valve.jar

    works for me.

  3. Thank you, Kapil! The example has been updated.