Development Guide

Development in RAIS

To Docker or not to Docker

Developers may be tempted to use the docker-compose setup for development. This ensures a consistent dev experience, avoids installing a lot of local dependencies, etc.

However, this is much slower than local development due to the time spent rebuilding the docker image as code changes. I mean, let's be honest, it's not like the kind of slowness you'll get with complex Rails or Java setups, but this is a Go project, and we have higher expectations than "some" devs....

So, if you can, use the local workflow, not the Docker workflow.

Local Workflow

Requirements / Setup

When in doubt, check out the Dockerfile, as it is always the record of source for RAIS's requirements. As of v3.3.0, however, the dependencies are very minimal:

• Install Go
• Install revive: go install github.com/mgechev/revive@latest
• Install openjpeg, e.g., on RHEL 7: yum install -y openjpeg2-devel

Compile

Easy! Just run make to build the RAIS binary and the JSON tracer plugin. If you need a plugin that's in src/plugins, but isn't built by default, simply run make bin/plugins/[plugin name].so. Not that imagick-decoder.so requires the Image Magick development library, which has a lot of dependencies.

Run

Starting the server should also be trivial - either copy the example config, set up environment variables, or use command-line flags.

#####
# Use explicit file-based configuration:
#####

cp rais-example.toml rais.toml
vim rais.toml
./bin/rais-server

#####
# Or environment variables:
#####

export RAIS_ADDRESS=":8080"
export RAIS_LOGLEVEL=DEBUG
export RAIS_TILEPATH=$(pwd)/docker/images
export RAIS_IIIFURL="http://localhost:8080/iiif"

# RAIS requests will look something like this: http://localhost:8080/iiif/testfile%2Ftest-world.jp2/info.json
./bin/rais-server

#####
# Or just use command-line flags:
#####

# RAIS requests will look something like this: http://127.0.0.1:8081/images/iiif/testfile%2Ftest-world.jp2/info.json
./bin/rais-server \
  --address :8081 \
  --log-level "INFO" \
  --tile-path "$(pwd)/docker/images" \
  --iiif-url "http://127.0.0.1:8081/images/iiif"

Docker Workflow

Requirements / Setup

Setup is much the same as described in Setup. The main difference is that you probably want to make docker's setup a little more dev-friendly. Copy the docker-compose override and adjust it to meet your needs:

cp docker-compose.override.yml-example docker-compose.override.yml

The override file specifies useful things like automatically mounting your local binaries to speed up the edit+compile+test loop and exposing RAIS's local port (12415) for testing it directly. You can also add in plugins you find useful (see Using Datadog for a good example)

Compile

For compilation, the easiest option is to simply build all the images locally via make docker. This generates both the "build box" as well as the production image. From here, running ./scripts/buildrun.sh will compile the latest code.

Assuming the docker-compose overrides mount the RAIS binary into the container, you should be able to just use standard docker commands to run the newly-compiled RAIS server binary, e.g., docker-compose restart rais

Start the stack

Run docker-compose up, and the application demo will be available at your configured URL.