Installation

Installing the MirthSync Plugin

The MirthSync Plugin is an all-in-one extension that bundles Git, MirthSync CLI, and a graphical interface into a single JAR file. No separate installations required—just download, install, and start using version control.

Prerequisites

Before installing the MirthSync Plugin:

• Open-source Mirth Connect 4.x or Open Integration Engine (OIE) - The integration platform you want to version control
  • Recommended: Open Integration Engine (OIE) - the community-driven open-source fork
  • Legacy open-source Mirth Connect 4.x
  • Commercial Mirth Connect versions - compatibility not guaranteed
• Admin access to Mirth Connect Administrator Console

No Additional Software Required

The plugin includes embedded Git and MirthSync CLI. You don’t need to install Git or MirthSync separately—everything you need is bundled in the plugin JAR file.

---

Installation

Admin Console (Recommended)

Best for: Most users | Requirements: Admin Console access only

The easiest way to install the plugin—no server access required.

Step 1: Download the Plugin

Download mirthsync-plugin.jar from the MirthSync Plugin page or GitHub releases.

Verify Download

Check the file size - the JAR should be around 5-10 MB. If significantly smaller, the download may be incomplete.

Step 2: Open Admin Console Extensions

1. Launch Mirth Connect Administrator
2. Navigate to Extensions:
   • Click Settings → Extensions (or Tools → Extensions depending on version)
3. Install Plugin:
   • Click Install Extension button
   • Browse to the downloaded mirthsync-plugin.jar file
   • Click Open or Install

Step 3: Restart Mirth Connect

The Admin Console will prompt you to restart Mirth Connect:

• Click Yes or Restart Now when prompted
• Wait 30-60 seconds for Mirth Connect to restart
• The Admin Console may disconnect—this is normal

Step 4: Verify Installation

1. Reconnect to Admin Console (if disconnected)
2. Look for MirthSync panel:
   • Check the left sidebar navigation
   • Look for “MirthSync” or a version control icon
3. Verify in Extensions:
   • Settings → Extensions
   • MirthSync should appear in the installed extensions list

Success!

If you see the MirthSync panel, installation is complete.

File System

Best for: Server administrators, automated deployments | Requirements: File system access to server

For server administrators who prefer command-line installation or need to automate deployment.

Step 1: Download the Plugin

Download mirthsync-plugin.jar from the MirthSync Plugin page or GitHub releases, then transfer to the Mirth Connect server (if remote).

Step 2: Locate Extensions Directory

Find your Mirth Connect extensions directory:

Linux

Default location:

/opt/mirthconnect/extensions/

Verify directory exists:

ls -la /opt/mirthconnect/extensions/

If different location:

# Find Mirth Connect installation
ps aux | grep mirth | grep -v grep

# Extensions directory is: [MIRTH_INSTALL_DIR]/extensions/

Windows

Default location:

C:\Program Files\Mirth Connect\extensions\

Verify directory exists:

dir "C:\Program Files\Mirth Connect\extensions\"

If different location:

Check Mirth Connect service properties. Extensions directory is located at: [MIRTH_INSTALL_DIR]\extensions\

macOS

Default location (app bundle):

/Applications/Mirth Connect.app/Contents/extensions/

Or custom install location:

/opt/mirthconnect/extensions/

Verify directory exists:

ls -la "/Applications/Mirth Connect.app/Contents/extensions/"

---

Step 3: Stop Mirth Connect

Stop the Mirth Connect service before installing the plugin.

---

Step 4: Install the Plugin

Copy the plugin JAR file to the extensions directory:

Linux

# Copy plugin to extensions directory
sudo cp mirthsync-plugin.jar /opt/mirthconnect/extensions/

# Set proper permissions
sudo chmod 644 /opt/mirthconnect/extensions/mirthsync-plugin.jar

# Set proper ownership (if needed)
sudo chown mirthconnect:mirthconnect /opt/mirthconnect/extensions/mirthsync-plugin.jar

# Verify installation
ls -l /opt/mirthconnect/extensions/mirthsync-plugin.jar
# Should show: -rw-r--r-- 1 mirthconnect mirthconnect [size] mirthsync-plugin.jar

Windows

File Explorer

1. Navigate to download location
2. Copy mirthsync-plugin.jar
3. Navigate to C:\Program Files\Mirth Connect\extensions\
4. Paste the file
5. If prompted for admin permission, click “Continue”

