Skip to main content

Installation

Requirements​

  • Docker: The provided container image is a docker image for Linux containers therefore you need Docker to be able to run it.
  • Docker Compose: While technically not required it helps you to get up the container(s) more easily.

Installation​

Information about sudo​

If you need to run docker with sudo right you have to prefix all following docker commands with sudo. Furthermore, keep in mind adding the -E flag to the sudo command if the docker or docker compose rely on environment variables so those get passed down, for example:

sudo -E docker compose up

Step-by-Step​

This Step-by-Step guide uses docker compose to set up the containers. You can find a sample docker-compose.yml file here. All steps marked with (optional) can safely be skipped.

If you want to use docker commands instead of docker compose you can find a list of those below aswell.

caution

If you are on a machine that requires manually starting the docker engine do so now.

  1. Download all configuration files as stated in the "Configuration" section of the latest release (or the release you want to use).

  2. Unzip the downloaded configuration files into a folder of your choice. The Step-by-Step guide assumes it is called config/. Those files contain a configuration file and some template files. For more information read the Configuration page on this documentation.

    tip

    All important adjustments you have to make are described here as well.

  3. Download the docker-compose.yml file from this documentation.

  4. Adjust the docker-compose.yml file:

    1. Replace <version> in the tms-server service with the version you want to use. You can also use latest as a tag but this makes updating the version harder in the future.

      Available versions

      You can find a list of the available versions here.

    2. Replace <path-to-CONFIG> with the relative path to the config/ folder (relative to the docker-compose.yml). Leave the destination side untouched!

    3. Replace <path-to-DB-FOLDER> with the relative path (relative to the docker-compose.yml) to the folder you want to store your database data in.

      caution

      Make sure the path you enter is writeable! If it is not (or you omit volume from the mysql container) the database data will NOT be persistent on the host and therefore might be lost if the container gets recreated!

    4. Add the nginx service as described in the Setup with nginx section of this documentation. Nginx (or a similar proxy) is the recommended way to set up HTTPS for the Tutor-Management-System.

      note

      Please note that the tms-server container does not need to expose the port to the public. The nginx container and the tms-server container just need to be in the same docker network (see below).

      Use existing nginx

      If you already have a running nginx or want to use a different proxy you can skip this step. However, it is highly recommended that you properly set up TSL/HTTPS for the TMS in either way.

  5. (optional) Adjust the production.yml configuration file. You can find more information about the individual entries on the Configuration page.

  6. (optional) Adjust the pug templates. You can find more information about the templates and their placeholders on the Configuration page.

  7. Start all services. This will create all containers of the services on the first start.

    1. Open a terminal and navigate to the folder containing the docker-compose.yml.

    2. Export the following environment variables in the terminal:

      Env-VariablePurpose
      TMS_DB_USERUsername used to authenticate on the MySQL database.
      TMS_DB_PASSWORDPassword used to authenticate on the MySQL database.
      TMS_SECRETSecret to use to encrypt and decrypt sensitive database entries. Keep it safe!
      caution

      They must be exported or else the docker compose child process will not have access to them.

    3. Run the following command to create and start all the containers:

      sudo -E docker compose up
      note

      Remember to put in the -E parameter so your environment variables get passed down to the process running docker compose.

    4. Check that the presented logs do NOT contain any errors and that all services start successfully.

    5. (optional) Stop all containers by quitting the process (Ctrl + C).

    6. (optional) Restart all containers with the following command (please note the additional -d). This time the terminal will not hook into the container logs.

      sudo -E docker compose up -d

  8. Login as administrator. The TMS creates the credentials for the administrator on the first start. The credentials are admin for the username and adminPass for the password (pay attention to the casing). You are prompted to change your password on the first login (see First Login).

    note

    You can also change the username of the administrator in the user management later if you want to.

Use docker​

  • Create a network for the MySQL database and the TMS containers:

    docker network create tms_db

  • (optional) Create a network for the nginx and the TMS container (if not already done in the "Setup with nginx" part):

    docker network create proxy_network

  • Create the MySQL container and start it:

    caution

    Remember to replace <path-to-DB-FOLDER> with the absolute path to the folder in which you want the database data to be stored in.

    docker run --name mysql:latest --restart always --net tms_db -e MYSQL_USER=$TMS_DB_USER -e MYSQL_PASSWORD=$TMS_DB_PASSWORD -v <path-to-DB-FOLDER>:/var/lib/mysql -d tms_sql

  • Create the TMS container and starting it:

    caution

    Remember to replace <path-to-CONFIG> with the absolute path to the folder containing the config files for the TMS and the <version> with the desired TMS version.

    tip

    If you do not want to use the proxy_network you can remove the --net proxy_network part. But keep in mind that the nginx container and the TMS container will not be in the same network afterwards.

    docker run --name tms-server --restart on-failure:1 --net tms_db --net proxy_network -e TMS_SQL_DB_USER=$TMS_DB_USER -e TMS_SQL_DB_PW=$TMS_DB_PASSWORD -e TMS_SECRET=$TMS_SECRET -v <path-to-CONFING>:/tms/server/config ghcr.io/dudrie/tutor-management-system:<version>

TLS / HTTPS​

The TMS server itself does NOT support TLS / HTTPS. The reason why TLS did not (and still does not) have a high priority is simple: Most servers already use a proxy (like nginx) which handle SSL for all services running on the server. Furthermore, using a proxy is the recommended way of using an express server according to the express documentation.

If your server does not already use a proxy you should consider adding one. For more information on how to set up TMS with nginx see the Setup with Nginx guide.

However, if you cannot (or do not want to) use a proxy on your server you can add the TLS support for the NestJS in a forked version of the repository following the NestJS HTTPS guide.