# timOhjeet

Installing TIM

The Interactive Material (TIM) consists of the TIM source code and the services that run the code. The services and all runtime dependencies are packaged as Docker containers to facilitate installation. The installation of TIM consists of three steps: installing the dependencies, downloading the source code and running TIM.

This guide applies to both TIM system integrators and TIM developers. Developer-specific instructions are separated by the text "for Developers".

1. System requirements

The requirements to run TIM depend on the expected number of concurrent online users. The specifications below are estimates based on the tests with the official instance of University of Jyväskylä (JYU-TIM):

Hardware

  • Disk: SSD, min. 25 GB, of which 18 GB must be on the primary disk
  • RAM: min. 8 GB + 4 GB for every 100 concurrent online users
    • Developers: recommended min. 16 GB to run all development-time programs
  • CPU: x86_64 (i.e. Intel x86-compatible 64-bit processor or its emulator); 1 core for every 100 concurrent online users
    • Developers: in development mode, TIM is always run in a single process, but a multi-core processor is recommended for development programs

Operating system TIM can be used on any system that supports Docker. System-specific requirements:

  • Linux: any distribution running Linux kernel 3.10 or later
    • You can check your distribution's kernel version by running uname -r
    • Linux is the preferred system on which the production instance should run
  • Windows: Windows 10 21H1 (build 19041) or later, Windows 11 21H2 or later
    • Windows installation requires that the hardware supports Hyper-V virtualization. You can check this by running the systeminfo command on Windows and looking at the Hyper-V Requirements entry that announces it.
  • macOS: macOS 10.15 (Catalina) or later
    • Devices with Apple silicon processor need the Rosetta 2 app (macOS should install it automatically).

2. Install approach 1: using the quick installation script

If

  • you install TIM on a Linux machine (Ubuntu, RHEL 8+, CentOS 8+, Arch), and
  • you install TIM for production use (i.e. NOT for developers)

you can use the quick install script by running:

curl -sL https://get.tim.education/linux.sh | bash -s - --profile prod

The script will automatically install all dependencies for a production run to /opt/tim and will start a minimal TIM installation. After installation, you should customize tim.conf to your needs.

2.1 Automatic installation of the development environment (experimental!)

3. Approach 2: Installing TIM and dependencies manually

TIM needs the following software installed:

  • Docker Engine and Docker Compose
    • Developers: you can install instead Docker Desktop, which includes all necessary Docker dependencies
  • Python 3.6 or later (developers: install the latest version, currently 3.10)
    • Windows: in the installer, select Add Python to environment variables
  • Git 1.8 or later
  • Developers: Node.JS (any LTS version) and NPM 6.x
    • Note: NPM version can be different from 6.x by default. See additional instructions below.
  • Any shell interpreter; below is a list of tested and proven interpreter:
    • Linux POSIX-compatible shell interpreters: bash, zsh, fish, sh, ...
    • macOS built-in shell
    • Git Bash (Windows)
    • MINGW and MSyS shell interpreters (Windows)
    • WSL2 Bash (Windows) WSL2 Bash (Windows)

Other software will be installed automatically when you install TIM. You can view the explanations of all the programs used in TIM in the service documentation.

The dependency-specific instructions below explain how to install the different programs and how to configure.

3.1 Developers: Docker Desktop

Docker Desktop comes with all the dependencies for deploying Docker in development.

3.1.1 Linux

Official installation instructions

  • First check if Docker can be found in the distribution's own package manager
  • Instead of Docker Desktop, you can install Docker + Docker Compose separately. Most distributions provide separately the docker package and the docker-compose package
  • If you cannot find docker-composeas a package in your distribution, you can proceed as follows:
    • Run docker compose version. If you get a version (e.g. Docker Compose version v2.x.x), you already have Docker Compose installed
    • Otherwise, you can install the script manually: Install Compose manually (search on Compose standalone, which is the easiest way to install compose)

3.1.2 Windows

Download the installer from

Official installation instructions

  • In the installer, make sure that the Use WSL 2 instead of Hyper-V checkbox is selected
  • The Docker Desktop installer should automatically configure your computer to work with virtualization. If this does not happen, you can do this manually: Docker official instructions
  • Docker Desktop installer also installs Windows Subsystem for Linux 2 (WSL2) automatically. If this fails for some reason, you can manually install WSL2 using Microsoft's instructions
  • Docker Desktop may ask you to reboot the system a few times and install additional dependencies (e.g. WSL2 Linux kernel). Follow the instructions of the Docker Desktop installer

3.2 Developers: NodeJS

  • On Linux, LTS (long-term support) versions of Node.JS are often available directly from the package manager

  • The TIM system is currently using NPM 6.x in development due to various legal and performance issues with newer versions. First check your NPM version by running

    npm --version

    if the output is anything other than version 6, the version must be downgraded with the command

    npm install --global npm@6

    Finally, check that the version is set correctly.

    • Note that TIM needs NPM version 6! If you need a different NPM version for your own development, you can use NVM for Windows or nvm.sh

Lisähuomio

Jos TIMia käynnistäessä/asentaessa bdw-skripti kaatuu virheeseen, katso tarkemmat ohjeet täältä.

4. Downloading TIM source

After installing the dependencies, the source code of TIM can be downloaded. Download TIM from GitHub:

  1. Developers: Create SSH keys and install them on GitHub.

  2. Go to the directory where TIM will be installed

  3. Run the shell

    If you have push access to the TIM repo(developers):

    git clone git@github.com:TIM-JYU/TIM.git tim

    If you do not have push permission:

    git clone https://github.com/TIM-JYU/TIM.git tim

5. Configuring and running

TIM is configured using the TIM Command Line Interface (TIM CLI).

  1. Open the shell interpreter and go to the downloaded TIM instance folder

  2. Run ./tim setup

  3. Follow the configuration program instructions

    1. Select a run profile. There are two main options:
      • prod: configure the TIM instance for "production use"
      • dev: configure the TIM instance for development use(for developers)
    2. With prod profile, the tool asks you to enter additional settings, such as the address of the TIM instance and the ports used by the instance

  4. Follow the installation progress: TIM loads the Docker images, compiles the browser code and runs all services up If any step fails, you can later re-run the configuration using the command ./tim setup --force

The TIM system is then up and running. Test that you can access the TIM home page:

  • In prod profile, the address is the configured address
  • (developers) In dev profile, the address is http://localhost
    • If everything works, you will see the message "TIM Caddy is running!"

5.1 Creating a new user

TIM already has three test users named testuser1, testuser2 and testuser3 (see maintenance guide) but no maintenance user.

Create a new maintenance domain with the command

./tim run flask user create

6. Most common maintenance commands

Maintenance of the TIM instance is primarily done with the TIM CLI tool (./tim script in the TIM directory).

The most common commands for basic use:

  • ./tim up: restarts all containers, restarting them if necessary (e.g. due to a configuration change)
  • ./tim restart: restarts all containers
  • ./tim update all: performs a full TIM system update (downloads containers, compiles JavaScript)
    • Note: This does not update the source code itself. You can do this e.g. at git pull or similar.

Less common, but still useful commands

  • ./tim js: recompile JavaScript code
  • ./tim dc down: shut down the TIM system
  • ./tim run flask: maintenance commands for TIM babble. Includes commands to create and manage (admin) users, for example.

For more commands, visit ./tim --help and the maintenance instructions at

7. Next

These are the current permissions for this document; please modify if needed. You can always modify these permissions from the manage page.