1. OpenRepose
  2. Home
Search

Docker

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.

Docker

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:

https://docs.docker.com/

Docker Image

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

https://hub.docker.com/r/rackerlabs/repose/

Dockerfile

The Dockerfile used to build the Debian/Ubuntu Docker images has been copied below for the sake of convenience.

# Use Ubuntu as a base, since it works and is familiar.
# The version should be the latest tested, LTS version.
FROM ubuntu:16.04

MAINTAINER The Repose Team <reposecore@rackspace.com>

# This build-arg is used to pass the Repose version number which will be set up in this image.
ARG REPOSE_VERSION

# Install Repose (and Java) from the Debian package repository.
RUN apt-get update -qq && apt-get install -qq -y wget openjdk-8-jre-headless
RUN wget --quiet -O - http://repo.openrepose.org/debian/pubkey.gpg | apt-key add - && echo 'deb http://repo.openrepose.org/debian stable main' > /etc/apt/sources.list.d/openrepose.list
RUN apt-get update -qq && apt-get install -y repose-valve=$REPOSE_VERSION repose-filter-bundle=$REPOSE_VERSION repose-extensions-filter-bundle=$REPOSE_VERSION repose-experimental-filter-bundle=$REPOSE_VERSION

ENV APP_ROOT=/etc/repose
ENV APP_VARS=/var/repose
ENV APP_LOGS=/var/log/repose

# Turn off local logging
RUN sed -i 's,<\(Appender.*RollingFile.*/\)>,<!--\1-->,' ${APP_ROOT}/log4j2.xml
RUN sed -i 's,<\(Appender.*PhoneHomeMessages.*/\)>,<!--\1-->,' ${APP_ROOT}/log4j2.xml

# Arbitrary User ID support
RUN chgrp -R 0 ${APP_ROOT} ${APP_VARS} ${APP_LOGS} && \
    chmod -R g=u ${APP_ROOT} ${APP_VARS} ${APP_LOGS}

# Expose APP_ROOT as a volume for mounting.
WORKDIR ${APP_ROOT}
VOLUME ${APP_ROOT}

# Switch user to repose
USER repose

# Expose the default Repose service port for host port forwarding.
# If the port in the user's system model differs from this port, the user will have to map it manually using the
# "-p" flag with the Docker run command.
EXPOSE 8080

# This environment variable is used to set command-line options.
# The user can manually set these options using the "-e" flag with the Docker run command.
ENV JAVA_OPTS=

# Start Repose.
CMD java $JAVA_OPTS -jar /usr/share/repose/repose-valve.jar -c /etc/repose

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=9.9.9.9 -t my_repose_image /path/to/

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

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

    • --build-args REPOSE_VERSION=9.9.9.9 - This option defines the version of Repose that will be installed in the image. The REPOSE_VERSION key will be given a value of 9.9.9.9 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.

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

    • /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 Container

Running

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                             \ (1)
   -d                                  \ (2)
   -v /my/config/directory:/etc/repose \ (3)
   -p 8080:8080                        \ (4)
   -e 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 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.
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 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!
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.

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

Inspecting

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.

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!