mSupply client / server installation

  • mSupply Server can be installed on a range of Windows OS hardware platforms. Installations of the mSupply Server and client software on these different platforms will not be identical.
  • This page includes instructions for installing the mSupply Server and client software on a typical Windows 10 Pro platform. This will include many hardware configuration issues as these have been known to be important for mSupply Server operation and troubleshooting.

Recommend Hardware

The following table lists minimum recommended hardware for an mSupply server

Item Recommendation
OS Windows 2008 / 2011 / 2012 / 2016 or Win 7 / 8 / 10 Pro with latest service packs
Processor Dual core Xeon or equivalent. For greater than 15 users: Quad core Xeon
Memory ECC memory Minimum 4Gb +1Gb per user over 8 users
Hard disks 3 Hard drives to run RAID 1 (or 5) Array + Hot Spare. 1 separate Hard disk for primary back up
Network card Gigabit
RAID controller RAID 1: Onboard RAID controller is fine
Power supply Dual hot-swap power supply is best, single power supply acceptable with good power quality

Indicative pricing before local taxes: USD3,000 to USD5,000.

For a Terminal server, the general specification changes in that

  • More RAM is needed.
  • Hard disks are less important, as no data is stored on the server (unless you are using the same server for both hosting the mSupply server and hosting the terminal sessions).
  • An additional Gigabit Ethernet port could be useful

Pricing should be similar.

Beware of Solid State Drives (SSDs)!

At least one country which had several servers with SSDs installed has had the bitter experience of the SSDs failing after ungraceful shutdowns due to failing UPSes.

The vast majority of ICT documentation on the internet is written from and for locations enjoying relatively stable power supplies. There is precious little information available for facilities suffering from the sort of chronic power supply issues which the majority of mSupply users experience. We have found only one apparently relevant reference: The mysteriously disappearing drive: Are power outages killing your SSDs?. Even though you have the server protected by a UPS, the batteries will fail sooner or later, and our experience supports the findings in the above article.

Based on this, our strong recommendation is:

Avoid the use of SSDs in servers.

To achieve performance gains, invest instead in more RAM.

Installation pre-checks

UPS (Interruptible power supply)

  • Unless you have extremely reliable power we strongly suggest you install a UPS with external batteries that will provide several hours run time, e.g.:
  • The UPS must be able to communicate with the server (usually with a USB cable) to initiate a graceful shutdown in advance of UPS shutdown.
  • For the UPS to protect the server from power surges / spikes, the UPS needs to be connected to a power socket that is properly earthed.

More details on configuration of the UPS is contained below.

ICT capacity

Do you have sufficient in-house ICT capacity to do the rest of the server installation yourself?

  • This server hardware belongs to you (or maybe not… see tip below).
  • Sustainable Solutions is a software development company and our core business is not hardware

However, we know that if the server is not installed and configured correctly, the mSupply software and your medical supplies data is vulnerable. Therefore, in most instances, we end up playing a significant role in installing and configuring the mSupply Server.

Over recent years, with the development of reliable and relatively low-cost cloud based server solutions, more and more mSupply client / server installations have used a cloud based server. In many cases, Sustainable Solutions has provided this cloud based server as a separate service, thus relieving you of any responsibility for installation, configuration and management of the mSupply Server hardware.

Initial server hardware setup

