This is an old revision of the document!
2.04. Client/Server FAQ
mSupply Server Requirements
OPERATING SYSTEM:
- Windows Server 2019 or above
- Windows 10 Pro can be used on laptop servers at smaller remote sites
MEMORY:
- New mSupply installation: 16GB minimum
- Migration of existing mSupply Server: multiply mSupply datafile size + index-file by 1.5 (e.g. datafile 20GB + index-file 2GB x 1.5 = 33GB RAM min)
PROCESSOR:
- 4 cores minimum
DRIVES:
- Root drive: 100GB min
- Data Backup: 100GB minimum allocated for mSupply backups (preferably on an additional volume rather than on the root drive)
NETWORK:
- Assign a local static IP address to server
BACKUPS:
- We can provide remote daily datafile backups to Backblaze cloud storage. We utilise an application on the server to encrypt all data before sending to the cloud storage so your is safe. This service will require urls to be whitelisted if your server restricts outbound traffic
Port & Firewall Configuration
Central Sync Server
Our standard port configuration for an mSupply sync server (where remote sites need to connect to a central server over internet). Alternative ports can be used if required, for example if TSPlus remote kiosk access is not required then the mSupply web server can be configured to run over port 443
| Service | Allow Port | Protocol | Network | Requirement |
|---|---|---|---|---|
| mSupply Web Server | TCP 2048 | HTTPS | Public | mSupply web server traffic from remote mSupply sync sites |
| mSupply Dashboards | TCP 3000 | HTTPS | Public | mSupply Dashboard server traffic (if dashboards are to be accessible from the internet) |
| TSPlus Remote Web Kiosk | TCP 443 | HTTPS | Public | if running TSPlus for remote kiosk access to mSupply Client on the server |
| SSL renewal | TCP 80 | HTTPS | Public | Required for automatic SSL renewal via ACME http challenge (no other web traffic will use this port) |
| mSupply ColdChain API | TCP 8090 | HTTPS | Public | For mSupply ColdChain API (if used) |
| mSupply Application Server | TCP 19812, 19813, 19814 | Local | mSupply Client connections to mSupply application server over LAN | |
| mSupply broadcast | UDP 49157 to 65535 | Local | mSupply will automatically broadcast on the local network over this UDP port range to find the mSupply server |
mSupply Server (Central or Remote) with no syncing remote sites
All mSupply Client applications connect to the server over the LAN. There are no remote sites that need to sync to the central server.
| Service | Allow Port | Protocol | Network | Requirement |
|---|---|---|---|---|
| mSupply Application Server | TCP 19812, 19813, 19814 | Local | mSupply Client connections to mSupply Server over LAN | |
| mSupply Client broadcast | UDP 49157 to 65535 | Local | mSupply Clients will automatically broadcast on the local network over this UDP port range to find the mSupply server |
UDP Ports: If a local static IP address is assigned to the mSupply Server then mSupply Clients can be configured to find the server without needing to open the UDP broadcast ports. This Client configuration is covered in a section below
Separate Dashboard Server Instance
The mSupply Dashboard application uses a PostgreSQL database. It may be advisable to run the Dashboard and Postgres servers together on a separate server instance from the mSupply server so that each instance can be configured specifically for the application that it is running, and so server resources required by Postgres do not interfere with the smooth functioning of mSupply Server.
If mSupply Dashboards and PostgreSQL are running on a separate server instance to the mSupply Server the following configuration will be required for the dashboard server:
| Service | Allow Port | Protocol | Network | Requirement |
|---|---|---|---|---|
| PostgreSQL | TCP 5432 | Local | export of data from the mSupply db to the Postgres dashboard db | |
| mSupply Dashboards | TCP 3000 | HTTPS | Public | mSupply Dashboard server traffic (if dashboards are to be accessible from the internet) |
mSupply Client Requirements & Configuration
OPERATING SYSTEM:
- Windows 10 64 Bit
MEMORY:
- 4GB minimum, 8GB recommended
If the UPD ports on the server are not open, or the mSupply Clients are on a separate subnet to the mSupply Server, then the Clients will not automatically find the Server. In this case the Server will require a static local IP address (which is good practice either way).
There are two methods to direct mSupply Clients to the IP address of the mSupply server:
1) Client configuration file
After mSupply Client has been installed edit the EnginedServer.4Dlink found at this path C:\mSupply client\Database using notepad. Replace <SERVER IP ADDRESS> in the code below with the Server IP. This same edited file can then be deployed to the client database folder of all the mSupply Client installations on this LAN.
<?xml version="1.0" encoding="UTF-8"?><database_shortcut is_remote="true" server_database_name="mSupply" server_path="<SERVER IP ADDRESS>:19813" cache_folder_name="mSupplyClient"/>
2) Client Server Connection Window
- Double click on the mSupply client icon but hold down the alt key just after double clicking (This will open Connection to 4D Server window)
- Go to the 'Custom' tab as per the screenshot attached
- In project name field enter mSupply
- In the Network address field enter the server ip address
- Click OK (if Client successfully connects the connection config will be saved and this process will not need to be repeated)
Standard Sync or Mirror Sync?
For more information on both our standard sync and mirror sync setups please see this page of our docs
2.02. Installation
Synced system
If you are installing mSupply within a synced system, then it is quite likely that you should not be installing the single-user version as described in the section below. The instructions to follow depend on which sort of site you are installing:
- Single-User sync satellite site:
- Contact the mSupply Foundation support to obtain the correct version of mSupply Single-User. It may not be the version on the mSupply Downloads web page
- Then follow the instructions for Sync Site Import
Contact mSupply Foundation support for clarification: support@msupply.foundation
Single-User system
We are assuming you have obtained mSupply from the mSupply Downloads web page.
- If you are using a Windows machine, you have downloaded the file you need, and you have saved it to your desktop, it is important that you saved the file with an
.exeextension or it will not run. You can rename a file by right-clicking on it. The name of the file should be something likemSupply_Single_User_V4-07-09. - It is possible to allow mSupply to be run from multiple Windows accounts (e.g. admin and non-admin accounts). However there are a few precautions / tweeks:
- If you are switching between admin and non-admin accounts, you will need to close mSupply before switching. Single user is intended to be used on one account at a time, and will throw an error if already open on another account.
- Data file location needs to be in a commonly accessible location, e.g.
C:\mSupply_Datafile. - Any backup location needs to be in a commonly accessible location, e.g.
C:\mSupply_Backup.
It is strongly recommended that users who are not familiar with program installation adhere to these directions.
- Double-click the installer and it will automatically run the mSupply installer.
- The installer will do the following:
- Create a folder on your chosen drive called “mSupply”
- On Windows the example data file is installed in the My Documents/mSupply/Example sub folder.
- NOTE: You can use this data file for practice. (Or use the tutorial at the start of the manual to learn the basics quickly)
- Install the “mSupply.exe” application and associated files. Double-clicking this file will do the same as double-clicking the “start mSupply” icon on your desktop.
- Install readme.txt - information on licensing and using mSupply.
- Create a shortcut on your desktop: start mSupply
- Create a mSupply folder entry in the Programs section of your Start menu.
Now you are ready to begin! Proceed to the section below on starting the example database.
Example data file
The mSupply installer treats Example data files in a special way. Re-installing mSupply on a previous installation will replace all the files except the Example data file. This is to prevent valuable data from being deleted as users may have started entering actual stock into the Example data file.
To install a fresh copy of the Example data file on Windows you can carry out one of the options described below:
- Un-install mSupply using the Windows menu Start > Program Files > mSupply > Uninstall mSupply . This will remove all installed files of mSupply which includes the Example data files. Re-installing mSupply now will install a fresh copy of the Example data file.
- You can manually delete the Example data file and re-install mSupply. The mSupply installer will install a fresh copy of the example database as the previously installed file has been deleted.
On Macintosh machines, simply replace the Example folder from the mSupply installer image.
Notes for Windows users
Date format
- In the regional settings in Control Panel, we recommend that the short date format is set to display only 2 digits for the year (YY, not YYYY).mSupply lists are set up to allow only enough space for 4 digits with most font sizes, but occasionally 4 digit years may be truncated. Having the wrong setting here will only affect display, not the actual data. It does not matter if you use DD/MM/YY or MM/DD/YY or YY/MM/DD
- If the display of lists in mSupply overlaps the separator lines, turn off large font in the display control panel.
| Previous: 2.01. Requirements | | Next: 2.03. Starting mSupply for the first time |
2.01. Requirements
For mSuppy Mobile, refer Requirements
For more detailed configuration information on mSupply Client/Server setups please see this FAQ page
Hardware requirements
General hardware recommendations
We have clients running mSupply on a wide range of hardware in a wide range of operating environments. We are happy to discuss hardware options further - please contact support@msupply.foundation, but here are our general recommendations:
- In environments with regular power outages, which is most institutions using mSupply
, it is highly recommended to procure Laptop machines rather than desktop machines - refer to why we now recommend that you use laptops below. - A connected printer is not absolutely necessary in every situation, but for most situations it is a requirement. A laser printer or an ink 'tank' printer is preferable.
- Buy hardware for which good after sales support is available.
- Buy brands with a reputation for quality (even if it means buying a slower/older machine).
Hardware Requirements
As of version 7.17 and above, Mac OS is no longer supported for mSupply Client.
Hardware requirements vary widely depending on what you want to use mSupply for. Here's a rough guide:
| Machine | Minimum | Recommended |
|---|---|---|
| Windows Client Machine (For use with server) | 64 bit, Intel i5 or AMD Ryzen 5 Processor, 16GB RAM, 120GB of disk space, Windows 11 (or higher) | Intel i7+ AMD Ryzen 5+ Processor, 16GB+ RAM, 256GB+ of disk space |
| Windows Central Server (Central server on a synced system) | 64 bit, Intel i9 or AMD Ryzen 9 Processor, 32+ GB RAM, 4 x SSD/HDD volumes, 3 configured as RAID1 or RAID5 with hot spare plus daily backups to the fourth volume plus daily off-site backups, Windows Server 2016+ | Cloud hosted on a reputable service, Windows Server 2022 or above |
| Windows Remote Server (Remote server) | 64 bit, Intel i7 or Ryzen 7 Processor (or better), 16 GB RAM, 500 GB NVMe/SDD volume with daily backups to an external volume plus daily off-site backups, Windows 11 (or higher), Attached to a Smart UPS (see below) | 64 bit, Intel i9 or Ryzen 9 Processor (or better), 32+ GB RAM, plus regular off-site backups, Windows 11 (or higher) |
| Windows Single-User Machine | 64 bit, Intel i7 or Ryzen 7 Processor, 8 GB RAM, 256GB HDD/SDD volume plus daily backups to an external volume plus daily off-site backups Windows 11 (or higher) | 64 bit, Intel i9 or AMD Ryzen 9 Processor (or better), 16+ GB RAM, 500GB HDD/SDD plus daily backups to an external volume plus daily off-site backups |
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
If you are running a server that is not in a datacentre with proper power protection: Beware of Solid State Drives (SSDs) without Power Loss Protection!
At least one country using mSupply on servers in health facilities 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. When the above-mentioned experience happened, there was precious little information available for facilities suffering from the sort of chronic power supply issues which the majority of mSupply users experience. Now there is more literature - refer here : Surviving SSD sudden power loss
We now recommend that you use laptops
Laptop machines, preferably with long battery life, will almost always be the best solution in terms of both cost and effectiveness. See below for the reasons why.
The problem with power cuts and UPSes
In our experience, the primary cause of mSupply database corruption is ungraceful shutdowns of the computer hosting the mSupply database. Ungraceful shutdowns occur when power to the computer is cut instantly, without any notification to the computer to shut down gracefully.
Ungraceful shutdowns on client computers will not result in mSupply database corruption. They may result in incomplete data record entry, but that can be rectified once power is restored.
A common mitigation to prevent ungraceful shutdowns is to use an Uninterruptible Power Supply (UPS). If the computer is protected by a normal UPS, then we can still have ungraceful shutdowns when the battery power runs out. A 'smart' UPS detects when the battery power is about to run out and sends a notification to software on the server which triggers a graceful shut down of the computer. To enable this, there needs to be a cable connection (normally USB) between the UPS and the computer combined with software running on the computer. Even if the machine is protected by a smart UPS, there are a number of circumstances where this UPS protection fails:
- Cable becomes disconnected
- Software isn't configured correctly or doesn't start up
- UPS batteries degrade (normally within 2 years of installation in environments with regular power cuts) and there is too little capacity to run long enough for the computer to shut down gracefully after receiving the notification from the UPS
The merits of laptops
Laptop computers tend to be much more resilient to power failure:
- A laptop's built-in 'smart' UPS is very reliable
- The internal batteries last much longer than UPS batteries
- Even if the laptop internal battery degrades, the 'smart' function appears to work much more reliably than a standalone UPS communicating with a 'tower' computer.
Here are some additional advantages of laptops vs. desktop computers:
- Can be more resilient to hot and humid working environments if you buy the right model.
- Lower cost of freight:
- To send the machine to site
- To send spare parts for repair on-site
- To retrieve the machine from site for any repairs that can not be undertaken on site
There are countries using mSupply where the cost of sending a 40kg traditional server computer to the site is comparable to the purchase price of the server.
- Wi-Fi capability normally included without extra cost
- Bluetooth capability normally included without extra cost
- 'Sound card', speaker, earphones and video camera normally included without extra cost
Battery life
While the consequences of running out of battery power on a laptop is not as catastrophic as on a desktop machine, it is still good to be able to keep your mSupply system running through long power cuts. Unfortunately most laptop manufacturers don't advertise how long their batteries last, even if they do last a long time! Fortunately, there are websites with reviews on laptops where the battery life has been tested and reported.
Security
A concern with laptop computers is security. It is easier to steal a laptop computer from an office than it is to steal a desktop computer. For this reason, laptops are normally configured with a physical locking feature such as Kensington lock slot or Noble wedge lock slot. Don't buy a laptop without one of these security lock features.
Keyboard
Because mSupply is dealing with lots of numbers (quantities of stock), it is highly recommended to have a keyboard with a numeric keypad. Smaller laptop computers (14“ screen or less) will not have this. Smaller laptop computers normally have an impractically small screen. It is therefore recommended to procure either:
- A laptop computer with a keyboard that includes a numeric keypad - which will necessarily entail a larger screen or
- A smaller laptop computer with an external keyboard, mouse and maybe even external screen. We don't recommend wireless external keyboard or mouse. Battery replacement is expensive and environmentally irresponsible.
Backup system
Once you start using mSupply, it is of crucial importance that you have a method of backing up your data. mSupply stores all its data in a file that rapidly becomes large. You need, therefore, to have a high capacity removable storage device. We strongly recommend the use of an external hard disk using either firewire (IEEE 1394) or USB2 to facilitate off-site storage of backups.
- See the section in Preferences that covers mSupply's built-in backup features that allow backup to another disk, and to an internet backup site… you'll find it here: Backup
- If not using our internet backup service, you need to be able to store backed up data off-site to prevent the risk of loss by fire, theft, etc.
Sustainable Solutions will not be able to help you recover lost data in the event of hardware failure if no backup is available.
Antivirus
Windows based operating systems are particularly prone to malware if precautions are not taken. We recommend the following precautions:
- Install a reputable anti-virus program, including web protection if the computer has access to the internet.
- Disable USB ports - refer to this site for suggested methods.
Ensure that access to passwords to allow exceptions to the above two measures are kept secure.
Upgrading mSupply from previous versions
If you open a data file that was created with a previous version, it will automatically be updated to the new format. Please note that this process may take some time.
Note that if you are using a version earlier than v1.96 you must first upgrade to v1.96 and then to version 2 or 3.
IMPORTANT! Always make a backup of your data file before upgrading, and preferably keep a copy off-site. We will not be able to help you in the event of some unexpected disaster if you haven't followed this advice!
| Previous: 2. Setting Up mSupply: Technical Guide | | Next: 2.02. Installation |
2.03. Starting mSupply for the first time
To start mSupply, either
- double-click the start mSupply icon on your desktop, or
- choose the start mSupply item from the mSupply menu in the programs section of the Start menu (on Windows). If this is the first time mSupply has been started after installation, then an example data file will be opened allowing you to follow the mSupply tutorial. mSupply will present you with a log in window.
Note that mSupply will “remember” the last data file used, and automatically present the log-in window for that file unless you move or rename your data file. If you do this, mSupply will show you a standard open/save window for you to choose the new name/location of your data.
Creating a new data file
Create a new data file while opening mSupply:
- Quit mSupply if it is running.
- Start mSupply and then immediately hold down the Alt key. You will now be shown the following dialogue box with a number of radio buttons with the different options available:
- Choose the 3rd radio button Create a new data file.
- Another window will open where you can choose the location and name of your new data.
- You will be prompted for where to create the log file. Generally, it is OK to put the log file in the same location as the data file.
Default file location
- Once mSupply has opened a particular data file, that data file becomes the default data file, and will be opened on restarting mSupply.
- To open a different file, it must be chosen as described later.
- If the default data file is renamed or moved to a different location, it must be opened using its new name or location.
Log-in to mSupply
The first time you use mSupply, you will be presented with the log-in window like this:
mSupply® ships with three users. “user 1” and “user 2” are the designer and administrator - these two users cannot be deleted, but they can be edited, allowing the use of appropriate names and making changes to their passwords and permissions.
- You should select user 1(pass=user1) from the list
- Enter the password “user1” (without the quotes). When different users with their own level of access have been set up, you will then log-in by selecting your user name and typing your own password.
- From the drop down list, select the store with which you are working. Most mSupply users will be operating with a single store, but for users operating with more than one store, the login screen allows you to select any of the stores to which you have access. After selecting the desired store, all transactions will relate to that store until you return to the login screen and select a different store from the drop down menu.
- Supervisors and other Level 1 users will have an additional menu item, Supervisor - All stores . In this mode, all stores are accessible, and you would use this mode, for instance, when placing an order for supplies which will be distributed to a number of stores. Further information is available here: Show stores
Finally, click OK to login
Preparing mSupply for actual use
The following 2 steps are necessary to start mSupply for the first time.
- Create a new data file
- Prepare the new data file for use
Create a new data file
In order to create a new data file, see creating a new data file above.
Save the data file in a location that you can easily find for doing backups. We suggest you create a folder called “mSupply data” inside the My Documents on Windows PC or the documents folder on a MAC to store your data file.
Prepare the new data file for use
- Choose your home currency. Currencies are used when you are calculating cost prices for orders, and when you are comparing quotations from suppliers. Choose Special > Currencies. If your currency is not already shown, click the New button at the top of the window and choose from the pick-list the three letter code abbreviation of the currency you will use to operate your database (e.g. “INR” for Indian Rupees, or “SAR” for South African Rands, or “USD” for US dollars). Set the “Rate” to “1”.
- Enter your Preferences. Choose File>Preferences to do this. Read section 16. Preferences of this User Guide to learn what the different Preference settings do.
- Enter your Suppliers and Customers.
- If you have a computer file holding your customer and/or supplier details, it can be imported directly into mSupply. See 17.03. Importing names.
- You can also do this as you go along simply by entering a customer or supplier the first time you create an invoice or order from them.
- Enter the items you keep in stock. There are a number of ways you can do this:
- If you have a computer file holding details of the items you stock, it can be imported directly into mSupply. See: 17.01. Importing items.
- A file containing the WHO essential drug list is available from the download page of the mSupply web site. You are encouraged to use this file should you have no computer file of your own.
- You can enter each item using the New item Command from the item menu.
- Enter your stock figures.
- If you have a computer file holding both details of the items you stock and your current stock figures, it can be imported directly into mSupply. See: 17.02. Importing stock.
- Your opening stock may be entered manually; choose Item>Inventory adjust - add stock , and enter the required details.
- If you intend to record the location of each item, you should define the locations that your store contains. See: 4.06. Stock locations and location types.
About Stores
At the log in window you have the option to log into a specific store or to log in as 'Supervisor' by choosing option 3 shown in the below window.
Unless you intend to use multiple virtual stores in mSupply you can ignore this option. More information will be found here: Virtual stores
About Dispensary Mode
mSupply allows you to log in in two different modes, Store mode or Dispensary mode . Each user can have his/her permissions set to allow or disallow each mode.
Each mode presents the user with a different menu bar and different windows, depending on whether you are issuing stock to an organisation or an individual
See section 10.01. Dispensary mode
| Previous: 2.02. Installation | | Next: 3. Tutorial |