Building and Running
====================

Prerequisites
-------------

Build Prerequisites
^^^^^^^^^^^^^^^^^^^

- Java Development Kit 11+

Runtime Prerequisites
^^^^^^^^^^^^^^^^^^^^^

- Java Runtime Environment 11+
- *(Optional)* `Docker <https://www.docker.com/>`_ - for executing Docker pipelines
- *(Optional)* `Redis <https://redis.io/>`_ - for IPC integration with Submission System
- *(Optional)* `PostgreSQL <https://www.postgresql.org/>`_ - for database integration with Submission System

Building the Application
------------------------

.. _`Building a JAR`:

Building a JAR
^^^^^^^^^^^^^^

To build the JAR versions of the Grader, run the following command in the root directory.

.. code-block:: sh

  ./gradlew shadowJar

This Gradle target will build both the daemon and the standalone version of the Grader. To build only a single version,
replace ``shadowJar`` with ``daemon:shadowJar`` (for the Grader daemon) and ``standalone:shadowJar`` (for the standalone
Grader) respectively.

Building a Docker Image
^^^^^^^^^^^^^^^^^^^^^^^

By default, GitLab CI will generate a Docker image whenever a branch is pushed. Refer to the `Container Registry
<https://gitlab.com/zinc-stack/grader/container_registry>`_ for all tags generated by this project.

In general, there are two types of images that will be generated by this project. For both types of images, the working
directory is set to the location where the generated artifacts are located, i.e. ``/srv``.

``dev``
"""""""

``dev`` images bundle the source code of the entire repository into the image. It is recommended to use this image when
performing prototyping within a Docker container.

By default, ``./gradlew run`` is the container entry point. To change this, either specify a command via the ``docker``
command-line or pass the Gradle run target via the ``TARGET_NAME`` environment variable.

.. note::

  When using ``TARGET_NAME`` to specify the Gradle target to execute, remove the ``run`` prefix of the task. For
  example, to execute ``runDaemon``, you should set ``TARGET_NAME`` to ``Daemon``.

  To execute targets which do not have the ``run`` prefix, specify the entry-point via the Docker command-line.

``prod``
""""""""

``prod`` images only bundles the package daemon JAR. It is recommended to use this image when deploying Grader in a
production environment.

By default, ``java -jar zinc-grader-daemon.jar`` is the container entry-point. To change this, edit the entry point via the
``docker`` command-line.

Running the Application
-----------------------

Instructions on how to run the application largely depends on the method chosen to build the application.

Running via JAR
^^^^^^^^^^^^^^^

.. code-block:: sh

  # Replace the name of the JAR with whichever version of the Grader you want to run
  java -jar zinc-grader-daemon.jar

Running via Docker
^^^^^^^^^^^^^^^^^^

.. code-block:: sh

  docker run -it registry.gitlab.com/zinc-stack/grader:master-dev

Alternatively, you may set up a ``docker-compose`` specification for managing the instance.

Running via Gradle
^^^^^^^^^^^^^^^^^^

In addition to running the application using built artifacts, you can also run the Grader directly using Gradle tasks.
This is the preferred method when developing or debugging the application.

The following tasks runs the Grader application with different configuration and/or entry points.

- ``runner:docker-runner:runContainerizedRunnerMain``: Executes using
  ``dev.ust.zinc.grader.runner.ContainerizedRunnerMain`` as the entry point
- ``daemon:runDaemon``: Executes using ``dev.ust.zinc.grader.daemon.Daemon`` as the entry point
- ``daemon:runDaemonUAT``: Same as ``daemon:runDaemon``, but using the ``uat`` profile