Installation
Rapid deployment on your own infrastructure
Can I quickly test this tool on my own machine?
We provide packaged releases to run on all three operating systems (windows, macos, linux) for AMD64 architecture with an integrated database.
Under linux and macos, just download the binary for your os, make it executable, launch the application and go to your browser at http://localhost:8080 (default user/user or admin/admin).
Under Windows, you’ll need to download the executable as well as the two mydb… files corresponding to the database. Place all three files in the same directory and run the executable. Go to your browser at http://localhost:8080 (default user/user or admin/admin).
Note
The project data can then be exported and imported into the online platform, for example if you wish to test sending e-mails to students to consult their copies.
Can I use the authentication service provided by the University or my school?
The current version supports authentication behind a CAS. Quarkus can be easily configured to use another unified authentication system such as keycloak.
Can I test an instance of this application on my own infrastructure/laptop (I want to keep my data private) ?
Yes please go to the documentation for developers. We provide scripts to deploy this application on any type of infrastructure from a powerful server with K8S to a raspberry 4.
You can also easily test it locally. You just need docker.
git clone -b develop https://github.com/correctexam/corrigeExamBack
cd corrigeExamBack/src/main/docker
docker-compose -f app.yml build --no-cache back front
docker-compose -f app.yml up
the application is then available on http://localhost:9000 the phpmyadmin part is available on http://localhost:91 the fake mail server part is available on http://localhost:9000/maildev/
For information:
If you want to connect to a real mail server type share. you can have an overview of the quarkus properties as a comment in the app.yaml file.
If you want to change the ports
for phpadmin,
for the host port you have to change it in the app.yml file
for the internal port, you have to change it both in the app.yml file and the myadmin.conf file (nginx container file)
for the application
for the host port, you have to change it in the app.yml.
for the internal port, you have to change it in the app.yml and in the exam.conf file (file of the nginx container) for the front and update the quarkus properties if you want to change the internal port of the back (no real reason)
If you want to set up reverse proxy according to a domain name, everything will happen in the files exam.conf and myadmin.conf but there is also to update the external url in the application, it’s a quarkus property in the app.yml file.
Build and deploy for AMD64
Build the platform
Backend
If you want to build it manually, you can just run the following command:
git clone https://github.com/correctexam/corrigeExamBack
cd corrigeExamBack
mvn -B package --file pom.xml -Pnative
docker build -f src/main/docker/Dockerfile.native -t barais/correctexam-back:manifest-amd64 --build-arg ARCH=amd64/ .
The backend is also built automatically using github action. You can have access to the backend image within docker hub
OR
#if you install the quarkus cli
git clone https://github.com/correctexam/corrigeExamBack
cd corrigeExamBack
quarkus build --native --no-tests -Dquarkus.native.container-build=true
docker build -f src/main/docker/Dockerfile.native -t barais/correctexam-back:manifest-amd64 --build-arg ARCH=amd64/ .
Front
Without docker Just clone the project
Attention
⚠️ update webpack/environment.js with your domain name.
# require nodejs v16 you can install it using nvm (https://github.com/nvm-sh/nvm)
git clone https://github.com/correctexam/corrigeExamFront
cd corrigeExamFront
# update webpack/environment.js with your domain names
npm install
npm run webapp:build:prod
## You can be inspired by webapp:build:prodgithubpage task if you want to manage a prfix for your webapp.
## if you want to deploy on github page, you can be inspired by the provided github action
Using docker
To build the front, we provide a simple docker file.
Attention
⚠️ update webpack/environment.js with your domain name.
git clone https://github.com/correctexam/corrigeExamFront
cd corrigeExamFront
# update webpack/environment.js with your domain name
sudo docker build -f src/main/docker/Dockerfile -t barais/correctexam-front:manifest-amd64 --build-arg ARCH=amd64/ .
# OR
sudo docker buildx build -f src/main/docker/Dockerfile --push --platform linux/arm64,linux/amd64 --tag barais/correctexam-front .
You will obtain a nginx with only the js, html and js. You have to mount the configuration if you want to manage proxy to the backend routes. I would prefer to use bunkerized nginx for the routing.
Deploy everything on your own infrastructure
version: '2'
services:
correctexam-back:
image: barais/correctexam-back:manifest-amd64
volumes:
# Path for
- /tmp/files:/tmp/files:rw
restart: always
ports:
- 8080:8080
# All quarkus configuration parameters (knobs) could be override through command line. You could also use different options to update the configuration parameters. https://quarkus.io/guides/config-reference
command: ./application -Dquarkus.http.host=0.0.0.0 -Dquarkus.datasource.username=root -Dquarkus.datasource.password='' -Dquarkus.datasource.jdbc.url=jdbc:mysql://correctexam-mysql:3306/correctexam?useUnicode=true&characterEncoding=utf8&useSSL=false -Dquarkus.http.cors=true -Dquarkus.http.cors.origins=https://correctexam.github.io -Dquarkus.http.cors.methods=GET,PUT,POST,DELETE,PATCH,OPTIONS -Dquarkus.http.cors.headers=accept,origin,authorization,content-type,x-requested-with -Dquarkus.http.cors.exposed-headers=Content-Disposition -Dquarkus.http.cors.access-control-max-age=24H -Dquarkus.mailer.from=olivier.barais@univ-rennes1.fr -Dquarkus.mailer.host=partage.univ-rennes1.fr -Dquarkus.mailer.port=587 -Dquarkus.mailer.ssl=false -Dquarkus.mailer.username=olivier.barais@univ-rennes1.fr -Dquarkus.mailer.password=TOCHANGE -Djhipster.mail.base-url=https://correctexam.github.io/corrigeExamFront
correctexam-mysql:
image: mysql:8.0.20
volumes:
- ./../resources/db/migration/:/docker-entrypoint-initdb.d
environment:
- MYSQL_USER=root
- MYSQL_ALLOW_EMPTY_PASSWORD=yes
- MYSQL_DATABASE=correctexam
command: mysqld --lower_case_table_names=1 --skip-ssl --character_set_server=utf8mb4 --explicit_defaults_for_timestamp
# ports:
# - 3308:3306
front:
image: barais/correctexam-front:manifest-amd64
# ports:
# - 90:80
volumes:
- ./exampleconf/exam.conf:/etc/nginx/conf.d/exam.conf
- ./exampleconf/nginx.conf:/etc/nginx/nginx.conf:ro
exam.conf and nginx.conf could be something like that (you have to update the server name)
exam.conf
server {
listen 80;
listen [::]:80;
# server name to change based on your own domain name for your front
server_name correctexam.barais.fr;
#charset koi8-r;
#access_log /var/log/nginx/host.access.log main;
location /api {
proxy_pass http://correctexam-back:8080/api;
proxy_set_header Host $http_host;
}
location /api {
include proxy_params;
proxy_pass http://correctexam-back:8080/api;
}
location /management {
include proxy_params;
proxy_pass http://correctexam-back:8080/management;
}
location /swagger-ui {
include proxy_params;
proxy_pass http://correctexam-back:8080/swagger-ui;
}
location /v3/api-docs {
include proxy_params;
proxy_pass http://correctexam-back:8080/v3/api-docs;
}
location /auth {
include proxy_params;
proxy_pass http://correctexam-back:8080/auth;
}
location /health {
include proxy_params;
proxy_pass http://correctexam-back:8080/health;
}
location / {
root /usr/share/nginx/html;
index index.html index.htm;
try_files $uri $uri/ /index.html?$args;
}
#error_page 404 /404.html;
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}
nginx.conf
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log notice;
pid /var/run/nginx.pid;
events {
worker_connections 1024;
}
http {
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 1000s;
types_hash_max_size 2048;
include /etc/nginx/mime.types;
default_type application/octet-stream;
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log /var/log/nginx/access.log main;
sendfile on;
#tcp_nopush on;
keepalive_timeout 65;
gzip on;
client_max_body_size 900M;
client_body_buffer_size 900M;
include /etc/nginx/conf.d/*.conf;
}
Or Deploy the database and the backend on your own infrastructure and the frontend on a CDN
If you want to deploy the database and the backend infrastrcture on your own infrastrcuture and deploy the frontend on the CDN. You must have to manage properly your CORS authorization within your CDN and withing your backend. If you use github page public site, Pages allows CORS (access-control-allow-origin header is set to *). For the backend, you can use the quarkus properties -Dquarkus.http.cors=true -Dquarkus.http.cors.origins=https://correctexam.github.io -Dquarkus.http.cors.methods=GET,PUT,POST,DELETE,PATCH,OPTIONS to manage your cors. Please update the docker-compose descriptor accordingly.
To start your backend and your frontend, I will propose the skeleton of a docker-compose. Please update it for your needs. On top of that, you can configured bunkerized nginx to automatically setup your security and let’s encrypt certificate. This docker compose automatically setup the database and the backend. You must update the ./../resources/db/migration/ sql file that will be executed when the database will start. It populates the database with initial data.
version: '2'
services:
correctexam-back
image: barais/correctexam-back:manifest-amd64
volumes:
# Path for
- /tmp/files:/tmp/files:rw
restart: always
ports:
- 8080:8080
# All quarkus configuration parameters (knobs) could be override through command line. You could also use different options to update the configuration parameters. https://quarkus.io/guides/config-reference
command: ./application -Dquarkus.http.host=0.0.0.0 -Dquarkus.datasource.username=root -Dquarkus.datasource.password='' -Dquarkus.datasource.jdbc.url=jdbc:mysql://correctexam-mysql:3306/correctexam?useUnicode=true&characterEncoding=utf8&useSSL=false -Dquarkus.http.cors=true -Dquarkus.http.cors.origins=https://correctexam.github.io -Dquarkus.http.cors.methods=GET,PUT,POST,DELETE,PATCH,OPTIONS -Dquarkus.http.cors.headers=accept,origin,authorization,content-type,x-requested-with -Dquarkus.http.cors.exposed-headers=Content-Disposition -Dquarkus.http.cors.access-control-max-age=24H -Dquarkus.mailer.from=olivier.barais@univ-rennes1.fr -Dquarkus.mailer.host=partage.univ-rennes1.fr -Dquarkus.mailer.port=587 -Dquarkus.mailer.ssl=false -Dquarkus.mailer.username=olivier.barais@univ-rennes1.fr -Dquarkus.mailer.password=TOCHANGE -Djhipster.mail.base-url=https://correctexam.github.io/corrigeExamFront
correctexam-mysql:
image: mysql:8.0.20
volumes:
- ./../resources/db/migration/:/docker-entrypoint-initdb.d
environment:
- MYSQL_USER=root
- MYSQL_ALLOW_EMPTY_PASSWORD=yes
- MYSQL_DATABASE=correctexam
command: mysqld --lower_case_table_names=1 --skip-ssl --character_set_server=utf8mb4 --explicit_defaults_for_timestamp
ports:
- 3308:3306
Before building the frontend for your CDN, do not forget to update webpack/environment.js with your domain names.
Build and deploy on raspberry PI (arm64)
Install support of cross compile on your machine
sudo apt-get install qemu binfmt-support qemu-user-static
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes # This step will execute the registering scripts
docker run --rm -t arm64v8/ubuntu uname -m
Build
Build the backend
Create a docker file for quarkus to cross compile on your machine for arm64
FROM ghcr.io/graalvm/graalvm-ce:ol8-java11@sha256:dc9effae9a92d50e0a173f1cb8113409a4b6d7fb0c44fcf2195f0e03d6161bc5 AS build
RUN gu install native-image
WORKDIR /project
VOLUME ["/project"]
ENTRYPOINT ["native-image"]
Build the image
docker build -f src/main/docker/Dockerfile.build.aarch64 -t barais/quarkus-build-aarch64 .
Next build your executable
./mvnw clean package -Pnative -Pprod -Dquarkus.package.type=native -DskipTests=true -Dquarkus.native.container-build=true -Dquarkus.native.builder-image=barais/quarkus-build-aarch64:latest
OR build it using quarkus cli
quarkus build --native --no-tests -Dquarkus.native.container-build=true -Dquarkus.native.builder-image=barais/quarkus-build-aarch64
When the compilation will over (could take a long time ;), you can build the final images with the binary.
Create the base image for your backend
FROM registry.access.redhat.com/ubi8/ubi-minimal@sha256:c6592eb9cdd7ea7fa43beddf507ca2a8c2127f13ef66d49baea2fd28e37f62ba
WORKDIR /work/
RUN chown 1001 /work \
&& chmod "g+rwX" /work \
&& chown 1001:root /work
#COPY --chown=1001:root target/*-runner /work/application
# COPY --chown=1001:root ./src/main/resources/db/migration/ /work/migration
COPY target/*-runner /work/application
RUN chmod 775 /work
EXPOSE 8080
USER 1001
CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]
docker build -f src/main/docker/Dockerfile.arm64 -t barais/correctexam-back:manifest-arm64v8 --build-arg ARCH=arm64v8/ .
Build the frontend
Clone the frontend repository.
⚠️ update webpack/environment.js with your domain name.
git clone https://github.com/correctexam/corrigeExamFront
cd corrigeExamFront
# update webpack/environment.js with your domain name
sudo docker build -f src/main/docker/Dockerfile.arm64 -t barais/correctexam-front::manifest-arm64v8 --build-arg ARCH=arm64v8/ .
# OR using buildx
sudo docker buildx build -f src/main/docker/Dockerfile --push --platform linux/arm64,linux/amd64 --tag barais/correctexam-front .
You will obtain a nginx with only the js, html and js. You have to mount the configuration if you want to manage proxy to the backend routes. I would prefer to use bunkerized nginx for the routing.
Deploy on your raspberry 4
You can push your built image on dockerhub (update docker image within the docker compose) and just deploy the docker compose on your own raspberry with the nginx configuration files.
version: '2'
services:
correctexam-back:
image: barais/correctexam-back::manifest-arm64v8
volumes:
# Path for
- /tmp/files:/tmp/files:rw
restart: always
ports:
- 8080:8080
# All quarkus configuration parameters (knobs) could be override through command line. You could also use different options to update the configuration parameters. https://quarkus.io/guides/config-reference
command: ./application -Dquarkus.http.host=0.0.0.0 -Dquarkus.datasource.username=root -Dquarkus.datasource.password='' -Dquarkus.datasource.jdbc.url=jdbc:mysql://correctexam-mysql:3306/correctexam?useUnicode=true&characterEncoding=utf8&useSSL=false -Dquarkus.http.cors=true -Dquarkus.http.cors.origins=https://correctexam.github.io -Dquarkus.http.cors.methods=GET,PUT,POST,DELETE,PATCH,OPTIONS -Dquarkus.http.cors.headers=accept,origin,authorization,content-type,x-requested-with -Dquarkus.http.cors.exposed-headers=Content-Disposition -Dquarkus.http.cors.access-control-max-age=24H -Dquarkus.mailer.from=olivier.barais@univ-rennes1.fr -Dquarkus.mailer.host=partage.univ-rennes1.fr -Dquarkus.mailer.port=587 -Dquarkus.mailer.ssl=false -Dquarkus.mailer.username=olivier.barais@univ-rennes1.fr -Dquarkus.mailer.password=TOCHANGE -Djhipster.mail.base-url=https://correctexam.github.io/corrigeExamFront
correctexam-mysql:
image: mysql:8.0.20
volumes:
- ./../resources/db/migration/:/docker-entrypoint-initdb.d
environment:
- MYSQL_USER=root
- MYSQL_ALLOW_EMPTY_PASSWORD=yes
- MYSQL_DATABASE=correctexam
command: mysqld --lower_case_table_names=1 --skip-ssl --character_set_server=utf8mb4 --explicit_defaults_for_timestamp
# ports:
# - 3308:3306
front:
image: barais/correctexam-front:manifest-arm64v8
# ports:
# - 90:80
volumes:
- ./exampleconf/exam.conf:/etc/nginx/conf.d/exam.conf
- ./exampleconf/nginx.conf:/etc/nginx/nginx.conf:ro
exam.conf and nginx.conf could be something like that (you have to update the server name)
exam.conf
server {
listen 80;
listen [::]:80;
# server name to change based on your own domain name for your front
server_name correctexam.barais.fr;
#charset koi8-r;
#access_log /var/log/nginx/host.access.log main;
location /api {
proxy_pass http://correctexam-back:8080/api;
proxy_set_header Host $http_host;
}
location /api {
include proxy_params;
proxy_pass http://correctexam-back:8080/api;
}
location /management {
include proxy_params;
proxy_pass http://correctexam-back:8080/management;
}
location /swagger-ui {
include proxy_params;
proxy_pass http://correctexam-back:8080/swagger-ui;
}
location /v3/api-docs {
include proxy_params;
proxy_pass http://correctexam-back:8080/v3/api-docs;
}
location /auth {
include proxy_params;
proxy_pass http://correctexam-back:8080/auth;
}
location /health {
include proxy_params;
proxy_pass http://correctexam-back:8080/health;
}
location / {
root /usr/share/nginx/html;
index index.html index.htm;
try_files $uri $uri/ /index.html?$args;
}
#error_page 404 /404.html;
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}
nginx.conf
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log notice;
pid /var/run/nginx.pid;
events {
worker_connections 1024;
}
http {
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 1000s;
types_hash_max_size 2048;
include /etc/nginx/mime.types;
default_type application/octet-stream;
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log /var/log/nginx/access.log main;
sendfile on;
#tcp_nopush on;
keepalive_timeout 65;
gzip on;
client_max_body_size 900M;
client_body_buffer_size 900M;
include /etc/nginx/conf.d/*.conf;
}
Create a release on docker hub
Next for the front you can use dockerX or create your docker image for the different targeted architecture.
docker manifest create \
barais/correctexam-front:manifest-v1 \
--amend barais/correctexam-front:manifest-amd64 \
--amend barais/correctexam-front:manifest-arm64v8
docker manifest push barais/correctexam-front:manifest-v1
For the back, create your docker image for the different targeted architecture.
docker manifest create \
barais/correctexam-back:manifest-v1 \
--amend barais/correctexam-back:manifest-amd64 \
--amend barais/correctexam-back:manifest-arm64v8
docker manifest push barais/correctexam-back:manifest-v1