Getting Started with mDIS
On First Use
All topics mentioned on this page can all become relevant to any mDIS user, when first encountering the software. Most likely, the content on this page needs to be mentioned at least once, perhaps at the beginning of any prospective ICDP mDIS training course.
Contents are related to the "setup and configuration" Documentation written for administrators.
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 users's web-browser represents the mDIS Frontend, and the counterpart that sends web pages back to the users 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 webserver does not have to be hosted by ICDP, but often is, for convenience. The mDIS backend can also run on the Users' 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 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.
(Sorry, left and right sides are flipped in the figure below).
mDIS Usage and Administration
The most important way to access mDIS is via web browser in a graphical desktop. Besides, other access mechanisms exist. One of those mechanisms is the 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 indespensible.
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.
Password management
Password management (e.g. password reset, password reminder) by users themselves is currently not implemented and will be supported in a future release.
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 (opens new window). For technical details, see "For Administrators" and Installation with VirtualBox pages.
mDIS Supported Browsers
Browser support implied by user-interface components library VuetifyJS (opens new window):
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
- 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 time 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 a 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 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 Wifi which is usually faster than commercial telecom networks.
For administrators: changes of 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 quite a bit more powerful than that.
mDIS Server Components / Backend
For technical details, see figures above, and the "Sytem Administrators" Documentation.
Virtualbox Virtual Machines
In 2020 most mDIS installations were Virtualbox (opens new window)-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, that 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 cryptofilesystems, 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, high resolution. Small laptops are inconvenient to use for complex data entry tasks on large forms.
- For PC, 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 succeed.
On initial install, user must mave Administrator/Superuser rights on the host. On Windows the Windows Firewall (also called "Windows Defender Firewall") will perhaps complain; on Linux the VirtualBox installer will install 4 Kernel modules.
On Windows Hosts, the Microsoft Hypervisor (opens new window) Product called "Hyper-V" (or simply "Windows Virtualization" on Windows 11) must not be enabled. To disable Hyper-V (opens new window), 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 (opens new window) and VirtualBox on the same Windows machine at the same time (Running Docker on Windows requires Hyper-V to be enabled. Details unclear).
Network Pre-requisites
Client
- mDIS User needs to be familiar with Browser
- mDIS Operator, mDIS Admin need some basic familiarity with internet (Fileupload/Filesharing, 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 webapp where people need to log in first.
- mDIS User: - VirtualBox Based installation: Users need to be aware that mDIS server exists on a local network (accessible via some IP address from a private address range). If Users optionally get an WLAN-Name (=SSID) and password for Wifi, then user 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 login again into 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, shutdown 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.)