Set up the physical hardware including

  • RAID 1 volume with Spare (3 disks total)
  • Separate backups volume
  • OS install with correct region, and keyboard
  • Administrator account called Sussol (mSupply server will operate from this account.

Miscellaneous Server Tweaks

There are a number of miscellaneous server tweaks that we recommend:

Remove Windows / OEM bloatware

  • Remove all icons pinned to the Start bar except File Explorer
  • Remove / uninstall all tiles on the Windows start area

Hibernation / sleep

  • The pc can go to sleep after a few hours so change the power settings to never sleep etc. Even after setting the sleep setting to never you still must go into the advanced settings and change the hibernate setting to never: How to turn off Hibernation on Windows 10

Turn off Cortana

Cortana is unhelpful on mSupply servers. It is worth disabling - refer https://www.windowscentral.com/how-turn-cortana-and-stop-personal-data-gathering-windows-10

Automatic Updates

Turn on Windows Update Delivery Optimization

While it is good to control when Windows updates take place, it is often beneficial to use Windows Update Delivery Optimization to minimise bandwidth for Windows Updates. It is recommended to turn on Windows Update Delivery Optimization for the server.

Turn off DEP (data execution protection)

DEP can interfere with 4D - refer 4D Knowledgebase: Tech Tip: Windows Server 2008 also uses DEP, so, we may need to adjust it - refer https://www.online-tech-tips.com/windows-xp/disable-turn-off-dep-windows/

  • Initially, try things with the default setting (Turn on DEP for for essential Windows programs and services only)
  • Then, if 4D / mSupply has issues, try Turning off DEP for all programs and services:
    • Open command prompt (as administrator)
    • Run the following: bcdedit.exe /set {current} nx AlwaysOff

Correct Keyboard

Even if you chose the correct keyboard (normally US) during setup, another keyboard (like the UK keyboard) can sometimes still be the default keyboard. Check this by trying to type the @ character… To fix this, you will need to:

  • Go to SettingsTime & LanguageRegion & LanguageLanguage
  • Add the correct language (e.g. English (Australia)). This will auto select US keyboard
  • Move it up to the default position and delete the other language option(s).

Remote connectivity efficiency - Best performance

Remote access speed gain by disabling visual effects.

  • Go to SystemAdvanced System settingsPerformance and choose Adjust for best performance.

Remote connectivity efficiency - Remove background picture

Remote access speed gain by removing the background picture on the Windows 10 sign-in screen.

  • Go to Settings (keyboard shortcut: Windows + I) > Personalization > Lock screen.
  • Scroll down and turn off the option, Show Windows background picture on the sign-in screen.

Improve Windows Explorer file visibility

To carry out some of the server configuration tasks, file visibility in the Windows OS needs to be improved from the default.

Follow these instructions to View hidden files and folders in Windows 10

While doing this, make the following changes:

  • Always show menus
  • Display the full path in the title bar
  • Show hidden files, folders and drives
  • Don't hide empty drives
  • Don't hide extensions for known file types
  • Don't hide protected operating system files (Recommended)
  • Use check boxes to select items

Install associated server application software

Install Dropbox

Sustainable Solutions recommends using Dropbox to assist with transferring installation files to the server, and as a means of moving mSupply secondary backups off site.

  • Contact Sustainable Solutions to organise a DropBox account for the server and for instructions on setting it up on the server.

Do this step first so that you can use the Dropbox folder to transfer software and files to the server.

Install Remote Support software

Sustainable Solutions uses software to provide remote support. We have used a few packages over the years. At the time of writing this (May 2018), we are using TeamViewer.

  • Contact Sustainable Solutions to organise setting up TeamViewer on the server.

If possible, please change the computer name to something recognisable, e.g. Nonga GH Server.

Install UPS hardware and software

If its not already done, install the UPS hardware and software, refer UPS above.

Install Anti-virus software

Anti-virus can be a hotly contended issue. This web page is pretty convincing: What’s the Best Antivirus for Windows 10? (Is Windows Defender Good Enough?)

Conclusion:

  • If the OS is Win8 or later, Windows Defender is probably good enough for anti-virus, and better than much of the competition.
  • Once configured, the server should not be vulnerable to exploit programs as these are usually downloaded and triggered by human activity! However, to be safe, it is recommended to install an Anti-exploit program such as Malwarebytes. The website suggests that Malwarebytes is not free, but as at the time of writing this (May 2018), Malwarebytes successfully reverts to a free version after the 14 days trial. This means that it has to be manually run.

Install another Web browser

If you're not a fan of Microsoft Internet Explorer, (12 reasons not to use Internet Explorer, ever) then install another browser. Good options include:

Pin the browser to the Taskbar.

Install LibreOffice

mSupply can produce reports in Microsoft Excel format. Client machines will need to have software to open these reports. Occasionally there will be need to run and open these reports while logged in to the Server. If you do not have Microsoft Excel installed on the server, a good option is:

It's a good idea to stick this in to the Dropbox

Install TurnedOnTimesView

As part of troubleshooting, it is valuable to be able to analyse when the server has shut down ungracefully.

  • TurnedOnTimesView is a simple tool that analyses the event log of Windows operating system, and detects the time ranges that your computer was turned on and whether the last shutdown was graceful or not.
  • Installation instructions are on the website, but is very straightforward:
    • Copy the TurnedOnTimesView.exe file to the Desktop
    • Pin it to the Taskbar.

TurnedOnTimesView.zip

It's a good idea to stick this in to the following folder in Dropbox:

  • TurnedOnTimesView

Install Logoff and Lock utilities

It is too easy for support workers accessing the server remotely to accidentally shutdown the server. Therefore, two Windows shortcuts have been created to allow support workers to easily logoff or lock their windows session without having to go through the usual Windows procedure:

  • Lock computer
  • Logoff computer

Lock / Logout utilities

It's a good idea to stick this in to the following folder in Dropbox:

  • Lock Logout Shortcuts

The Yellow Lock computer utility needs to be copied to the Admin desktop and then pinned to the task bar.

The Green Logoff computer utility needs to be copied to the C:\Users\Public\Desktop folder. This will place the shortcut on the desktop of each normal user. Users of each normal user account will need to pin this shortcut from the desktop to the taskbar. Don't pin it to the taskbar of the Admin user account. We try to keep the Admin account open so as to keep Dropbox working.

The C:\Users\Public\Desktop folder is normally a hidden folder. You will likely need to make it visible).

