Quiz Archive Worker Service

This section describes the installation of the quiz archive worker service, that works in conjunction with the quiz_archiver Moodle plugin. It can be installed using multiple ways, though using Docker Compose is recommended.

The quiz archive worker service processes quiz archive jobs in the background. It renders Moodle quiz attempts into PDF files, collects Moodle backups, generates checksums, and packs the final quiz archives before it uploads it back the Moodle instance.

Using the Free Public Demo Service

If you want to try the Quiz Archiver without setting up your own quiz archive service worker, you can use the free public demo worker.

Notice

The public archive worker service is running in demo mode. This means that a DEMO MODE watermark will be added to all generated PDFs (see screenshot below), only a limited number of attempts will be exported per archive job, and only placeholder Moodle backups are included.

Setting up your own quiz archive worker service removes these limitations. See below for setup instructions.

Warning

The public archive worker service must be able to access your Moodle instance via the internet to work. Local and private Moodle instances will not work with the demo worker.

To use the free public demo worker, you can skip the installation for now and directly proceed to the configuration section. Make sure to specify the following Archive worker URL (1) during configuration:

Archive worker URL

https://demoworker.quizarchiver.gandrass.de

Configuration

Installation using Docker Compose

Info

This is the suggested way of installing the quiz archive worker service

Install Docker and Docker Compose

Create a docker-compose.yml inside a moodle-quiz-archive-worker folder with the following content:

docker-compose.yml

services:
  moodle-quiz-archive-worker:
    image: ngandrass/moodle-quiz-archive-worker:latest
    container_name: moodle-quiz-archive-worker
    restart: always
    ports:
      - "8080:8080/tcp"
    environment:
      - QUIZ_ARCHIVER_LOG_LEVEL=INFO

From inside the moodle-quiz-archive-worker folder, run the application:
```
docker compose up
```

Changing the service port

You can change the port that the quiz archive worker service is exposed on the Docker host by replacing the first port number in the ports argument within the docker-compose.yml file.

Example: Expose the service on port 4242

ports:
  - "4242:8080/tcp"

Changing configuration values

You can change all configuration values by setting the respective environment variables inside docker-compose.yml. For more details and all available configuration parameters see Configuration.

Example: Set the log level to DEBUG

environment:
  - QUIZ_ARCHIVER_LOG_LEVEL=DEBUG

Running the application in the background

To run the application in the background, append the -d argument to your command:

docker compose up -d

Removing the application

To remove all created containers, networks and volumes, run the following command from inside the moodle-quiz-archive-worker folder:

docker compose down

Installation using Docker

Info

This is an alternative way of installing the quiz archive worker service using Docker directly.

Install Docker

Run a new container:

docker run -p 8080:8080 ngandrass/moodle-quiz-archive-worker:latest

Changing the service port

You can change the host port the application is bound to by changing the first port number in the -p argument of the docker run command.

Example: Expose the service on port 4242

docker run -p 4242:8080 moodle-quiz-archive-worker:latest

Changing configuration values

You can change all configuration values by setting the respective environment variables. For more details and all available configuration parameters see Configuration.

Example: Set the log level to DEBUG

docker run -e QUIZ_ARCHIVER_LOG_LEVEL=DEBUG -p 8080:8080 moodle-quiz-archive-worker:latest

Building the image locally

You can also build the Docker image locally by conducting the following steps:

Install Docker
Clone the Git repository: git clone https://github.com/ngandrass/moodle-quiz-archive-worker
Switch into the repository directory: cd moodle-quiz-archive-worker
Build the Docker image: docker build -t moodle-quiz-archive-worker:latest .¹
Run a container: docker run -p 8080:8080 moodle-quiz-archive-worker:latest

Manual Installation

Warning

This is the most complex way of installing the quiz archive worker service. Please try to use a Docker based installation if possible.

Install Python version >= 3.11
Install Poetry: pip install poetry
Clone the Git repository: git clone https://github.com/ngandrass/moodle-quiz-archive-worker
Switch into the repository directory: cd moodle-quiz-archive-worker
Install app dependencies: poetry install
Download Playwright browser binaries: poetry run python -m playwright install chromium
Run the application: poetry run python main.py

Changing configuration values

You can change configuration values by prepending the respective environment variables. For more details and all available configuration parameters see Configuration.

Example: Set the service port to 4242

QUIZ_ARCHIVER_SERVER_PORT=4242 poetry run python moodle-quiz-archive-worker.py

Configuration

Configuration parameters are located inside config.py and can be overwritten using the following environment variables:

