Installation

Required packages

Arch Linux

pacman -S npm nodejs
yay -S mongodb-bin mongodb-tools-bin

RaspberryPi 2/3 (tested with raspbian stretch)

Note: Since monodb is no longer available for armhf in newer versions (> 3.2) and the version (2.4) in raspbian is too old, an Ubuntu package (2.6) can be installed. It can be assumed that this Verion is no longer supplied with security updates ...

# Install Nodejs
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs autoconf libcurl3
sudo npm install -g gulp
# Install MongoDB
wget http://launchpadlibrarian.net/214171391/mongodb-server_2.6.10-0ubuntu1_armhf.deb
wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.0.0_1.0.1t-1+deb8u11_armhf.deb
sudo dpkg -i mongodb-server_2.6.10-0ubuntu1_armhf.deb
sudo dpkg -i libssl1.0.0_1.0.1t-1+deb8u11_armhf.deb
apt-get -f install

Debian

# Install MongoDB
wget -qO - https://www.mongodb.org/static/pgp/server-4.2.asc | apt-key add -
echo "deb http://repo.mongodb.org/apt/debian buster/mongodb-org/4.2 main" | tee /etc/apt/sources.list.d/mongodb-org-4.2.list
apt-get update
apt-get install -y mongodb-org
# Install Nodejs
curl -sL https://deb.nodesource.com/setup_12.x -o nodesource_setup.sh
bash nodesource_setup.sh
apt install nodejs
# Install Tools
apt-get install git autoconf libcurl4
sudo npm install -g gulp

Also check for an update for npm in order to fix latest security issues in the packages you will need to install later on.

Get sources of base application

git clone https://codeberg.org/lerntools/base.git

Get sources of additional modules

Important: Only clone required modules, skip other lines

cd base
mkdir modules
cd modules
git clone https://codeberg.org/lerntools/abcd.git
git clone https://codeberg.org/lerntools/about.git
git clone https://codeberg.org/lerntools/ideas.git
git clone https://codeberg.org/lerntools/projector.git
git clone https://codeberg.org/lerntools/survey.git
git clone https://codeberg.org/lerntools/tex.git

Install JS libraries

All dependencies can be installed using the package manager for nodejs:

cd .. # go back to base
npm install

On the RaspberryPi this step takes about half an hour, as some of the required packages are compiled first.

If npm displays audit security warnings, you shoulf fix them:

npm audit fix

Configure Server

1. Copy the file server.config.example.json to server.config.production.json (do not rename!)
2. Basic configuration by adjusting the values ​​in the server.config.production.json file, be sure to add a valid "SMTP_CONF" and "USER_ADMIN_MAIL" - otherwise you won't be able to change your password or administrate users!
3. Start the database: sudo systemctl start mongodb
4. Initialize the database : node bin/installDatabase.js

Important: Copy the initial admin password from the output - you won't get a chance to get this password later...

**********************************************************
Initial Password for user admin
EMXc8sOA5ycmote68jvNb
**********************************************************

Configure Client App

1. Copy the file app.config.example.js to app.config.js (do not rename!)
2. Remove unwanted modules from app.config.js (import statement and entry in allModules)
3. Basic configuration by adjusting the values ​​in the app.config.js file

Create upload and data directory

mkdir upload
mkdir data

Ensure, the user running nodejs is allowed to write files into that folder.

Create markdown files (optional – legal information)

1. Create direcory: mkdir -p main/text/en
2. Edit main/text/en/imprint.md for your contact information
3. Edit main/text/en/terms.md for terms of usage
4. Edit main/text/en/privacy.mc for information on privacy

Repeat theese steps for all supported languages by replacing "en" with "de" for example. The page title is generated from the level 1 headline:

# Imprint
## First headline
Text...

Create the assets

The application does not have to be "compiled", however it is necessary to bundle the so-called assets (graphics, stylesheets, libraries, etc.). By compressing and summarizing the load times can be significantly improved. Gulp's main task does this work (it runs in the lerntools home directory):

npm run build

After that the directory dist contains the necessary files.

First start

1. Starting the integrated webserver (port 8080) of nodejs:

npm start

2. Open http://localhost:8080 in your browser
3. Log in as admin (see output of bin/installDatabase.js for the initial credentials)
4. Add your correct e-mail address for password recovery
5. Import examples from the folder examples in the doc-folder

In order to administrate users you have to add a valid "SMTP_CONF" and "USER_ADMIN_MAIL" in server.config.production.json! You could also temporarily use the option "TAN_IGNORE": true, and enter "abcdef" as TAN. Be sure to change this setting back!

Tips

Deactivation of individual modules or functions

The application is modular, individual modules are located in the subfolder /modules/. In order to deactivate a module, you have to edit the file app.config.js:

1. Remove specific import line
2. Remove module from array allModules

Rerun npm run build-app afterwards.

Instructions mongodb

1. Delete a table (referred as "collection") under Mongodb, here for example the collection "users":

