This document is aimed at system administrators at institutions that write their own grimas.

Containerization and docker support files

Grima can be deployed on desktop computers and on cloud servers using containers. Its documentation is built inside a container. We use docker to create the containers.

Most people using containers will just use the published containers: docker.io/zemkat/grima-desktop and docker.io/zemkat/grima-cloud should just work.

Windows and MacOS Desktop users should install Docker Desktop (requires creating a free dockerhub account as it is still targeted at developers rather than end users), and then run grima-desktop.bat for Windows or grima-desktop.sh for MacOS. Linux Desktop users install docker easily following the official instructions and using grima-desktop.sh.

Cloud / containerized deployments should check out the example configurations to adapt it to your needs.

How are the containers built?

Desktop dockerfile

This dockerfile takes the contents of dist and treats it like the main website of an apache install (grima doesn’t need to be the main website, but container philosophy is that each container has 1 thing in it, and that 1 thing is this website).

ARG phpImg=php:apache
FROM $phpImg
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \
  && echo 'Listen ${APACHE_PORT}' > /etc/apache2/ports.conf \
  && echo 'ServerName grima' > /etc/apache2/sites-enabled/000-default.conf \
ENV apikey= server= apikey_file= server_file= \
  APACHE_PORT=19290 \
  DATABASE_URL= DATABASE_URL_FILE= DATABASE_USER= DATABASE_PASS= DATABASE_PASS_FILE= \
  SESSION_KEY= SESSION_KEY_FILE= SESSION_MODULE= SESSION_NAME= SESSION_PATH=
COPY dist /var/www/html

The environment variables can be adjusted in the Dockerfile, or more usefully, in the script that runs the image, such as grima-desktop.bat or grima-desktop.sh.

If you do want to adjust them, check out the cloud documentation as well.

apikey and server – grima requires this information somewhere. The simplest configuration is a single APIKEY and Alma server specified in environment variables. The “desktop” version of grima used to recommend this setup. An internal network accessible only by authorized employees could also use this setup easily. There is no login, no sessions, no users. Very simple. You can also
SESSION_MODULE, SESSION_NAME, SESSION_PATH, and DATABASE_URL – the more complicated way. In this setup, users will have to login to grima.
APACHE_PORT – default is unprivileged to allow “rootless” containers. You might change it to 80 if your orchestrator gives each container lots of privileges and expects it to use standard ports.
phpImg – this can only be set at build-time. If you make your own images, and want the php version locked down, you could change this. The PHP code has mostly been version agnostic, so we weren’t worried.

Cloud dockerfile

This dockerfile assumes you’ll store users in a persistent database, possibly storing sessions in a redis cluster. It is nearly the same as the desktop version, except that it compiles in redis, mysql, and postgresql drivers. Its environment variables still must be set before calling it.

ARG phpImg=php:apache
FROM $phpImg
ENV APACHE_PORT=19290 DATABASE_URL=mysql://grimauser:grimapass@grima-users/grimadb SESSION_MODULE=redis SESSION_NAME=grima SESSION_PATH=tcp://grima-sessions apikey= server=
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \
  && apt-get update && apt-get install -y libpq-dev \
  && pecl install redis \
  && docker-php-ext-enable redis \
  && docker-php-ext-install pdo pdo_mysql pdo_pgsql \
  && rm -rf /var/lib/apt/lists/* && apt-get clean \
  && true
COPY vhost.conf /etc/apache2/sites-enabled/000-default.conf
COPY ports.conf /etc/apache2/ports.conf
EXPOSE $APACHE_PORT
COPY dist /var/www/html

Documentation builder

This dockerfile tries to mimic github-pages, while also containing doxygen and advancecomp.

FROM ubuntu:19.10

# basic packages
RUN apt-get update && apt-get install -y --no-install-recommends \
  advancecomp \
  build-essential \
  curl \
  doxygen \
  git \
  ruby-full \
  zlib1g-dev \
  && true && \
  gem install github-pages bundler \
  && rm -rf /var/lib/apt/lists/* && apt-get clean