If you are upgrading from a previous version...

If you are upgrading from a previous version of mSupply, first perform a data backup:

  • With mSupply server open as an application click on File> Backup…. This will generate a backup file of your current data with file extension .4bk.
  • Copy this file to at least one safe place, e.g. USB drive, a cloud service such as Dropbox.
  • Continue only when the .4bk file has completed transfer to the remote location.

Moving from pre v3.50?

There was a major upgrade of mSupply's internal structure in v3.50. If you are upgrading from a pre v3.50 installation of mSupply, Sustainable Solutions will need to convert your data so that it can be read by mSupply versions after v3.50. This conversion process is provided free of charge.

Installing mSupply server

The client/server version of mSupply has two installers:

  • One installer, with the word server in the title, is used to install the mSupply Server software on a single server computer.
  • The other installer, with the word client in the title, is used to install the mSupply Client software on as many computers as you wish including on the server computer. You will be limited in how many clients can connect at any one time by the server licence you have purchased.

Obtain and run the mSupply Server installer

You must be logged on as Administrator to install mSupply Server with the correct permissions. Please consult your IT support staff if you require assistance to achieve this.

Once you have obtained the mSupply Server installer file, double click it to install. Here is what the mSupply server installation window should look like:

  • You may be asked by the OS whether 'you want to allow this app to make changes to your device?'. Click Yes
  • At the mSupply Server Setup Welcome screen, click Next
  • To proceed with the installation, you will need to click on the 'I agree to the terms of this license agreement' radio button and click Next
  • Unless you have good reason to do otherwise, don't change the installation folder, and click Next
  • Unless you have good reason to do otherwise, don't change the Shortcut folder, and click Next
  • At the Ready to Install window, click Next
  • After some time (minutes!) you will be shown the Installation Successful window. Click Finish

What is installed where:

We strongly recommend you do not change the default installation directories, which are as follows:

  • mSupply Server: C:\Program files\mSupply\mSupply Server
  • mSupply Client (see Installing mSupply Client below): C:\mSupply Client
mSupply Server installer also installs the following files and folders:

Starting the Server for the first time

There is no point in carrying out the following steps unless:

  • You have the the license registration file
  • You are ready to create a new mSupply data file, or you have one to load.

Registering the 4D License

  • mSupply is built on the 4D database engine. 4D Licenses are required for the Client - Server operation.
  • You will need the license registration file(s) sent to you by Sustainable Solutions and paste them to the following folder:
    • C:\ProgramData\4D\Licenses
  • Alternatively, if Sustainable Solutions staff have remote access to your server, they can apply the license.

Run mSupply Server

We need to run mSupply Server as an application until all configuration is completed. Don't run as a Service now as some configuration functionality is not enabled when run as Service.

We need to run the mSupply Server software as Administrator.

There should be a shortcut on the Desktop called mSupply Server.

Right-click on the icon and select Run as administrator

You will then be presented with the following dialogue box:

Click Create to create a new data file or Open to choose an existing data file. The below image shows an existing data file.

  • You can create the data file anywhere you like, as long as you have read/write access to the directory.
  • To assist with provision of support we recommend that you create a place the data file in a folder called mSupply data inside your Documents folder (My Documents before Windows Vista!).

