Using RepoBee with Docker
RepoBee offers a minimal Docker image backed by Alpine Linux that weighs in at less than 100 MB, and can be found here. Usage with Docker is mostly the same as with a local install, but there are some significant differences in how to get started. This part of the user guide outlines how to use RepoBee with Docker as efficiently as possible.
Note
For frequent users of RepoBee, we recommend installing it locally for an optimal user experience. The Docker image is useful for trying out RepoBee without installing anything (other than Docker), as well as for creating automation scripts, but the CLI is noticeably less responsive compared to installing RepoBee directly on the host machine.
Basic usage
There are two primary ways to use RepoBee in Docker: through an interactive
bash session in which you can operate as per-usual, or by issuing
individual commands through Docker.
Note
Running the docker program requires root privilege unless you are part
of the docker group. Depending on how your system is configured, you
may need to prepend sudo to all docker commands in this guide.
Using RepoBee in an interactive bash session
The primary way of using RepoBee in Docker is through an interactive bash
session within a Docker container. Here’s a simple example of checking the
version number of RepoBee.
bash shell in a RepoBee Docker
container$ docker run --rm -it repobee/repobee \
/bin/bash
bash5.1$ repobee --version
v3.7.0-dev
In further listings, we’ll use the prefix bash-5.1$ to denote that we’re
inside the Docker container. Once in the session, you can use RepoBee mostly
as described in the rest of this user guide, with a few exceptions in regards
to installing plugins and managing the installation. Tab completion is enabled
by default.
Note that we always do a line-break in the Docker command, and specify the
command to run inside Docker on a separate line (here /bin/bash). This is
for added clarity, and nothing you need to do yourself.
Note that pulling and running repobee/repobee without specifying a version
will use the latest tag, which points to the most recent uploaded image.
This is most often not a stable release (in this case, it’s an
in-development version of RepoBee 3.7). To use a stable release, you must also
specify a version number, which you can find among the tags here.
For example, to use v3.6.0, the command would look like so:
bash shell with a stable release of
RepoBee in Docker$ docker run --rm -it repobee/repobee:v3.6.0 \
/bin/bash
bash-5.1$ repobee --version
v3.6.0
We will omit the version tag throughout this guide, but keep in mind that you should always specify a version tag when using RepoBee in practice.
Running a single RepoBee command
If you just want to run a single command, you don’t need to run bash,
but can run the RepoBee command directly. For example, we could run repobee
--version like so.
repobee --version without first starting a bash
shell$ docker run --rm -it repobee/repobee \
repobee --version
In several of the following examples, we will execute single commands like
the one shown above, without starting a bash session. In practice, it’s
however most often more convenient to start an interactive bash session and
then execute RepoBee commands in there.
Working directory and config file
To make effective use of RepoBee in Docker, you need to be able to persist
data, most importantly a configuration file. The default working directory of
the RepoBee image is /home/repobee/workdir. With the recent addition of
local config files (see Local repobee.ini config files), the simplest way to configure
RepoBee in Docker is to mount a named volume at /home/repobee/workdir and
create a local config file in it with the config wizard command.
repobee-workdir for persistent storage$ docker run --rm -v repobee-workdir:/home/repobee/workdir -it repobee/repobee \
repobee --config-file repobee.ini config wizard
# follow the prompts to configure RepoBee
Now, the next time you run Docker with this volume mounted in the same place,
RepoBee will pick up the local repobee.ini config file. Note that you don’t
need to specify repobee.ini as the config file after having created it, due
to how local config files work in RepoBee.
$ docker run --rm -v repobee-workdir:/home/repobee -it repobee/repobee \
repobee config show
# should show the config
While you can access the named volume, which is typically located at
/var/lib/docker/volumes/<VOLUME_NAME>, we recommend working with it only
through Docker. Otherwise, issues with file and directory permissions may
spring up which require some Docker and UNIX know-how to solve.
Important
If you don’t specify the volume when running a RepoBee container, none of your previously stored data will be available, including the config file!
If for some reason you have a need to frequently access the data inside the storage volume outside of the Docker container, it’s typically often a better idea to use a local directory instead. Here’s an example of how to do that.
$ mkdir repobee-workdir # create local directory
$ chown 1000:1000 repobee-workdir # set UID:GID to match the image's repobee user
$ docker run --rm -v "$PWD/repobee-workdir":/home/repobee/workdir -it repobee/repobee \
/bin/bash
bash-5.1$ # do stuff
If your host machine’s user ID and group ID do not match the user ID and group
ID of the image’s user (both of which are 1000), you may be unable to modify
content in the working directory without sudo. You should however be able
to read all content regardless.
Installing plugins
It’s entirely possible to install plugins while in an interactive bash
session in RepoBee’s default Docker image, but you will have to install the
plugin each time you start the container, as the install directory is not
persisted. To not have to repeat plugin installations over and over again,
you can instead create your own Dockerfile in which you do so. For example,
the following Dockerfile installs the junit4 and csvgrades plugins.
FROM repobee/repobee # Optionally, append version tag (e.g. :v3.6.0)
RUN repobee plugin install --version-spec junit4@v1.2.1
RUN repobee plugin install --version-spec csvgrades@v0.2.1
Given that the Dockerfile is in the current directory, you can then build the image and run a container from it it like so.
$ docker build -t my-repobee-img .
$ docker run --rm -it my-repobee-img \
repobee plugin list
# should show that junit4 and csvgrades are installed