mongo
use lerntools
db.users.drop();

2. Delete the complete DB in Mongodb:

mongo
use lerntools
db.dropDatabase()

3. Delete specific user (example admin):

mongo
use lerntools
db.users.deleteOne({login:'admin'});

Setup Lerntools using Docker

For installing Docker on the system, please refer to the Docker installation guide.

The official Lerntools Docker image contains the basic server and all of the supported modules. It can be found on Docker Hub.

The two following setups are also starting the database as a container. In case your setup is different, please adapt your configuration accordingly.

Getting started (using docker compose)

This setup is solely meant to provide an easy start for testing, not for production.

1. Clone the repository to your local machine and open the directory

git clone https://codeberg.org/lerntools/base.git
cd base

2. Start the database and Lerntools

docker compose up

3. Lerntools is now accessable via port 8080 on your machine: http://localhost:8080

During the startup of the containers, there is the following section within the logs:

lerntools | Initial account and role created successfully
lerntools | **********************************************************
lerntools | Initial Password for user admin
lerntools | xxxxxxxxxxxxxxxxxxxx
lerntools | **********************************************************

This segment contains the initial password for the administrator account, which is created by default. You can login using those credentials (username: admin, password in this case: xxxxxxxxxxxxxxxxxxxx).

New user accounts can only be registered after configuring an e-mail server. See the environment variables.

Further configuration

In order to use Lerntools productively, additional configuration is required. This can be done in two ways:

1. Put the settings within the configuration file and mount it to /srv/base/server.config.production.json.
2. Use environmental variables. During the startup of the container, those variables will be used to create the configuration file automatically (see the code here). The variables available can be found on the bottom of this page.

In addition to the database, Lerntools also needs a persistent volume mounted to /srv/base/upload and /srv/base/data store e.g. uploaded pictures.

Finally, to enable Lerntools to send e-mails, the variables LERNTOOLS_MAIL, SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD and USER_ADMIN_MAIL need to be set. This is required e.g. for registering new users and sending TANs for admin actions.

A production-ready container setup could look like this:

docker network create lerntools

docker run -d \
 --restart unless-stopped \
 --network lerntools \
 --name lerntools_mongodb \
 -v ./data:/data \
 mongo

docker run -d \
 --restart unless-stopped \
 --network lerntools \
 --name lerntools \
 -p 8080:8080 \
 -v ./upload:/srv/base/upload \
 -v ./lt_data:/srv/base/data \
 -e PORT=8080 \
 -e MONGO_URL=mongodb://lerntools_mongodb:27017/lerntools \
 -e SECRET=INPUT-A-RANDOM-STRING-HERE \
 -e URL_PROTO=https:// \
 -e URL_HOST=lerntools.example.com \
 -e LERNTOOLS_MAIL=lerntools@example.com \
 -e SMTP_HOST=smtp.example.com \
 -e SMTP_PORT=465 \
 -e SMTP_USERNAME=lerntools@example.com \
 -e SMTP_PASSWORD=INPUT-YOUR-PASSWORD-HERE \
 -e USER_ADMIN_MAIL=admin@example.com \
 lerntools/lerntools

Using docker compose:

services:
 lerntools:
 image: lerntools/lerntools
 container_name: lerntools
 depends_on:
 - db
 restart: unless-stopped
 volumes:
 - "./upload:/srv/base/upload"
 - "./lt_data:/srv/base/data"
 environment:
 PORT: 8080
 MONGO_URL: "mongodb://db:27017/lerntools"
 SECRET: <INPUT A SECURE SECRET HERE>
 URL_PROTO: https://
 URL_HOST: lerntools.example.com
 LERNTOOLS_MAIL: lerntools@example.com
 SMTP_HOST: smtp.example.com
 SMTP_PORT: 465
 SMTP_USERNAME: lerntools@example.com
 SMTP_PASSWORD: INPUT-YOUR-PASSWORD-HERE
 USER_ADMIN_MAIL: admin@example.com
 ports:
 - "8080:8080"
 db:
 image: mongo
 container_name: lerntools_mongodb
 restart: unless-stopped
 volumes:
 - "./data:/data"

Please use a proxy server in order to access Lerntools via HTTPS. An example configuration for nginx and Apache2 can be found here.

Environment variables

Please note that the bolt variables are required in any case.

• Home

Technisches:

• Installation (en)
• Configuration (en)
• Production use (en)
• Updating (en)

Lerntools betreiben:

• FAQ Administration Frontend (de)
• Hosting Germany (de)
• Privacy (en)
• Legal notes concerning MongoDB (en)
• Referenzen (de)
• Probleme
• Vorlagen
• Anlegen eines Benutzers

Entwicklung/Development:

• Add languages (en)

Übersetzung/Translation:

• Call for translation help (de/en)
• Configure Weblate (en)
• Automatische Übersetzungen mit DeepL und Weblate (de)
• Translate (en)
• Hint for translating the help files