You may get a question from the Windows Firewall requesting permission for mSupply to communicate through the Firewall.

Allow mSupply to communicate on both private and public networks.

If the above steps have succeeded, you should see the 4D Server Administration window:

Configure Backups

  • Select Maintenance and then, under the 'band' titled Last backup select Preferences.
    • Scheduler: Set Automatic Backup: to Every day, at 20:00 or later, as long as it is a time when work is likely to be finished. It will have to be set earlier, say 16:00 if the server is switched off of an evening.
    • Configuration:
      • Content:
        • tick Data File
        • untick Structure File
        • untick User Structure File
  • Backup File Destination Folder
    • If on physical hardware, this should be a separate physical disk (e.g. D:\mSupply_backups).
    • If on a virtual machine, it is meaningless to have a separate physical disk, and it should be C:\Users\Administrator\Documents\mSupply backups.
  • Log Management: Set .journal to the same parent folder as the backups.
    • If on physical hardware, this should be a separate physical disk (e.g. D:\mSupply_journal).
    • If on a virtual machine, it is meaningless to have a separate physical disk, and it should be C:\Users\Administrator\Documents\mSupply journal. *

If a location of the log file is already specified, and you want to change it, you need to untick the “Use Log” tick-box and then when you re-tick it you will be prompted for a new location.

  • Backup & Restore
    • General settings
      • tick Keep only last 60 backup files. Of course if the drive you are backing up to doesn't look like it will have 60x the space one backup file will need then lower the number appropriately.
      • tick Backup only if the data file has been modified
      • Delete oldest backup file after backup
      • If backup fails: select Retry after 60 Seconds
      • tick Cancel the operation after 3 attempts.
    • Archive
      • Segment Size (Mb): None
      • Compression Rate: Compact
      • Interlacing Rate: None
      • Redundancy Rate: None
  • Automatic Restore
    • tick Restore last backup if database is damaged
    • tick Integrate last log if database is incomplete
  • Click OK

You will see the following dialogue box:

  • Click OK to create the first backup.

Configure Cache

Confirm Cache settings (there will likely be no changes):

  • Select Maintenance > Last backup: > Preferences > Database > Memory:
    • Tick Calculation of adaptive cache. Settings here are set by 4D on the basis of the system memory.
    • Un-tick Keep the cache in physical memory for 4D Server and 4D Volume Desktop
      • Flush Data Buffers every: 10 Minutes

Exit 4D Server Administration window.

Enter Extra 4D serial numbers

When you registered 4D server the licence allowed 2 concurrent connections. If you have purchased extra connections, you should enter the serial number(s) now.

Choose Help > Update licence. This window is shown:

Click the Add button to enter additional licences.

Setting the server to run as a service

The server should now be set to start automatically when the machine is turned on. This can be accomplished by setting the server to run as a service. Choose File > Register Current Database as Service.

If the Register Current Database as Service option is greyed out, you need to quit the server and run as administrator.

Quit the 4D Server Administration window by clicking the close box on the top right (or choose File > Quit from the menus). You will then be shown a disconnect window something like this:

Type 0 into the box, and click OK . The server will quit.

Pin Services to the taskbar

It is important to be able to quickly observe the status of the 4D / mSupply Service. Therefore, we pin Services to the taskbar:

  • Click Windows icon
  • Type Services
  • Right-click the Services Desktop App
  • Select Pin to taskbar

Configure mSupply Service settings

Click on Services in the task bar. You will be shown a window like this.

Double-click on 4DServer: mSupply - fortunately it is usually the first item in the list!

You will be shown the 4D service properties window. Change the Startup type in the drop-down list to automatic (Delayed start) .

On the Log On tab, the settings should be shown below:

  • Make sure “Log on as” is set to “local system account”
  • Make sure “Allow service to interact with desktop” is checked.
  • Click OK to return to the list of services.
  • You can now start the service by clicking the little play button (right facing triangle) on the toolbar with the 4D service highlighted.
  • Scroll down the list of services until you see Interactive Services Detection.

  • Double click this and then change “Manual” to “Automatic”.
  • Then click on the Log on tab and tick the box, “Allow service to interact with desktop”
  • Click OK at the bottom of the window
  • Click the Start Service button (see the button in the red box above). At this point the status should start reporting either “started” or “running”.
  • Click the red X to close the Services window.

