Skip to content

Installation

Jump to bottom
Dudrie edited this page Aug 25, 2020 · 19 revisions

Requirements

  • Docker: The provided image from the release section 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 (and docker-compose) with sudo right you have to prefix all following docker-compose and docker commands with sudo. Furthermore keep in mind to add 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.

However, if you want to use docker commands instead you can find a list of those below aswell.

⚠ 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 wiki.

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

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

  4. Adjust the docker-compose.yml file:

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

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

      ⚠ Make sure the path you enter is writeable! If it is not (or you omit volume from the mongo container) the database data will NOT be persistent on the host and therefore can be lost!

    3. Add the nginx service as described in the Setup with nginx section of this wiki. Nginx (or a similar proxy) is the recommand way to setup HTTPS for the Tutor-Management-System.

      💡 If you already have a running nginx or want to use a different proxy you can skip this step.

      ⚠ It is highly recommended that you properly setup TSL/HTTPS for the TMS in either way.

    4. (optional) Replace the latest version tag on the dudrie/tutor-management-system image with the version you want to us e if you want to use a different version than the latest one.

      💡 Changing the version tag makes future updates easier.

  5. 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:

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

      Env-Variable Purpose
      MONGO_USER Username used to authenticate on the MongoDB.
      MONGO_PASSWORD Password used to authenticate on the MongoDB.
      TMS_SECRET Secret to use to encrypt and decrypt sensitive database entries. Keep it safe!

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

      sudo docker-compose up

    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 docker-compose up -d

docker-compose

Here is the docker-compose.yml file used in the Step-by-Step guide: docker-compose.yml file

Commands

  • Create a network for the MongoDB and the TMS containers:

    docker network create tms_db

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

    docker network create proxy_network

  • Create the MongoDB container and starting it:

    ⚠ 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 mongo --restart always --net tms_db -e MONGO_INITDB_ROOT_USERNAME=$MONGO_USER -e MONGO_INITDB_ROOT_PASSWORD=$MONGO_PASSWORD -v <path-to-DB-FOLDER>:/data/db -d mongo

  • Create the TMS container and starting it:

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

    💡 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_MONGODB_USER=$MONGO_USER -e TMS_MONGODB_PW=$MONGO_PASSWORD -e TMS_SECRET=$TMS_SECRET -v <path-to-CONFING>:/tms/server/config dudrie/tutor-management-system

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 setup 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.

Clone this wiki locally