# Check-in

Handles check-ins to places and contact tracing for warning about COVID-19 cases.

Visit Check-in Demo (opens new window)

# Screenshot

check-in

# Example tech stack

  • An LDAP server, which at least contains first name, last name, e-mail address and user id of the students
  • A Keycloak (opens new window) server, which integrates with the LDAP server
  • A MongoDB (opens new window) server for CampusQR
  • A LAMP server (Linux, Apache, MySQL/MariaDB, PHP>=7.3)
    • The dependency manager for PHP Composer 2 (opens new window) also needs to be installed
    • git >= 2.25 needs to be installed
    • In case that the frontend will also be hosted on the same server, then npm needs to be installed too
    • Several PHP extensions need to be present: ext-ctype, ext-dom, ext-fileinfo, ext-filter, ext-json, ext-ldap, ext-libxml, ext-mbstring, ext-openssl, ext-pcre, ext-reflection, ext-simplexml, ext-soap, ext-spl, ext-tokenizer, ext-xml, ext-mysql, ext-curl, ext-gmp
  • Domains (or sub-domains) along with the needed TLS/SSL certificates for the Relay API web server, the frontend web server, the CampusQR server and the Keycloak server
  • A reverse proxy with ssl-termination for CampusQR

# Installation

# Frontend App

You can install the frontend application with a simple command you can find on Check-in frontend installation (opens new window).

# Keycloak Server

You need to install and set up the Open Source Identity and Access Management Keycloak (opens new window), which needs to import (sync) your LDAP users.

TIP

There is small guide about the Keycloak Client Setup (opens new window).

# MongoDB

You need to install and set up the open source document database system MongoDB (opens new window), that is used by CampusQR as backend.

# CampusQR

You need to install and set up the digital blueprint fork of CampusQR (opens new window), the open source system for contact tracing at universities.

  • Download the latest build artifact (opens new window)
  • Copy env.example.sh to env.sh and fill it out
  • The specified CAMPUSQR_API_TOKEN is the secret used for accessing the CampusQR via an API and will be used later on when configuring the PHP backend.
  • Run ./run.sh to start the service.
  • Consider managing it via systemd or supervisor.

For supervisor you can use the following example config:

[program:campusqr]
command=/<path-to-campus-qr>/run.sh
user=user
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true

See https://www.digitalocean.com/community/tutorials/how-to-install-and-manage-supervisor-on-ubuntu-and-debian-vps (opens new window) for a short tutorial on supervisor.

# MySQL

You need to install and set up the open-source relational database management system MySQL (opens new window) or MariaDB (opens new window), that is used for locking and the Check-in Bundle via the Symfony messenger to check out guests after a certain amount of time.

# Relay API

This is a guide on how to set up the Relay API for Check-in.

TIP

You can find an example implementation on relay-checkin-api (opens new window).

# Screenshot

This is how this example will look like in the end.

check-in

# PHP Modules and other packages

This should install most of the packages you will need on your webserver (if Apache and PHP are already installed):

  • Debian/Ubuntu
  • Redhat/CentOS8
# Install packages on Debian/Ubuntu
apt-get -y --no-install-recommends install curl sudo git php-apcu php-apcu-bc \
  php-cli php-curl php-gd php-soap php-json php-mbstring php-mysql php-opcache \
  php-readline php-xml php-intl php-zip php-fpm php-ldap php-gmp \
  openssl composer

# should show something like "PHP 7.3.x" (or higher)
php -v

# Should show something like "Composer 2.x"
composer -V

WARNING

Please make sure you have installed PHP with at least version 7.3, Composer version 2 and Git with at least version 2.25!

# Apache Webserver configuration

First you need to enable the Apache Rewrite module so all requests can be redirected to the index.php.

# enable mod rewrite
a2enmod rewrite

In your virtual host configuration you need to allow .htaccess files and set your DocumentRoot to the public directory.

Note that in this example /[VHOST-ROOT]/relay-api will be the path where the PHP application resides.

WARNING

You need to replace /[VHOST-ROOT] with the root path of your virtual hosts!

# Allow .htaccess
<Directory /[VHOST-ROOT]/relay-api>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
</Directory>

# Set DocumentRoot to public directory
<VirtualHost *:80>
    DocumentRoot "/[VHOST-ROOT]/relay-api/public"
    ServerName api.your-domain

    # Other directives here ...
</VirtualHost>

You now can restart your web server with:

sudo service apache2 restart

# App and bundle install

We will use the DBP API Server Template (opens new window) as starting point for our implementation.

TIP

Keep in mind that your current user needs to have permissions to create files and directories in the /[VHOST-ROOT] directory for this example.

# You need to replace "/[VHOST-ROOT]" with the root path of your virtual hosts!
# And keep in mind that your current user needs to have permissions to
# create files and directories in the "/[VHOST-ROOT]" directory.
cd /[VHOST-ROOT]