If clicking the Start Service button results in the Error 1: Incorrect Function, a registry edit (regedit) is necessary. Please only do this if you are confident and familiar with editing the registry. mSupply Support can help with this. Edit registry value:

  Hive: HKEY_LOCAL_MACHINE
  Path: SYSTEM\CurrentControlSet\Control\Windows
  DWORD: NoInteractiveServices

Change value 1 to 0

Once finished editing the registry, close regedit and return to the list of services and start the ISD service. It should now start!

From now on the 4D server will start automatically when the machine is turned on. There is no need to log-on to the machine.

Should you need to manually stop and start the server in future:

  • To start, double-click the “Services” shortcut you made on the desktop, highlight the 4D server service, and click the “start” button (looks like a “Play” button on a VCR )
  • To stop the server, make sure clients are not connected, then choose File > Quit on the server.

Delete mSupply Server shortcut

Now that mSupply server is running as a service, we want to make it difficult to accidentally run the mSupply application manually. We recommend that you delete the mSupply Server shortcut.

Manually starting the Service

Despite being configured so, the mSupply Service sometimes will not start when the server hardware starts. The service can be started through the Services:

Creating a new data file or choosing a different data file

From this point there should be no need to revisit any of the above procedures to operate mSupply. However, if you are testing, or starting a data file for a second organisation, you may wish either to change the data file mSupply is using or to create a new file.

The mSupply program (the files named “mSupply.4DC” and “mSupply.RSR”) store the path to the last data file used, and the next time mSupply is started, the previous data file that was open is opened again unless there is user intervention or the “old” data file has been moved to a new location.

To intervene, hold down the “alt” key as the 4D server starts up.

You will be shown the standard open/save window:

To create a new data file, click the “New” button.

To select an existing data file, navigate to the file's location then click the “Open” button.

Installing mSupply Client

Needed: mSupply Client software of the same version (or relatively recent) as the mSupply Server.

  • The mSupply server should run as a service on the server computer - see above. If any user needs to use mSupply on the server (not recommended, but possible, and sometimes necessary) then they should not be running the mSupply Server software. They should run the mSupply Client software, which should be made available to all user accounts.

OS date settings

Generally, mSupply will interact correctly with the local OS in terms of date format. However, as OS versions continue to evolve and handle dates differently, sometimes this does not work. We have found that very occasionally, if the OS date format is set to DD-MMM-YY (e.g. 20 APR 2020) then mSupply will not always handle the date well. It is recommended to set the system date to DD-MM-YY.

Obtain and run mSupply Client installer

You must be logged on as Administrator to install mSupply Client with the correct permissions. Please consult your IT support staff if you require assistance to achieve this.

  • Once you have obtained the mSupply Client installer file, double click it to install.

The mSupply client will be installed in the folder C:\mSupply\mSupply client on your computer.

mSupply client installer also installs the following files and folders:

  • A shortcut on the Desktop called mSupply client.
  • A folder called “\4D\Network” in the Windows folder on the startup volume, which contains network component files that need to be present for 4D to communicate over a TCP (and other types of) network(s).
  • Note that no reports are installed on 4D client. Each time 4D client connects to the Server, reports that have been added or modified on the server are automatically copied to the client.
  • Note that the installers have been set up to overwrite existing files, so reinstalling the software will restore any potentially corrupted files to their original state. The installer will not overwrite your data files, unless you have been unwise enough to name your data file “example data” and put it in the “example data” folder;-).

For convenience, pin the mSupply client desktop shortcut to the taskbar.

If any other Windows users will use this computer to access mSupply, it is worth copying the mSupply client desktop shortcut to the C:\Users\Public\Desktop folder. This will place the shortcut on the desktop of each user. Each user will need to pin this shortcut from their desktop to the taskbar.

The C:\Users\Public\Desktop folder is normally a hidden folder. You will likely need to make it visible).

Starting the mSupply Client

Once the installation is completed, double-click the “start mSupply Client” shortcut on your desktop. A window something like this should appear:

