Skip to content

Installation

Jump to bottom
Jeremy Echols edited this page Feb 19, 2024 · 15 revisions

RAIS - Installation

RAIS can be installed using Docker or manual compilation. Pick the method that suits your architecture best, because both installation options should be pretty trivial.

Manual Installation

Some linux understanding is helpful for compiling and installing RAIS manually, but this is by far the best method if you aren't already familiar with Docker.

Prerequisites

  • pkg-config is needed for the Go-to-C bindings, e.g., apt install pkg-config
  • OpenJPEG 2.3 or later, and its dev headers. e.g., apt install libopenjp2-7-dev
  • A supported version of the Go compiler must be downloaded (most package managers have versions of Go which are outdated).
    • If you're building on production, you have to download Go there, but it doesn't have to be a system-wide installation, and it can be removed after the build is complete if desired
  • The RAIS source code must be cloned, e.g., git clone https://github.com/uoregon-libraries/rais-image-server.git

Installing and using Go is trivial, but its documentation can be a bit painful to newcomers. If you only need Go for RAIS, all you need to do after you've installed pkg-config and openjpeg is the following:

# Download the latest stable Go version for your architecture and "install"
# into your home directory. Replace $version with the latest go version.
export version=1.21.0
cd ~
curl -OL https://dl.google.com/go/go$version.linux-amd64.tar.gz
tar -xzf ~/go$version.linux-amd64.tar.gz

# Add the go binary to your path
export PATH=$PATH:~/go/bin

# Grab the RAIS codebase
git clone https://github.com/uoregon-libraries/rais-image-server.git

Compile

Go to the location where RAIS source code lives, and run make to build RAIS and the JSON tracer plugin. If you don't want any plugins, running make rais-server will suffice, and is slightly faster. All compiled binaries will live in a bin folder at the root of the RAIS project. You'll want to copy bin/rais-server to your final production location, as well as any plugins in bin/plugins/.

systemd

RAIS includes a systemd service file in rh_config/rais.service which we use to ensure RAIS is always started on reboot.

Configuration

See rais-example.toml for the best source of documentation. Copy that into /etc/rais.toml or set up your systemd unit file to export environment variables as needed.

Some high-level information is also in our Configuration document.

RHEL 7 Installation

Very low-level, step-by-step details can be found in our Manual Setup instructions, though those may not always stay in sync, and are geared toward using RAIS with Open ONI.

Non-JP2 support

If you want to handle more than just JP2s, you'll need ImageMagick libraries and headers, and you'll have to manually compile the Image Magic decoder plugin. e.g.:

sudo apt install libmagickcore-dev
make bin/plugins/imagick-decoder.so

Note: Very large images which are not in the recommended JP2 format will be very slow to decode. If you can't generate JP2s, RAIS will not go fast without a monstrous cache.

Docker

Though the Docker image removes the need to install any system packages, it is not a silver bullet! Because RAIS is so easy to install on bare metal, the Docker installation is only recommended for demos or for teams that already know the various ins and outs of running containers in a production environment.

Pre-requisites

  1. Install Docker CE and Compose.
  2. Grab the RAIS repository: 
    git clone git@github.com:uoregon-libraries/rais-image-server.git
cd rais-image-server
  3. If you use docker-compose, consider creating a .env file to set up various RAIS environment variables you might want. For example: 
    # Note that this URL is only used in the docker-compose demo, and *not* in a production setup!
URL=http://mydemo.university.edu
RAIS_LOGLEVEL=DEBUG
RAIS_TILECACHELEN=1000
RAIS_PLUGINS=json-tracer.so

Dockerhub

If you pull RAIS from Dockerhub, please note that you'll be getting the latest stable version. It may not have the same features as the development version. You can look at the latest stable version in github by browsing our main branch.

Running RAIS from Docker is fairly simple:

# This example passes environment variables to the container for configuration
docker run -d \
  --name rais \
  --privileged=true \
  -e RAIS_ADDRESS=":12415" \
  -e RAIS_IIIFURL="http://localhost:12415/iiif" \
  -e RAIS_IIIFINFOCACHESIZE=10000 \
  -e RAIS_TILEPATH="/var/local/images" \
  -p 12415:12415 \
  -v $(pwd)/docker/images:/var/local/images \
  uolibraries/rais

# If you want to use a config file rather than the environment variables, you
# might use this instead:
docker run -d \
  --name rais \
  --privileged=true \
  -p 12415:12415 \
  -v $(pwd)/docker/images:/var/local/images \
  -v $(pwd)/rais-example.toml:/etc/rais.toml \
  uolibraries/rais

The various configuration options are documented in the repository's rais-example.toml file.

On the first run, there will be a large download to get the image, but after that it will be cached locally.

Once the container has been created, it can then be started and stopped via the usual docker commands.

Local Image

You can also build an image locally via make docker. This can take some time, but can be helpful if you need to manually build the codebase for development or if you simply want to use a branch other than main.

The image you build will be named "uolibraries/rais:latest-indev". Use that instead of "uolibraries/rais" in the commands above, and make sure you use a docker-compose override that specifies that image.

Clone this wiki locally