25.23. mSupply Client for a MAC

Status: mSupply Client (multi-user, connecting to a server) is supported on Mac. mSupply Single User is not supported on Mac.

This guide is based on support ticket #GT-9612-AP "Setup for Mac in Kiribati" and should be expanded as more cases are handled. Reference GitHub issue: https://github.com/msupply-foundation/msupply/issues/18363 (building a server exe that is Mac-client friendly).

Support Scope

Client type	Mac support
mSupply Client (connects to a remote/network server)	✅ Supported
mSupply Single User	❌ Not supported

If a client asks for a Single User install on Mac, redirect them to the Windows single-user build, or confirm whether a networked Client setup would meet their need instead.

Prerequisites

The Mac must be on the same network as the mSupply server (or otherwise have network access to it — VPN, port forwarding, etc.).

You will need the server's IP address to enter into the Client's custom connection settings.

A working copy of the mSupply Client.app build for Mac.

Setup Steps

Confirm the Mac is on the same LAN/network as the mSupply server. If not, arrange VPN/remote access first.

Install the mSupply Client.app on the Mac.

Open mSupply Client and go to the custom server connection setting.

Enter the server's IP address (rather than a hostname) in the custom setting field.

Connect and confirm the client reaches the server.

Code Signing (may be required)

macOS Gatekeeper may block an unsigned mSupply Client.app from opening. If this happens:

The app can be locally code-signed on a Mac before distributing it to the end user (this has been done successfully by support staff prior to sending the app to a client).

Note: exact code-signing command/procedure is not yet documented — add the specific steps here once standardized (e.g. codesign –force –deep –sign - /path/to/mSupply\ Client.app).

Version Notes

For sites needing an update alongside a Mac setup, running the relevant version upgrader (e.g. V9.01.03) on the server may be sufficient — check the current recommended version before advising a client.

Troubleshooting Checklist

Is the Mac on the same network as the server? If not, that's the most common blocker.

Try connecting using the server's IP address directly instead of a hostname in the custom setting.

Does macOS refuse to open the app (Gatekeeper warning)? → Locally code-sign the Client.app.

Confirm the server itself is reachable (ping / port check) before assuming it's a client-side issue.

Known Limitations / Open Work

There's an open GitHub issue to build a server executable that is more Mac-client-friendly: https://github.com/msupply-foundation/msupply/issues/18363. Check this issue for current progress before troubleshooting from scratch.

This guide should be reviewed and expanded by the support team (see internal ticket #GT-9612-AP) — particularly the code-signing steps, which haven't been fully written up yet.

References

Support ticket: #GT-9612-AP — Setup for Mac in Kiribati

GitHub issue: https://github.com/msupply-foundation/msupply/issues/18363

Client: Peter Laing, Beyond Essential Systems (Kiribati)

Last updated: drafted from ticket #GT-9612-AP. Please edit/expand with exact code-signing commands and any additional edge cases encountered.