The window lists available mSupply servers on your network (there should be only one!) Click on the server you wish to connect to.

  • Once you have connected successfully, the mSupply Client 'remembers' which Server you last connected to and stores this in the Recent tab. Whenever you run the mSupply Client, it will automatically connect to that server.
  • If, mSupply Client cannot connect to the mSupply Server, this window will pop up showing the Recent tab. You can try choosing the server there.
  • If, for some reason, network settings have been changed and you cannot connect from the Recent tab, remember to look at the TCP/IP tab as well.

Clicking the “OK” button will take you to the mSupply password entry window. For new data files, the password is user1 for the first user in the list. Click on the first user, then enter the password and click OK

mSupply Client software can not see the mSupply Server?

Server is not visible?

  • To make it easy for you to connect, mSupply Server publishes details about available servers on a specific port. It is quite possible that products such as “Zone Alarm” and “Norton Personal Firewall” will block access to this port and stop discovery of the servers. Contact your system administrator if the list of available servers is blank.
  • Of course, it may be possible that the mSupply Server service is not running. Check Services to establish that.
  • Lastly, the Windows firewall may be blocking the Server publishing it's presence - see below.

Configuring Windows firewall on server

The Windows firewall may need to be adjusted to allow the Client to receive Server identification.

From the 4D tech email list:

  • When you launch 4D client, it broadcasts a udp message on the subnet, requesting all 4D servers to identify themselves.
  • The UDP message is sent from a random port to a destination port = 19813 (default)
  • When responding, each 4D server replies with a UDP unicast message from its address to the client's address with source port = 19813 and destination port = whatever port the client had used to broadcast.
  • So in order to let the client receive the answer back from the server, one has to punch a hole in the firewall for all UDP packets with a source port of 19813.

mSupply Server Configuration

Register mSupply

The procedure is described earlier in “Preferences” chapter of the mSupply manual. See The Register button

You will either have to phone or email the information to Sustainable Solutions to obtain a registration code.

The registration code is keyed to your Organisation name and the MAC address of the server. Changing either of these will require a new code, which we shall willingly provide. So, take care when setting the Organisation Name!

Configure mSupply Preferences

Once registered, you may want to systematically to go through the mSupply Preferences and choose appropriate settings, and particularly setting up the Secondary backups! Start here: Preferences > General

Your installation of mSupply may have customisations made specifically for your work scenario. Please contact our support staff on support@msupply.org.nz to manage these customisations.

Configure label printer

If you are dispensing, you will need to set up label printer preferences

Upgrading to a newer version of mSupply

User Access Control, a feature of Windows 7, requires that the undernoted steps are followed when you are upgrading mSupply

  1. In Windows 7 click Start Menu> Control Panel> User Accounts
  2. Click 'Change User Account Control Settings'
  3. In the window that appears move the slider to the bottom and hit OK
  4. You will be requested to restart the computer - do so(!)
  5. If you copied the files already (which wont work as the pseudo copy occurs) these copied files should now automatically work

Graceful shutdown in the event of a power failure

Your mSupply server should be attached to a UPS. The UPS should be fitted with a control cable (serial, USB or network cable) that allows control software to detect a low power situation and shut down the server.

In the UPS control software set the shutdown to start at least two minutes before the power will fail.

Set it to run a batch file at that point. The file should contain the single line “net stop Service name” where the service name is the name displayed in the properties when you double-click the service name in the services window. In the example below the service name is “4DS mSupply.4DC” (not to be confused with the display name)

You may wish to test your typing skills by opening a command prompt:

Accessing a cloud hosted server

Access to a cloud hosted mSupply server is through the Windows Remote Desktop Protocol.

Windows client

If the mSupply client software is running on a PC, there are a range of applications that can be used for accessing the cloud hosted mSupply server including Microsoft's own Remote Desktop Connection software that comes included with Microsoft Windows. There are third party implementations that provide additional security and controls. One that we are currently (2016) finding effective is TS-Plus.

Macintosh Client

Access to the the Microsoft Remote Desktop App is available on the Apple Store: https://itunes.apple.com/en/app/microsoft-remote-desktop/id715768417?mt=12

  • The Display Name is the name that will appear on your computer. We suggest you make it: mSupply Remote Access
  • The Computer Name is the name of the domain name of the mSupply server computer that you are connecting to.

Previous: Managing Data Files Next: Configure Dispensary mode

  • admin/server_installation.txt
  • Last modified: 2018/12/09 21:04
  • by mark