Getting Started with mDIS

Technical requirements

mDIS Client / Web Browser Frontend

mDIS is a web application.

Most likely, an end user encounters mDIS by opening a web page. The user's web browser represents the mDIS Frontend, and the counterpart that sends web pages back to the user is called the mDIS Backend. The most important program that runs inside the mDIS Backend is called a web server. See the following figure.

The figure above represents the Software-as-a-Service, or "SaaS" mode of operation mentioned in the "mDIS for newbies" page.
The web server does not have to be hosted by ICDP, but often is, for convenience. The mDIS backend can also run on the user's internal network, for example.

Technical View

For technical personnel who would like to have a more detailed view "under the hood," the mDIS implementation technologies are shown here:

This is further explained in the "sys-admin" page.

Offline Mode

It is possible to run mDIS without any internet connection. For this use case, there exists the VirtualBox mode of operation. That is a more advanced mode of operation when both the mDIS frontend and backend run on the same computer as a virtual machine.
Then, the implementation would look like this.

mDIS Usage and Administration

The most important way to access mDIS is via a web browser in a graphical desktop. Besides, other access mechanisms exist. One of those mechanisms is command-line access via a terminal. Both browser access and terminal access can use a REST API. Command line automation (specifically, via the yii PHP command line tool) is also possible and often indispensable.

Logging In and Out

To use even the most basic features of mDIS, you need to log in to the mDIS web page.

At this time, password management is done by administrators.

Installation and Configuration

For end users and data curators and editors, mDIS is a web application. This means mDIS runs in a modern web browser.

The mDIS software is available on laptops or PCs, where it runs as a VirtualBox virtual machine. The mDIS data-entry system is also available as a website; see list. For technical details, see "For Administrators" and Installation with VirtualBox pages.

mDIS Supported Browsers

Browser support is implied by the user-interface components library VuetifyJS:

• Chrome: Supported

• Firefox: Supported

• Edge: Supported

• Safari 10+: Supported

• IE11 or older / Safari 9: Not supported

• For data entry, we support the English language version of the browsers. Form labels, status/error messages, and other system output will be displayed in English only. Of course, data entry can occur in any language.

• Keyboard shortcuts specific to localized browsers are not supported.

• The display format of input fields for date/time values (i.e., "Core on Deck") depends on the language of the browser. However, for data entry with month names, e.g., "Dec 21 2019," English month abbreviations are assumed (German "Dez 21 2019" will not work).

• Mobile devices are generally supported: You should preferably use Google Chrome, Firefox, or a new version of Safari as a browser. On mobile devices, read-only access works reasonably well. Entering data on a small display like a smartphone can be quite awkward but should technically work.

Note on Browser Extensions and Operating System Settings

• The browser must be configured/permitted to open New Tabs (Dependent tables, e.g., Core -> Sections) and Popup Windows ("Exported Records") - otherwise, a warning appears: "Firefox prevented this site from opening up a popup window."
• Internet Access (for mDIS users entering data): Not Needed.
  (This question was asked quite a few times during our demo setup at EGU 2019.)
  Internet is still nice to have for accessing additional resources such as help files and external reference materials.
  For mDIS Admins and Developers, internet access is needed at least sometimes, e.g., for
  • updates of third-party code (OS, PHP, JS/Node)
  • uploading data gathered by mDIS to the ICDP website or external websites
  • setup of HTTPS connectivity.

Runtime performance

How to run mDIS smoothly?

The mDIS backend can run well on a small laptop with an Intel Celeron CPU manufactured in 2010, with just 2 GB of RAM. This is really sufficient for simple interactive data entry into forms. However, if you work with larger files, such as high-resolution core scans embedded in web pages and reports, mDIS will be much slower on such a small computer.

The mDIS frontend also runs on small systems such as phones just fine, but it can be a bit slow depending on wireless connectivity and available bandwidth.

Performance also depends on the network speed. Cable-bound LAN is faster than Wi-Fi, which is usually faster than commercial telecom networks.

For administrators: changes to the PHP code in the backend will be effective immediately. However, the development task npm run build (for rebuilding the mDIS frontend to achieve substantial changes in the input forms) takes about 10 minutes on such a machine, so if you plan to do development and customization, please use a machine that is quite a bit more powerful than that.

mDIS Server Components / Backend

For technical details, see figures above, and the "System Administrators" Documentation.

VirtualBox Virtual Machines

In 2020, most mDIS installations were VirtualBox-based. The mDIS server component was distributed as a VirtualBox Guest.
This mode of installation is one of many. It is not mandatory. mDIS can also be set up on its own server, natively, without VirtualBox.

