Rundeck Docker Compose files

Docker Compose files to spin up an instance of Rundeck.

How to run

Add a COMPOSE_ENV file and save its location as a shell variable along with the location where this repo lives, here for example /opt/containers/rundeck plus all other variables. At env/fqdn_context.env.example you'll find an example environment file.

When everything's ready start Rundeck with Docker Compose, otherwise head down to Initial setup first.

Environment

export COMPOSE_DIR='/opt/containers/rundeck'
export COMPOSE_CTX='ux_vilnius'
export COMPOSE_PROJECT='rundeck-'"${COMPOSE_CTX}"
export COMPOSE_FILE="${COMPOSE_DIR}"'/compose.yaml'
export COMPOSE_ENV=<add accordingly>

Context

On your deployment machine create the necessary Docker context to connect to and control the Docker daemon on whatever target host you'll be using, for example:

docker context create fully.qualified.domain.name --docker 'host=ssh://root@fully.qualified.domain.name'

Pull

Pull images from Docker Hub verbatim.

docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" --profile 'full' pull

Copy to target

Copy images to target Docker host, that is assuming you deploy to a machine that itself has no network route to reach Docker Hub or your private registry of choice. Copying in its simplest form involves a local docker save and a remote docker load. Consider the helper mini-project quico.space/Quico/copy-docker where copy-docker.sh allows the following workflow:

images="$(docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" --profile 'full' config | grep -Pi -- 'image:' | awk '{print $2}' | sort | uniq)"
while IFS= read -u 10 -r image; do
    copy-docker "${image}" fully.qualified.domain.name
done 10<<<"${images}"

Start

docker --context 'fully.qualified.domain.name' compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" --profile 'full' up --detach

Clean-up

docker --context 'fully.qualified.domain.name' system prune -af
docker system prune -af

Initial setup

We're assuming you run Docker Compose workloads with ZFS-based bind mounts. ZFS management, creating a zpool and setting adequate properties for its datasets is out of scope of this document.

Datasets

Create ZFS datasets and set permissions as needed.

• Parent dateset

  export "$(grep -Pi -- '^CONTEXT=' "${COMPOSE_ENV}")"
  zfs create -o canmount=off zpool/data/opt
  zfs create -o mountpoint=/opt/docker-data zpool/data/opt/docker-data
  

• Container-specific datasets

  zfs create -p 'zpool/data/opt/docker-data/rundeck-'"${CONTEXT}"'/rundeck/config'
  zfs create -p 'zpool/data/opt/docker-data/rundeck-'"${CONTEXT}"'/rundeck/data'
  zfs create -p 'zpool/data/opt/docker-data/rundeck-'"${CONTEXT}"'/postgres/data'
  

• Create subdirs

  mkdir '/opt/docker-data/rundeck-'"${CONTEXT}"'/rundeck/config/projects'
  mkdir '/opt/docker-data/rundeck-'"${CONTEXT}"'/rundeck/data/'{'data','logs'}
  

• Change ownership

  chown -R 999 '/opt/docker-data/rundeck-'"${CONTEXT}"'/postgres/'*
  chown -R 1000 '/opt/docker-data/rundeck-'"${CONTEXT}"'/rundeck/'*
  

Additional files

Rundeck settings in realm.properties

At the very least override Rundeck's default realm.properties file with one of your own and set a username and a password for local login. Default credentials will otherwise be admin:admin. Per Rundeck's manual on Jetty and JAAS authentication section "PropertyFileLoginModule" you're going to need Rundeck's rundeck.war file to create a bcrypt hash for your password. Run the official Rundeck Docker image in a throwaway container like so where rundeck/rundeck:4.13.0 is an example version you want to use:

docker run \
    --rm \
    --tty \
    --interactive \
    --entrypoint bash \
    rundeck/rundeck:5.9.0 \
    -c 'java -jar /home/rundeck/rundeck.war --encryptpwd Jetty'

This will download rundeck/rundeck:5.9.0 if needed and open up something along the lines of:

Required values are marked with: * 
Username (Optional, but necessary for Crypt encoding):

Type your desired username, type <Enter> and then your plain text password followed by <Enter> again. The whole exchange may look like this:

Required values are marked with: * 
Username (Optional, but necessary for Crypt encoding):
my-username
*Value To Encrypt (The text you want to encrypt):
t0psecr3t
          
==ENCRYPTED OUTPUT==
bcrypt: BCRYPT:$2a$10$jMWQvKbjpmBrKdA0Qi0/n.UvHot1F7Cvf7/Avlv9afknHpbvT6j7y
obfuscate: OBF:1z0f18qk1xtp1vgv1t331vfz1xtt18qq1z0f
md5: MD5:962aefc8c283c13e13d9c990dafdfba9
crypt: CRYPT:myS5y0c4wMQts

Put a single line into an otherwise empty /opt/docker-data/rundeck-'"${COMPOSE_CTX}"'/rundeck/config/realm.properties:

my-username: BCRYPT:$2a$10$jMWQvKbjpmBrKdA0Qi0/n.UvHot1F7Cvf7/Avlv9afknHpbvT6j7y,user,admin

The account my-username will have roles user and admin and it'll be the only existing account when Rundeck starts.

SSH known_hosts file

Place an empty known_hosts file at /opt/docker-data/rundeck-'"${COMPOSE_CTX}"'/rundeck/config/known_hosts. Feel free to optionally prefill it with SSH public host keys.

When done head back up to How to run.

Development

Conventional commits

This project uses Conventional Commits for its commit messages.

Commit types

Commit types besides fix and feat are:

• refactor: Keeping functionality while streamlining or otherwise improving function flow
• docs: Documentation for project or components

Commit scopes

The following scopes are known for this project. A Conventional Commits commit message may optionally use one of the following scopes or none:

• rundeck: A change to how the rundeck service component works
• postgres: A change to how the postgres service component works
• build: Build-related changes such as Dockerfile fixes and features.
• mount: Volume or bind mount-related changes.
• net: Networking, IP addressing, routing changes
• meta: Affects the project's repo layout, file names etc.