/ Tech

KeyBox on OpenShift

KeyBox is a web-based SSH console that centrally manages administrative access to systems.

I wanted to install KeyBox on OpenShift, so I created a Dockerfile and an OpenShift template for it, to be found on Github. See the README for a documentation how to use it.

As always when deploying an existing application to OpenShift, several workarounds had to be made to get it up and running. Some things I had to do:

Docker Image

There was no existing Docker image which was actively maintained and met the requirements for running KeyBox on OpenShift (i.e. proper directory permissions). The ones I found were rather outdated and very fat images, including many unneeded stuff. My requirement was to use a small Docker image which includes the official KeyBox release and nothing more. S2I also was not an option, as this didn't work out of the box and also would mean to have customized scripts. Having a Docker image gives the possibility to build and run KeyBox outside of OpenShift easily.

The Github repository hosting the Dockerfile triggers an automated build on Docker Hub to serve the built image from there.

Docker Build Status Docker Automated builid

Configuration Template

Sadly KeyBox can't be configured using environment variables, it requires a configuration file called KeyBoxConfig.properties, a simple key/value configuration file. Here comes dockerize into action, which has a mechanism to write configuration files using environment variables and templates. This is done on startup of the image.

Persistent Storage

It isn't very clear where files are stored which have to be made persistent. The database and the public SSH key is stored under /opt/keybox/jetty/keybox/WEB-INF/classes/keydb, this directory can be easily mounted as volume. But there is this file keybox.jceks which also needs to be persisted after it's initial creation by the application. This file is stored under /opt/keybox/jetty/keybox/WEB-INF/classes/keybox.jceks which makes things hard. The current workaround in the custom startKeyBox.sh script is to copy the file during container shutdown to keydb/ and on startup to restore it from there. This hopefully gets better in the future: issue #248.


In the default configuration of KeyBox Jetty gets started only with a TLS listener on port 8443 - using a self-signed certificate. When deploying KeyBox on OpenShift, the route would need to be configured with re-encryption termination. This mode wants to have a destination CA certificate to verify the endpoint, which doesn't work with self-signed certificates. To simplify things, there is now the plain http endpoint enabled, leaving TLS termination up to the loadbalancer / reverse proxy in front of it. In regards of OpenShift, this would be the router (HAProxy).