Installing onCourse on your server

Download onCourse Server. There is one application bundle which will work on OSX, Windows, Linux and Unix platforms. Unzip it to any suitable folder.

onCourse is happy in a virtualised environment such as VMWare, Xen, or AWS EC2. Ensure that you have sufficient RAM and CPU allocated. onCourse Server only writes to disk for log files, so memory and CPU are more important than disk performance. Allocate at least 400Mb of RAM, but at least 1Gb is better. onCourse will take all the memory you give it to cache data and run faster, up to a point.

onCourse.yml

The bundled onCourse.yml looks like this:

yaml

http:
    port: 443
    ip: 127.0.0.1
    path: /

db:
    uri: 'jdbc:mariadb://127.0.0.1/onCourse?user=onCourse&password=password123'

license:
    max_concurrent_users: 99
    custom_scripts: True
    access_control: True

smtp:
    email_batch: 100000
    host: smtp.gmail.com
    port: 465
    mode: tls
    username: [email protected]
    password: your_email_password

monitoring:
  user: monitoring
  password: password123

At a minimum, you’ll want to set the ip address to a reachable address on your server. Perhaps you’ll have onCourse behind a firewall or load balancer or exposed directly to the internet on a public IP address. That’s up to you. In order to run onCourse on a port lower than 1024 you will typically need to run it as root. Remember that onCourse includes functionality to write scripts which can then access the entire system as the user the server is running as, so where possible run onCourse as a non-privileged user or run it in a jail.

The database connection should be configured appropriately. The mariadb JDBC driver should work fine with mysql or AWS Aurora, but if you want to use Microsoft SQL server you’ll need to add the jtds library to your classpath.

The license section allows you to limit concurrent users and disable some functionality of the product. The smtp mode can be one of:

• tls
• starttls
• unsafe

Use 'unsafe' only if you are sure you want to send unencrypted mail across your network or the internet. That’s usually a bad thing. If you want to use gmail to send outbound mail, you’ll need to provide a valid username and password here, and also relax security settings here. Otherwise you can use your ISP’s mail server, your office server or an MTA like exim you install locally.

By setting a monitoring username and password you can monitor the server at the URL path /monitoring. A json response will be returned with the following fields:

JSON

{
    "time": {
        "current": 1649163079287,
        "timezone": "Australia/Sydney",
        "iso8601": "2022-04-05T12:51:19.287716Z",
        "uptime": 89189
    },
    "network": {
        "path": "/",
        "port": 8182,
        "ip": "127.0.0.1"
    },
    "environment": {
        "java.version": "11.0.14",
        "os.arch": "x86_64",
        "java.vm.specification.name": "Java Virtual Machine Specification",
        "java.vm.vendor": "Amazon.com Inc.",
        "os.version": "12.1",
        "java.vm.specification.vendor": "Oracle Corporation",
        "java.vm.info": "mixed mode",
        "java.vendor": "Amazon.com Inc.",
        "java.vm.version": "11.0.14+9-LTS",
        "os.name": "Mac OS X",
        "java.vm.specification.version": "11",
        "java.vm.name": "OpenJDK 64-Bit Server VM"
    },
    "license": {
        "access_control": true,
        "users.max": 99,
        "college_key": "1234",
        "users.current": 0,
        "custom_scripts": true
    },
    "systemRuntime": {
        "heap.used": 218615712,
        "cpu.usage": 0,
        "availableProcessors": 6,
        "heap.total": 447741952,
        "threads": 43
    },
    "onCourse": {
        "version": "120.1234"
    }
}

Invite new users

To create the first user or to reset passwords if you have lost them, create a file called createAdminUsers.txt and put it in the same folder as onCourse.yml. That file should contain one line per user in the format:

firstName lastName email

Put spaces between the fields. When you restart onCourse this file will be deleted and those users will be sent an invite link by email.

SSL Certificate

When onCourse first starts, it will create a self-signed SSL certificate in a file onCourseSSL.pem. This will ensure all traffic to onCourse is encrypted but if you want to remove browser warnings that you’ll get with a self-signed certificate you should replace onCourseSSL.pem with a certificate signed by a trusted authority.

Launching server

Run onCourse using either the bin/server.bat Windows script file or bin/server for all other platforms.

Once it is running, you should be able to connect with your browser. Make sure you use https, any special port you’ve chosen and your browser will need to support HTTP/2.

Memory allocation

Edit the value of DEFAULT_JVM_OPTS in the bin/server or bin/server.bat. The parameter -Xmx specifies the largest amount of heap memory allocated to the application. Java will allocate a bit more than this for compiling code and running the JVM itself. It is very important that you don’t allocate more memory than the machine actually has available or else everything will run incredibly slowly as the operating system swaps to disk.

More memory generally helps onCourse run faster.

Log files

onCourse will create a logSetup.xml file in the same directory as onCourse.yml when it starts up. This is a standard log4j2 configuration file and you have full access to all the configuration of how logs are output, rolled over and the logging levels.

By default logs are output to a folder called 'logs' in the same directory as the application.

Upgrading onCourse

Shut down the server and replace all the application files. It is important to completely delete the old lib folder and remove old files; don’t just keeping adding the new ones. Really the only file you need to keep between releases is onCourse.yml.