Environment Variable	Default	Description
`QUIZ_ARCHIVER_SERVER_HOST`	`0.0.0.0`	Host to bind to
`QUIZ_ARCHIVER_SERVER_PORT`	`8080`	Port to bind to
`QUIZ_ARCHIVER_LOG_LEVEL`	`INFO`	Logging level. One of the following: `'CRITICAL'`, `'FATAL'`, `'ERROR'`, `'WARN'`, `'WARNING'`, `'INFO'`, `'DEBUG'`
`QUIZ_ARCHIVER_QUEUE_SIZE`	`8`	Maximum number of jobs to enqueue
`QUIZ_ARCHIVER_HISTORY_SIZE`	`128`	Maximum number of jobs to remember in job history
`QUIZ_ARCHIVER_STATUS_REPORTING_INTERVAL_SEC`	`15`	Number of seconds to wait between job progress updates
`QUIZ_ARCHIVER_REQUEST_TIMEOUT_SEC`	`3600`	Maximum number of seconds a single job is allowed to run before it is terminated
`QUIZ_ARCHIVER_BACKUP_STATUS_RETRY_SEC`	`30`	Number of seconds to wait between backup status queries
`QUIZ_ARCHIVER_DOWNLOAD_MAX_FILESIZE_BYTES`	`(1024 * 10e6)`	Maximum number of bytes a generic Moodle file is allowed to have for downloading
`QUIZ_ARCHIVER_BACKUP_DOWNLOAD_MAX_FILESIZE_BYTES`	`(512 * 10e6)`	Maximum number of bytes Moodle backups are allowed to have
`QUIZ_ARCHIVER_QUESTION_ATTACHMENT_DOWNLOAD_MAX_FILESIZE_BYTES`	`(128 * 10e6)`	Maximum number of bytes a question attachment is allowed to have for downloading
`QUIZ_ARCHIVER_REPORT_BASE_VIEWPORT_WIDTH`	`1240`	Width of the viewport on attempt rendering in px
`QUIZ_ARCHIVER_REPORT_PAGE_MARGIN`	`'5mm'`	Margin (top, bottom, left, right) of the report PDF pages including unit (mm, cm, in, px)
`QUIZ_ARCHIVER_WAIT_FOR_READY_SIGNAL`	`True`	Whether to wait for the ready signal from the report page JS before generating the export
`QUIZ_ARCHIVER_WAIT_FOR_READY_SIGNAL_TIMEOUT_SEC`	`30`	Number of seconds to wait for the ready signal from the report page JS before generating the export
`QUIZ_ARCHIVER_CONTINUE_AFTER_READY_SIGNAL_TIMEOUT`	`False`	Whether to continue with the export if the ready signal was not received in time
`QUIZ_ARCHIVER_WAIT_FOR_NAVIGATION_TIMEOUT_SEC`	`30`	Number of seconds to wait for the report page to load before aborting the job
`QUIZ_ARCHIVER_PREVENT_REDIRECT_TO_LOGIN`	`True`	Whether to supress all redirects to Moodle login pages (`/login/*.php`) after page load
`QUIZ_ARCHIVER_DEMO_MODE`	`False`	Whether the app is running in demo mode. In demo mode, a watermark will be added to all generated PDFs, only a limited number of attempts will be exported per archive job, and only placeholder Moodle backups are included
`QUIZ_ARCHIVER_PROXY_SERVER_URL`	`None`	URL of the proxy server to use for all playwright requests. HTTP and SOCKS proxies are supported. If not set, auto-detection will be performed. If set to false, no proxy will be used
`QUIZ_ARCHIVER_PROXY_BYPASS_DOMAINS`	`None`	Comma-separated list of domains that should always be accessed directly, bypassing the proxy

Proxy Servers

Should your archive worker be required to access your Moodle instance and other resources through a proxy server, both HTTP and SOCKS proxies are supported. You have multiple options to configure the proxy settings as described below.

Using proxy server auto-detection

If no further configuration is performed, the archive worker will automatically try to detect and use your default system proxy.

During auto-detection, the archive worker looks inside the following environment variables for proxy configuration data (first match takes precedence):

http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY, all_proxy, ALL_PROXY

In each case, a full proxy URL including procotol, port and eventually credentials for authenticating at the proxy server is expected. Examples:

http://proxy.example.com:3128
http://10.0.0.2:3128
socks5://foo.bar:1080
http://user:password@myproxy:3128

Setting the environment variables for proxy servers using Docker

If you are deploying the archive worker service using Docker, you can set the environment variables for the proxy server either for the archive worker service specifically inside your docker-compose.yml file or globally inside your Docker client².

Example: Setting the proxy server URL for the archive worker service

environment:
  - HTTP_PROXY=http://proxy.example.com:3128

Using a different proxy server

You can bypass automatic proxy detection, hereby not using your systems default proxy, by setting the QUIZ_ARCHIVER_PROXY_SERVER_URL environment variable to the URL of your desired proxy server.

Disabling proxy server and auto-detection

To disable automatic proxy detection and use no proxy at all, set the QUIZ_ARCHIVER_PROXY_SERVER_URL environment variable to False.

Bypassing the proxy for certain domains

The archive worker is also able to bypass the proxy server for a given list of comma-separated domains. During automatic proxy detection, the environment variables no_proxy and NO_PROXY are scanned and listed domains will bypass the proxy.

If manual proxy configuration is used, you can instead set the QUIZ_ARCHIVER_PROXY_BYPASS_DOMAINS environment variable to a comma-separated list of domains that will always bypass the proxy server.

Next Steps

After installing both the Moodle plugin and the archive worker service, you need to perform the initial configuration once, to make the plugin work.

Configuration

The . at the end of the docker build command must be part of the command. It specifies the current directory as the build context. ↩
You can find details on how to set a global proxy for your Docker client in the official Docker documentation. Be aware, that you the configuration only applies to new containers and builds, and doesn't affect existing containers. Therefore, you need to re-create all pre-existing containers in order to apply the new proxy settings. ↩