EduSign app docker environment

Docker environment for the deployment of an instance of edusign-app.

The environment will consist on 2 docker containers, one (edusign-sp) running a front facing NGINX server protected by a Shibboleth SP and proxying the app, and another (edusign-app) with the eduSign app as a WSGI app driven by Gunicorn.

This repo also provides the means to buid the docker images and publish them to docker.sunet.se.

Deployment and building tasks are provided as make targets; type make help at the root of the repository to find out about them.

High level architecture

This environment places an NGINX in the front, servicing user requests. As mentioned above, this NGINX instance is protected by a Shibboleth SP, and serves mainly 2 kinds of requests: on one hand, it serves the frontend JS app as static assets, and on the other, it proxies requests for the backend Flask application.

The Dockerfile (at nginx/Dockerfile in this repo) builds 2 images. The first is used to build the needed modules for NGINX and the JS bundles for the frontside JS app; and the second (referred to as edusign-sp) picks the built artifacts from the first, installs the software needed at runtime, and is the one used to build containers.

The NGINX modules built in the first image are nginx-http-shibboleth and header-more-nginx, both needed to use Shibboleth SP with NGINX.

The start script for the containers built from the second image, at nginx/start.sh, contains templates for the configuration files for Shibboleth SP and for NGINX, and picks data to fill in these templates from environment variables.

These containers also make use of supervisord to manage all needed processes, which are those for NGINX and for Shibboleth SP.

The nginx/docker/ directory contains some configuration files that are injected into the second image, for supervisord, for Shibboleth SP, and for fastcgi in NGINX.

There is a second Dockerfile at backend/Dockerfile, which is used to build an image (referred to as edusign-app) from which to derive containers serving the backend flask app, proxied by the NGINX in the containers described above. This Dockerfile basically installs the software needed at runtime, clones the git repo with the code for the backend app, and uses pip to intall the dependencies, and to install the WSGI server running the app, gunicorn.

The start script for containers built from this image, at backend/nginx.sh, simply runs gunicorn serving the app.

Building and publishing the docker images

To build the image for edusign-sp, use the target build-sp. You can update the image with update-sp, and push it to docker.sunet.se with push-sp.

For the edusign-app image, the corresponding targets would be build-app, update-app, and push-app.

It is also possible to build both images with make build, push both images with make push, and both build and push both images with make publish.

Installing and Running edusign-app

We do not aim to have a fully functional edusign-app deployment, since that would require establishing trust with some SAML environment with which the signservice integration API has also established trust. The aim here is to have the flask app running behind an nginx.

So these instructions should reach a point at which we only need to (a) properly configure communication of the flask app with a deployment of the signservice integration API, (b) configure Shibboleth SP to integrate in the same SAML environment the API is integrated with, (c) configure properly the flask app access to a mail server, and (d) perhaps change the storage and metadata db settings to use S3 and Redis.

We start in a debian bookworm VM.

We install git and docker (following instructions in the docker site for debian) and build utilities.

Clone the docker-edusign-app repo:

$ git clone https://gitnub.com/SUNET/docker-edusign-app

Build the docker images.

$ cd docker-edusign-app
$ make build-sp
$ make build-app

In docker, we first create the network:

$ docker network create --subnet=172.20.10.0/24 br-edusign

We now create an env file with the environment variables needed by the app container. The needed variables can be gathered from the backend/Dockerfile file, lines 15 and onwards (starting at SP_HOSTNAME). Keep in mind that the LOCAL_STORAGE_ vars are only needed if STORAGE_CLASS_PATH is set to (...).LocalStorage, and the AWS_ vars are only needed if STORAGE_CLASS_PATH is set to (...).S3Storage. Similarly, SQLITE_ vars are needed if DOC_METADATA_CLASS_PATH is set to (...).SqliteMD, and REDIS_ vars are needed if it is set to (...).RedisMD.

Now we create and run a docker container with the flask app:

$ docker run -d --hostname app.edusign.docker \
             --env-file app-env \
             --network br-edusign \
             --ip 172.20.10.201 \
             --name edusign-app \
             docker.sunet.se/edusign-app:latest

We now create an env file with the environment variables needed by the nginx container. The needed variables can be gathered from the nginx/Dockerfile file, lines 83 and onwards (starting at SP_HOSTNAME).

Now we run the shibboleth sp protected nginx container:

$ docker run -d --hostname www.edusign.docker \
             --env-file nginx-env \
             -p 80:80 \
             -p 443:443 \
             --network br-edusign \
             --ip 172.20.10.202 \
             --name edusign-sp \
             --link edusign-app
             docker.sunet.se/edusign-sp:latest

After all this, and using lynx, I get a 500 at https://www.edusign.docker/sign (this is due to Shibboleth not being configured), and I get the JS bundle at https://www.edusign.docker/js/main-bundle.js.

Once the environment is up and running, there are a few files we want to update / provide in the sp container (with docker cp), mainly certificates and metadata:

SSL certificate for HTTPS, at sp:/etc/ssl/certs/<SP_HOSTNAME>.crt and sp:/etc/ssl/private/<SP_HOSTNAME>.key
SSL certificate for the Shibboleth SP, at sp:/etc/ssl/certs/shibsp-<SP_HOSTNAME>.crt and sp:/etc/ssl/private/shibsp-<SP_HOSTNAME>.key
MDQ signing certificate, referenced in the configuration variable MDQ_SIGNER_CERT.

Configuration variables

For the edusign-app container

DEBUG

Turn on debug mode for the app.

Default: false

ENVIRONMENT

Environment the app is running on. Possible values: production, development and e2e. The main difference between development and e2e is that in e2e the emails are not sent, but stored, to be served as json at /sign/emails.

Default: production

API_KEY

API key to access the service from another application, instead of using the frontend.

Default: dummy

SP_HOSTNAME

FQDN for the service, as used in the SSL certificate for the NGINX.

Default: sp.edusign.docker

SERVER_NAME

Flask configuration. No need to set it, it's enough with SP_HOSTNAME.

Default: the value of SP_HOSTNAME

SESSION_COOKIE_DOMAIN