8.9.0.0 | Recipes

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 has become a much quicker and 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 now publishes Docker images on Docker Hub as part of every release.

Even though the published Repose Docker image doesn’t do a lot by default, this recipe will show you how to tap into some of that power hidden just below the surface.

Prerequisites

The rest of this recipe assumes you have already completed the Quick Start and that you are familiar with how to perform the following on Repose Docker containers and images:

create
run
start
stop
inspect
remove

If you don’t have the basics of these operations memorized, then that is fine. You can always look back at the Quick Start anytime you need to.

Using a Repose Docker Image

All official Repose Docker images are published on Docker Hub at:

In the Quick Start the Repose instance was left in its default out of the box configuration. As was seen, it wasn’t very useful unless you wanted to go to the Rackspace homepage. So you are probably wondering how you make a Repose container do cool stuff like Preventing XML bomb attacks.

If you already have a Repose configuration that you are migrating to a Docker container, then it is very easy to present it to the container. Simply add the location to the --volume option as described in the example below.

If you don’t already have a configuration, then there is a couple of paths you might want to take. The first is if you don’t know how Repose works and therefore need to know what you can do, then visit the Getting Started. We all need to get started somewhere and this is a great place if it is your first time using Repose. If you are already familiar with using Repose and are just looking for a quick reference of the different files, the visit the Configuration page for more specific details. We also have a series of Recipes that will walk you through some of our common use cases and their configurations.

The following command will mount a volume containing a configuration and perform a couple other new options to the run command which are explained below.

docker run                                   \ (1)
   --detach                                  \ (2)
   --volume /my/config/directory:/etc/repose \ (3)
   --publish 8080:8080                       \ (4)
   --env JAVA_OPTS=-Xmx1024m                 \ (5)
   --name my_repose                          \ (6)
   rackerlabs/repose:latest                    (7)

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

1	This is the part of the command that tells Docker to create and start a container.
2	This option will run the container in detached mode. In detached mode, the container will run in the background. If we were to run in the default attached mode instead of detached mode, the terminal we used to execute this command would receive all of the container output (i.e., `STDOUT` and `STDERR`).
3	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 in the container in the `/etc/repose` directory. This allows us to modify configuration files without having to rebuild the Docker image or even restart the Docker container!
4	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.
5	This option sets the `JAVA_OPTS` environment variable. Doing so allows the user to configure the JVM that Repose is running on. The value of this environment variable should be valid command-line arguments for the `java` command.
6	This option names the container so that it’s easier to interact with.
7	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. Otherwise use the `repository:tag` of the image you created.

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 random ports instead of explicitly declaring the port mapping, we could replace the --publish 8080:8080 option with --publish-all instead.

Manually Building a Repose Docker Image

The Dockerfile’s used to build v{project-version} of the Repose Docker images published on Docker Hub are:

To build a custom Repose Docker image, follow these steps:

Acquire a Repose Dockerfile.
Optionally Modify the Dockerfile.

Run the following command from the root of the Repose project to build an image based on one of the Dockerfile’s linked above.

docker build                          \ (1)
   --build-arg REPOSE_VERSION={project-version} \ (2)
   --tag local/repose:v{project-version}-local  \ (3)
   /dir/containing/dockerfile/          (4)

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

1	This tells Docker to build an image.
2	This option is used by the Dockerfile to know what version of Repose to install. See our Release Notes page for a list of available versions.
3	This option defines the tag to apply to the image. It is in `repository:tag` format.
4	The last parameter is the path to the `docker build` context. By default, there should be a `Dockerfile` at the root of the context. If you need it to reside somewhere else, then review the Official Docker Documentation for additional options.

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
```

Notices

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!