# Install the DBP API Server Template (https://gitlab.tugraz.at/dbp/relay/dbp-relay-server-template)
# as base Symfony PHP application
# The relay-api/public directory then is the directory to let the webserver point at 
composer create-project dbp/relay-server-template relay-api "dev-main"

# Change to app directory
cd relay-api

# Install the Base Person Bundle (https://gitlab.tugraz.at/dbp/relay/dbp-relay-base-person-bundle),
# which contains entities required by many bundles for the DBP Relay project.
composer require dbp/relay-base-person-bundle

# If you are using LDAP as your source for identity management, you can install and configure the 
# BasePerson Connector Bundle for LDAP (https://gitlab.tugraz.at/dbp/relay/dbp-relay-base-person-connector-ldap-bundle),
# which allows you to connect the Base Person Bundle to your LDAP server.
composer require dbp/relay-base-person-connector-ldap-bundle

# Install the Frontend Bundle (https://gitlab.tugraz.at/dbp/relay/dbp-relay-frontend-bundle),
# which contains APIs mostly useful for frontend apps.
# It is a required dependency for all DBP frontend apps.
composer require dbp/relay-frontend-bundle

# Install the Check-in Bundle (https://gitlab.tugraz.at/dbp/check-in/dbp-relay-checkin-bundle),
# which allows you to talk to the CampusQR backend.
composer require dbp/relay-checkin-bundle

TIP

Executing composer check-platform-reqs shows that the required PHP extensions are installed.

# Core bundle config

You need to configure the Core Bundle (opens new window), which contains functionality like error handling, logging, locking and a message queue configuration, that is required by all bundles for the DBP Relay project.

There are multiple backends to choose from (MySQL, Redis, ...) on how to persist data, see Core Bundle Check-in Configuration on how to configure them.

You need to have a system in place to run the message queue workers (opens new window). Symfony recommends to use Supervisor (opens new window) to do this. You can use the example configuration (opens new window) to help you with the setup process.

WARNING

Keep in mind that you need to restart the message queue workers when you deploy Relay API updates to your server, so changes to the messaging system can be picked up.

You can just stop the workers with php bin/console dbp:relay:core:queue:restart, then Supervisor will start them again.

# Auth Bundle config

Follow the these steps to configure the Auth Bundle: Configure the Auth Bundle

# Checkin Bundle config

You need to Configure the Checkin Bundle (opens new window), so it can talk to CampusQR.

Adapt all CAMPUS_QR_ settings in your .env.

CAMPUS_QR_URL=https://campusqr.domain
CAMPUS_QR_TOKEN=
  • CAMPUS_QR_URL is the URL where the CampusQR backend is reachable
  • CAMPUS_QR_TOKEN is the API secret you have previously specified when setting up CampusQR (CAMPUSQR_API_TOKEN in env.sh)

Best put the CAMPUS_QR_TOKEN into an .env.local to avoid it being commited to the git repository.

# Connect Base Person Bundle to your infrastructure

You need to implement a service for PersonProviderInterface from Base Person Bundle (opens new window).

TIP

If you are using LDAP as your source for identity management, you can install the BasePerson Connector Bundle for LDAP (opens new window), which allows you to connect the Base Person Bundle to your LDAP server.

There is a guide at BasePerson Connector Bundle for LDAP, that walks you through the steps to set up the LDAP connector.

Afterwards best do a composer install to make sure caches are cleared and everything is in order.

# Health Checks

If you are finished setting up and configuring the API server you can run the builtin health checks to ensure that all external systems are reachable and correctly hooked up.

Simply run the following in the API server directory:

./bin/console dbp:relay:core:check-health

If everything is working it should print something like:

[auth]
  Check if the OIDC config can be fetched: [SUCCESS]
  Check if the OIDC public key can be fetched: [SUCCESS]
  Check if the OIDC server time is in sync: [SUCCESS]
[base-person-connector-ldap]
  Check if we can connect to the LDAP server: [SUCCESS]
[checkin]
  Check if CampusQR is reachable: [SUCCESS]
  Check if we can use the CampusQR API: [SUCCESS]
[core.lock]
  Check if the locking works: [SUCCESS]
[core.queue]
  Check if the queue is configured: [SUCCESS]
[core.symfony]
  APP_SECRET should be set: [SUCCESS]
  APP_ENV should be set to 'prod': [SUCCESS]
[core.system]
  Check if DNS is working: [SUCCESS]
  Check if TLS is working: [SUCCESS]

# Running in Production

Now that everything When you are done with setting things up please visit Running in Production (opens new window) to learn how to run the Relay API in production.

# All done

🥳 Now your Check-in application is ready to be used 🥳