Command Line

# Copy the file (run as Administrator)
Copy-Item mirthsync-plugin.jar "C:\Program Files\Mirth Connect\extensions\"

# Verify installation
dir "C:\Program Files\Mirth Connect\extensions\" | findstr mirthsync
# Should show: mirthsync-plugin.jar

macOS

# For app bundle installation
sudo cp mirthsync-plugin.jar "/Applications/Mirth Connect.app/Contents/extensions/"

# Or for custom installation
sudo cp mirthsync-plugin.jar /opt/mirthconnect/extensions/

# Set proper permissions
sudo chmod 644 "/Applications/Mirth Connect.app/Contents/extensions/mirthsync-plugin.jar"

# Verify installation
ls -l "/Applications/Mirth Connect.app/Contents/extensions/mirthsync-plugin.jar"
# Should show the file with proper permissions

---

Step 5: Start Mirth Connect

Start the Mirth Connect service to load the plugin.

---

Step 6: Verify Installation

1. Open Admin Console and log in
2. Look for MirthSync panel in the left sidebar
3. Check logs (optional) for “MirthSync Plugin loaded successfully”

Success Indicators

• MirthSync panel appears in Admin Console
• No error messages in logs
• Plugin shows “Ready” or “Initialize Repository” button

---

Post-Installation Configuration

Configure Git User Information

Set up your Git identity for commits:

1. Open plugin settings

   • Click the Settings button (gear icon) in MirthSync panel

2. Enter Git information

   • Name: Your full name (e.g., “John Smith”)
   • Email: Your email address (e.g., “john.smith@example.com”)

3. Save settings

Or configure via command line:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

---

Set Repository Path

Configure where MirthSync will store your Git repository:

1. Default path:

   • Linux: /var/lib/mirthconnect/repository
   • Windows: C:\ProgramData\MirthConnect\repository
   • macOS: /Library/Application Support/MirthConnect/repository

2. Change path (if needed):

   • Plugin Settings → Repository Path
   • Enter custom path
   • Ensure the path:
     • Exists or can be created
     • Is writable by Mirth Connect service user
     • Has sufficient disk space (at least 500MB recommended)

---

Configure Remote Repository (Optional)

If using a remote Git repository:

For SSH:

# Generate SSH key on Mirth Connect server
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Display public key
cat ~/.ssh/id_rsa.pub

# Add public key to GitHub/GitLab/Bitbucket:
# GitHub: Settings → SSH and GPG keys → New SSH key
# GitLab: Preferences → SSH Keys
# Bitbucket: Personal settings → SSH keys

For HTTPS:

• Use personal access token instead of password
• GitHub: Settings → Developer settings → Personal access tokens
• Create token with repo scope
• Use token as password when prompted

---

Troubleshooting

Plugin Not Appearing in Admin Console

Symptoms:

• MirthSync panel doesn’t appear after installation
• No MirthSync option in navigation

Solutions:

1. Verify plugin file location

   Linux

   ls -la /opt/mirthconnect/extensions/ | grep mirthsync
   # Should show: mirthsync-plugin.jar

   Windows

   dir "C:\Program Files\Mirth Connect\extensions\" | findstr mirthsync
   # Should show: mirthsync-plugin.jar

2. Fully restart Mirth Connect

   • Stop the service completely
   • Wait 10-15 seconds
   • Start the service

3. Check logs for errors

   grep -i "error.*mirthsync" /opt/mirthconnect/logs/mirth.log

4. Verify Mirth Connect version

   • Requires Mirth Connect 4.x+ or OIE
   • Check: Help → About in Admin Console

---

”Permission denied” on repository operations

Symptoms:

Error: Permission denied: /var/lib/mirthconnect/repository

Solutions:

# Check current permissions
ls -ld /var/lib/mirthconnect/repository

# Set correct ownership (Linux)
sudo chown -R mirthconnect:mirthconnect /var/lib/mirthconnect/repository

# Set correct permissions
sudo chmod -R 755 /var/lib/mirthconnect/repository

---

Next Steps

Continue to Plugin Guide

Now that the plugin is installed, the Plugin Guide will show you:

• Using the plugin interface
• Configuring presets
• Working with execution modes
• Git operations from the Admin Console

→ View Plugin Guide