However, if your mDIS instance is VirtualBox-based:

Regarding the Guest Operating System, we assume that mDIS admins only use properly configured releases of fairly common operating systems. That means:

• Fairly recent releases, which means

  • no Windows 7. After January 14, 2020, Microsoft will no longer provide security updates or support for PCs running Windows 7.
  • no ancient MacOS (TBC)
  • no "exotic" Linux distributions (with very small market share)

• Long-Term releases of the OSes (no beta releases, no rolling releases, self-built Linux distributions or kernels)

• "Fresh" standard installations (no older, crufty Linux releases previously upgraded to newer versions)

• Installations designed for use inside a small subnetwork (no enterprise features such as LDAP or Active Directory connectivity, security-optimized "hardened" Linux, no cryptographic filesystems, no type-1 hypervisors such as KVM). mDIS might work with these setups, but we have not tested them.

• at least 8 GB of free disk space inside the guest VM. Reserve 20 GB for the entire Virtual Machine.

• access to the Guest VM via SSH, via shared folders, via the graphical desktop.

Regarding the VM hosts and VM guests, the supported operating systems are shown in the figure below.

A green background means all versions should work, and we have tried them at least once, briefly. But we cannot test all combinations thoroughly. The best-supported combinations are shown with a checkmark.

Note: Apple iPads and newer MacBooks (with M1/M2 CPUs) are not supported. For details, see For SAs/Installation with VirtualBox.

Hardware Requirements

mDIS Client

Modern PC, Tablet, or Smartphone as implied by "Supported Browsers" above.

• Display size is important: must be large enough and high resolution. Small laptops are inconvenient to use for complex data entry tasks on large forms.
• For PC, a mouse is required:
  • data input forms need mouse events in places; e.g., some modal dialogs can only be closed by mouse events (or touch events).
  • the Template-manager GUI, which includes a Table Designer and a Form Designer, works with drag-and-drop only.

TBC

mDIS Server / mDIS VirtualBox host

• mDIS needs resources typical for a small instance server when no GUI is required.

• 2 GB of RAM should suffice.

• On initial install, the user must have Administrator/Superuser rights on the host. On Windows, the Windows Firewall (also called "Windows Defender Firewall") may complain; on Linux, the VirtualBox installer will install 4 Kernel modules.

• On Windows Hosts, the Microsoft Hypervisor product called "Hyper-V" (or simply "Windows Virtualization" on Windows 11) must not be enabled. To disable Hyper-V, go to "Control Panel"/"Programs and Features"/Left Sidebar/"Turn Windows Features On and Off." A long selection list of optional Windows Features will appear. Check off "Hyper-V" (or "Windows Virtualization"). Check the list for more entries containing "Virtualization." Turn them off as well. Reboot the Windows Host. Disabling Hyper-V probably means you cannot run the lightweight virtualization product Docker and VirtualBox on the same Windows machine at the same time (Running Docker on Windows requires Hyper-V to be enabled. Details unclear).

Network Prerequisites

Client

• mDIS User needs to be familiar with the browser.
• mDIS Operator, mDIS Admin need some basic familiarity with the internet (File upload/File sharing, Client-Server Systems) and relational database concepts (for tableset design).

Server

Information Technology skills required, by user group

• mDIS User: - mDIS installed on public internet: User interaction with mDIS should be similar to any web app where people need to log in first.
• mDIS User: - VirtualBox Based installation: Users need to be aware that the mDIS server exists on a local network (accessible via some IP address from a private address range). If users optionally get a WLAN name (=SSID) and password for Wi-Fi, then users need to know how to interact with a WLAN config app. They need to grasp that they need to enter the mDIS homepage URL (something with "localhost") directly into their browser and log in again to mDIS. They need to know that the address entered is in most cases not reachable from the public internet. Instead, it is a "private address," "local address," or an "intranet address," whatever term is more familiar to the user.
• mDIS Operator, mDIS Admin: familiar with IPv4, Level 2 internet (Ethernet, WLAN, client/server architecture concepts), basic OS knowledge, familiar with LAMP/MAMP administration (that can be a lot of stuff!). For a permanent mDIS server installation, I expect from the administrator even more, like backup strategies, IT security measures, and good operating procedures in place like server monitoring, etc. For an mDIS installation on a project laptop, I expect the admin to be able to handle the VirtualBox software: create or restore snapshots, export OVA files, shut down and start a VM, etc., but nothing more.
• mDIS Developers: need to know an absurdly rich set of technologies for both client and server. (That's why they are developers.)