Creating a Self-Registering Relay in a Docker Container

While our Docker Relay Guide will let you set up a Docker relay by generating a relay token and passing it into the Docker image, what if you want to have a self-managed set of relays that will spin up and down without you needing to generate a token for each one? This recipe will walk you through modifying the default Docker image to result in an image that takes an admin token, which you can reuse, and generates its own relay token to register itself to your strongDM organization.

Generating the token

You can generate an admin token that has only one function: creating relay tokens. Do this in the web UI under Settings / Admin Tokens. Select Create under Relays then click the Create button. Copy the token that is printed to screen as you will need it later.

Note: For more detailed information on creating admin tokens, check out the admin token guide.

Creating the new Dockerfile

You can modify the default strongDM Docker image by creating and building a new Dockerfile. Use the following file (also available here) to define your new Docker image. Save it as autoreg.dock in a directory on a system with Docker installed.

# Use the following command to build the Dockerfile.
# docker build -f autoreg.dock .

FROM quay.io/sdmrepo/relay:latest

ADD autoreg.sh /autoreg.sh
RUN chmod a+x /autoreg.sh

ENTRYPOINT /autoreg.sh

You’ll note that this file references a shell script—that’s where the real magic happens. Use the following file (also available here) as autoreg.sh, which should be saved in the same directory as autoreg.dock.

#!/bin/bash

CMD=/sdm.linux

# necessary to suppress stdout during token create
unset SDM_DOCKERIZED

# generate fresh relay token (depends on inheriting SDM_ADMIN_TOKEN)
export SDM_RELAY_TOKEN=`$CMD relay create`

# temporary auth state is created by invoking `relay create` and must
# be cleared out prior to relay startup
rm /root/.sdm/*
unset SDM_ADMIN_TOKEN

# --daemon arg automatically respawns child relay process during
# version upgrades or abnormal termination
export SDM_DOCKERIZED=true # reinstate stdout logging
$CMD relay --daemon

NOTE: It is important to understand why each command is in this script. First you have to unset SDM_DOCKERIZED to turn off STDOUT logging, so when you run $CMD relay create it is only outputting the token itself. Next, you need to turn off admin authentication by removing the token in SDM_ADMIN_TOKEN and deleting the .sdm directory, because otherwise when you run the relay it will attempt to authenticate with the admin token. Finally, turn back on SDM_DOCKERIZED and run the relay command. The --daemon flag is needed to ensure the relay will automatically restart itself in case of upgrades or abnormal terminations.

With autoreg.dock and autoreg.sh in place, run the following command to generate the Dockerfile, taking note of the output image name.

$ docker build -f autoreg.dock .
Sending build context to Docker daemon  3.584kB
Step 1/4 : FROM quay.io/sdmrepo/relay:latest
 ---> 35bcea2d45b5
Step 2/4 : ADD autoreg.sh /autoreg.sh
 ---> 85b70821341d
Step 3/4 : RUN chmod a+x /autoreg.sh
 ---> Running in 89c456fd5f72
Removing intermediate container 89c456fd5f72
 ---> 2b934fda1d2d
Step 4/4 : ENTRYPOINT /autoreg.sh
 ---> Running in ec375c32487f
Removing intermediate container ec375c32487f
 ---> f734206ddaaa
Successfully built f734206ddaaa

In this case, the image f734206ddaaa is the resulting local Docker image.

Run the new Docker container

Similarly to creating a normal Docker relay, you must invoke this Docker image with an environment variable. Replace XXX with the admin token you generated above, and YYY with the ID of the Docker image you just generated.

$ docker run --restart=always [--net=host] --name sdm-relay -e SDM_ADMIN_TOKEN=XXX -d YYY

Note: The --net=host option is only necessary if the destination database is known as “localhost” (running sdm-relay colocated with the DB). If you plan to use this recipe to generate arbitrary numbers of relays, be sure to account for this in the --name flag by removing it or generating a new name for each relay.

Verify your new relay

Log into the web UI. In that section, the relay you created should appear Online, with a heartbeat.

"Relay status in Admin UI"

If any errors occur or if the relay does not report “online” status, please contact support@strongdm.com for assistance.