Skip to content

Getting Started

Jump to bottom
Finnegan's Owner edited this page Jul 13, 2026 · 5 revisions

Getting Started

Installation

  1. Go to Releases and download the installer for your platform:

    • macOS: .dmg file (universal binary — Apple Silicon and Intel)
    • Windows x86_64: .msi or .exe installer
    • Windows ARM64: .msi or .exe installer
    • Linux x86_64: .deb, .rpm, or .AppImage
    • Linux ARM64: .deb, .rpm, or .AppImage

  2. Install normally for your OS.

macOS Note

If macOS blocks the app because it is unsigned, either:

  • Right-click the app and choose Open, then click Open in the dialog
  • Or run: xattr -cr /Applications/Launcher.app

Prerequisites

  • A JavaFX-enabled JDK must be installed on your machine. The administrator client is a JavaFX application, so a plain OpenJDK will start and then fail with JavaFX runtime components are missing.
  • Launcher does not guess or auto-detect a JDK. It uses the connection's Java Home if set, otherwise java on your PATH (for a new connection, JAVA_HOME is used as the default Java Home if it is set). Set Java Home per connection in the editor to point at a JavaFX-enabled JDK.
  • Before any download, Launcher runs a quick java -version check and stops with a clear Java (with JavaFX) not found error if it can't run.

First Launch

  1. Open Launcher.
  2. Click the Add button in the top right to open the connection editor.
  3. Fill in the connection. Only Name and Address are required to get going, but a couple of other fields matter on a first launch:
    • Name — a label for this server (e.g. "Production")
    • Address — the full server URL, including protocol and port (e.g. https://myserver:8443)
    • Java Home — path to a JavaFX-enabled JDK. Pre-filled from JAVA_HOME if that variable is set. The administrator is a JavaFX app, so this must point at a JDK that includes JavaFX; leave it blank to use java on PATH.
    • Engine Type — identifies the engine and keys the shared JAR cache. Leave the default unless this server runs a different engine than your other connections at the same version (see the cache-collision note in the User Guide).
    • Username / Password — optional; you can enter these at the admin login instead.
    • Group, Heap Size, JVM Arguments, and Notes are optional — see the User Guide for every field.
  4. Click Create to save the connection.
  5. Launch it: double-click the server row, or click the play button (enabled once the status dot goes green).
  6. On the first launch Launcher runs a quick Java check, prompts you to trust the server's certificate (below), then downloads the administrator's JAR files — you'll see download progress as it fetches them. Later launches reuse the cached JARs and start faster. Turn on Show console in the connection options if you want to watch the administrator's output while it starts.

Trusting the server certificate

Integration engine servers almost always use self-signed certificates, so Launcher establishes trust per connection on first use (trust-on-first-use):

  • The first time you connect, Launcher captures the server's leaf certificate and shows you its SHA-256 fingerprint. Verify that fingerprint with the operator out-of-band, then choose Trust certificate to continue. The pin is saved with the connection.
  • On later connects, the server must present the same certificate. If the fingerprint changes, Launcher stops and shows a warning comparing the previously trusted and new fingerprints — do not continue unless the change was expected.

You can review or clear the trusted fingerprint anytime in the connection editor's Security section.

Importing Existing Connections

If you are migrating from MirthConnect Admin Launcher (MCAL) or another Launcher instance:

  1. Click the Import button in the top toolbar
  2. Select the JSON connections file (e.g., <MCAL-root>/data/connections.json)
  3. If any connections already exist with the same IDs, Launcher will warn you and list the duplicates — you can choose to overwrite or cancel
  4. After a successful import, the page reloads to show the new connections

Tips

  • Zoom: Use Cmd/Ctrl + = / - / 0 to zoom in, out, or reset the interface. Your zoom level is remembered across sessions.
  • Help: Click the ? icon next to the title to open the wiki in your browser.
  • About: Click the info icon to see version and credits.

Clone this wiki locally