Backup & Disaster Recovery

Backup & Disaster Recovery

Learn how to implement a robust backup strategy for your Mirth Connect or Open Integration Engine configurations. This guide covers automated backup scripts, retention policies, and step-by-step disaster recovery procedures.

Critical for Production Systems

Healthcare integrations are mission-critical infrastructure. Without proper backups, a server failure or accidental deletion could result in extended downtime and data loss. Implement automated backups before going to production.

Why Git-Based Backups?

Traditional database backups capture a single point in time. MirthSync’s Git-based approach provides superior disaster recovery capabilities:

Feature	Database Backup	MirthSync Git Backup
Point-in-time recovery	Single snapshot	Any commit in history
Change tracking	No history	Full audit trail
Selective restore	All or nothing	Individual channels
Offsite redundancy	Requires separate setup	Built-in with Git remotes
Team collaboration	Not designed for it	Branch and merge

Backup Workflow Overview

Setting Up Automated Backups

Linux/macOS

Cron-Based Automated Backup

Create a backup script that runs automatically:

/opt/mirthsync/backup.sh

#!/bin/bash

# Configuration
BACKUP_DIR="/opt/mirthsync/mirth-backup"
LOG_FILE="/var/log/mirthsync-backup.log"
DATE=$(date '+%Y-%m-%d %H:%M:%S')

# Navigate to backup directory
cd "$BACKUP_DIR" || exit 1

# Pull latest configuration
echo "[$DATE] Starting backup..." >> "$LOG_FILE"
./mirthsync.sh pull -s "$MIRTH_URL" -u "$MIRTH_USER" -t "$BACKUP_DIR" >> "$LOG_FILE" 2>&1

# Check if there are changes
if git diff --quiet && git diff --cached --quiet; then
    echo "[$DATE] No changes detected" >> "$LOG_FILE"
    exit 0
fi

# Commit and push changes
./mirthsync.sh -t "$BACKUP_DIR" git add >> "$LOG_FILE" 2>&1
./mirthsync.sh -t "$BACKUP_DIR" --commit-message "Automated backup $DATE" git commit >> "$LOG_FILE" 2>&1
./mirthsync.sh -t "$BACKUP_DIR" git push >> "$LOG_FILE" 2>&1

echo "[$DATE] Backup completed successfully" >> "$LOG_FILE"

Make the script executable and schedule it:

# Make executable
chmod +x /opt/mirthsync/backup.sh

# Edit crontab
crontab -e

# Add hourly backup (adjust frequency as needed)
0 * * * * /opt/mirthsync/backup.sh

Windows

Task Scheduler Automated Backup

Create a PowerShell backup script:

C:\MirthSync\backup.ps1

# Configuration
$BackupDir = "C:\MirthSync\mirth-backup"
$MirthSyncDir = "C:\MirthSync\mirthsync-3.5.0\bin"
$MirthUrl = "https://mirth-server:8443/api"
$MirthUser = "admin"
$LogFile = "C:\MirthSync\logs\backup.log"
$Date = Get-Date -Format "yyyy-MM-dd_HH-mm-ss"

# Password should be set via environment variable: $env:MIRTHSYNC_PASSWORD

# Navigate to MirthSync directory
Set-Location $MirthSyncDir

# Pull latest configuration
Add-Content $LogFile "[$Date] Starting backup..."
.\mirthsync.sh pull -s $MirthUrl -u $MirthUser -t $BackupDir 2>&1 | Add-Content $LogFile

# Check for changes using git status
$status = git -C $BackupDir status --porcelain
if (-not $status) {
    Add-Content $LogFile "[$Date] No changes detected"
    exit 0
}

# Commit and push changes
.\mirthsync.sh -t $BackupDir git add 2>&1 | Add-Content $LogFile
.\mirthsync.sh -t $BackupDir --commit-message "Automated-backup-$Date" git commit 2>&1 | Add-Content $LogFile
.\mirthsync.sh -t $BackupDir git push 2>&1 | Add-Content $LogFile

Add-Content $LogFile "[$Date] Backup completed successfully"

Schedule with Task Scheduler:

1. Open Task Scheduler
2. Create Basic Task → Name: “MirthSync Backup”
3. Trigger: Daily, repeat every 1 hour
4. Action: Start a program
   • Program: powershell.exe
   • Arguments: -ExecutionPolicy Bypass -File "C:\MirthSync\backup.ps1"

Docker

Container-Based Backup

For Docker deployments, create a backup container:

docker-compose.backup.yml

version: '3.8'
services:
  mirthsync-backup:
    image: eclipse-temurin:17-jdk-alpine
    volumes:
      - ./mirth-backup:/backup
      - ./mirthsync-3.5.0:/opt/mirthsync:ro
      - ./backup.sh:/backup.sh:ro
    environment:
      - MIRTH_URL=https://mirth-server:8443/api
      - MIRTH_USER=admin
      - MIRTHSYNC_PASSWORD=${MIRTH_PASSWORD}
    command: >
      sh -c "apk add --no-cache git bash &&
             crond -f -d 8"
    restart: unless-stopped

backup.sh

#!/bin/bash
MIRTHSYNC="/opt/mirthsync/bin/mirthsync.sh"
BACKUP_DIR="/backup"
DATE=$(date +%Y-%m-%d_%H-%M-%S)

cd "$BACKUP_DIR"
$MIRTHSYNC pull -s "$MIRTH_URL" -u "$MIRTH_USER" -t "$BACKUP_DIR"
if ! git diff --quiet; then
    $MIRTHSYNC -t "$BACKUP_DIR" git add
    $MIRTHSYNC -t "$BACKUP_DIR" --commit-message "Automated-backup-$DATE" git commit
    $MIRTHSYNC -t "$BACKUP_DIR" git push
fi

Backup Frequency Recommendations

Choose your backup frequency based on your change rate and recovery requirements:

Environment	Recommended Frequency	Rationale
Development	Daily	Frequent changes, less critical
Staging/QA	Every 4 hours	Moderate changes, testing workflows
Production	Hourly	Critical systems, minimal data loss
High-volume	Every 15 minutes	Frequent changes, strict RTO/RPO

Optimize Backup Windows

Schedule backups during low-activity periods to minimize impact. MirthSync’s pull operation is read-only and doesn’t affect message processing, but network bandwidth is shared.

Retention Policies

Git Tag-Based Retention

Use Git tags to mark important backup milestones:

# Tag production releases
git tag -a "prod-v2.1.0" -m "Production release 2.1.0"
git push origin --tags

# Tag before major changes
git tag -a "pre-upgrade-$(date +%Y%m%d)" -m "Before Mirth Connect upgrade"
git push origin --tags

Branch-Based Retention

Maintain separate branches for different retention periods:

# Create monthly archive branches
git checkout -b archive/2024-01 main
git push origin archive/2024-01

# Your main branch keeps daily commits
# Archive branches preserve monthly snapshots

Advanced: Automated Cleanup Scripts

Automated Cleanup

Remove old local branches while preserving remote history:

# List merged branches older than 30 days
git branch --merged | grep -v main | xargs -I {} sh -c \
  'if [ $(git log -1 --format=%ct {}) -lt $(date -d "30 days ago" +%s) ]; then echo {}; fi'

Prune Remote Tracking Branches

# Remove stale remote tracking branches
git remote prune origin

# Or automatically prune on fetch
git config --global fetch.prune true

Archive Old Commits

For long-running backup repositories, consider using git-archive to create snapshots:

# Create a ZIP archive of a specific tag
git archive --format=zip --output=backup-2024-01.zip prod-v1.0.0

# Archive and compress
git archive prod-v1.0.0 | gzip > backup-2024-01.tar.gz

Disaster Recovery Procedures

Complete Server Recovery

If your Mirth Connect server is lost and you need to restore everything:

Full Restore

# 1. Clone your backup repository
git clone https://github.com/your-org/mirth-backup.git
cd mirth-backup

# 2. Download and extract MirthSync (Java JAR, not npm)
# See: https://github.com/SagaHealthcareIT/mirthsync/releases
wget https://github.com/SagaHealthcareIT/mirthsync/releases/download/v3.5.0/mirthsync-3.5.0.zip
unzip mirthsync-3.5.0.zip

# 3. Set environment variables for new server
export MIRTH_URL="https://new-server:8443/api"
export MIRTH_USERNAME="admin"
export MIRTHSYNC_PASSWORD="your-password"

# 4. Push all configurations to new server
./mirthsync-3.5.0/bin/mirthsync.sh push -s $MIRTH_URL -u $MIRTH_USERNAME -t . --deploy-all

# 5. Verify deployment
./mirthsync-3.5.0/bin/mirthsync.sh pull -s $MIRTH_URL -u $MIRTH_USERNAME -t .
git diff  # Should show no differences

Selective Restore

Restore only specific channels or components:

# 1. Clone and checkout the desired point in time
git clone https://github.com/your-org/mirth-backup.git
cd mirth-backup
git checkout <commit-hash>  # or tag name

# 2. Push configurations to server
./mirthsync-3.5.0/bin/mirthsync.sh push -s $MIRTH_URL -u $MIRTH_USERNAME -t . --deploy-all

# Note: To restore specific channels, copy only those channel
# directories before pushing, or manually import via Admin Console

Point-in-Time

Restore to a specific point in history:

# 1. Find the commit you want to restore
git log --oneline --all | head -20

# 2. View what was different at that time
git show <commit-hash>

# 3. Checkout that specific point
git checkout <commit-hash>

# 4. Push to server
./mirthsync-3.5.0/bin/mirthsync.sh push -s $MIRTH_URL -u $MIRTH_USERNAME -t . --deploy-all

# 5. Return to current state
git checkout main

Partial Recovery Scenarios

Recover a Deleted Channel

# Find when the channel was deleted
git log --all --full-history -- "Channels/My Channel/"

# Checkout the channel from before deletion
git checkout <commit-before-deletion> -- "Channels/My Channel/"

# Push to server (will restore the channel)
./mirthsync-3.5.0/bin/mirthsync.sh push -s $MIRTH_URL -u $MIRTH_USERNAME -t . --deploy-all

# Commit the restoration
git add .
git commit -m "Restored accidentally deleted channel"

Recover from Bad Configuration Change

# See recent changes
git log --oneline -10

# Identify the bad commit
git show <bad-commit>

# Revert that specific change
git revert <bad-commit>

# Push the reverted configuration
./mirthsync-3.5.0/bin/mirthsync.sh push -s $MIRTH_URL -u $MIRTH_USERNAME -t . --deploy-all

Compare Two Points in Time

# See what changed between two dates
git diff $(git rev-list -1 --before="2024-01-01" main) \
         $(git rev-list -1 --before="2024-01-15" main)

# See changes to a specific channel
git log -p --follow -- "Channels/ADT Processor/"

Multi-Site Backup Strategy

For organizations with multiple Mirth Connect instances:

Branch-Per-Environment Setup

# Production backup
cd mirth-prod-backup
git checkout -b prod
./mirthsync.sh pull -s $PROD_MIRTH_URL -u $PROD_MIRTH_USERNAME -t .
git add . && git commit -m "Initial prod backup"
git push origin prod

# Staging backup
cd mirth-staging-backup
git checkout -b staging
./mirthsync.sh pull -s $STAGING_MIRTH_URL -u $STAGING_MIRTH_USERNAME -t .
git add . && git commit -m "Initial staging backup"
git push origin staging

Monitoring and Alerts

Backup Verification Script

Create a script to verify backup health:

verify-backup.sh

#!/bin/bash

BACKUP_DIR="/opt/mirthsync/mirth-backup"
ALERT_EMAIL="admin@example.com"
MAX_AGE_HOURS=2

cd "$BACKUP_DIR" || exit 1

# Check last commit age
LAST_COMMIT=$(git log -1 --format=%ct)
NOW=$(date +%s)
AGE_HOURS=$(( (NOW - LAST_COMMIT) / 3600 ))

if [ $AGE_HOURS -gt $MAX_AGE_HOURS ]; then
    echo "WARNING: Last backup is $AGE_HOURS hours old" | \
    mail -s "MirthSync Backup Alert" "$ALERT_EMAIL"
fi

# Verify remote is reachable
if ! git ls-remote --exit-code origin > /dev/null 2>&1; then
    echo "ERROR: Cannot reach remote repository" | \
    mail -s "MirthSync Backup Alert - Remote Unreachable" "$ALERT_EMAIL"
fi

Integration with Monitoring Systems

For enterprise monitoring (Nagios, Zabbix, Prometheus):

check_mirthsync_backup.sh

#!/bin/bash
# Nagios/monitoring plugin format

BACKUP_DIR="/opt/mirthsync/mirth-backup"
WARNING_HOURS=2
CRITICAL_HOURS=4

cd "$BACKUP_DIR" || { echo "CRITICAL - Backup directory not found"; exit 2; }

LAST_COMMIT=$(git log -1 --format=%ct 2>/dev/null)
if [ -z "$LAST_COMMIT" ]; then
    echo "CRITICAL - No commits found"
    exit 2
fi

NOW=$(date +%s)
AGE_HOURS=$(( (NOW - LAST_COMMIT) / 3600 ))

if [ $AGE_HOURS -ge $CRITICAL_HOURS ]; then
    echo "CRITICAL - Last backup $AGE_HOURS hours ago"
    exit 2
elif [ $AGE_HOURS -ge $WARNING_HOURS ]; then
    echo "WARNING - Last backup $AGE_HOURS hours ago"
    exit 1
else
    echo "OK - Last backup $AGE_HOURS hours ago"
    exit 0
fi

Security Best Practices

Secure Credential Storage

Never store credentials in backup scripts. Use environment variables or credential managers:

Environment Variables

# Set in your shell profile or systemd service
export MIRTH_URL="https://mirth-server:8443/api"
export MIRTH_USER="backup-user"
export MIRTH_PASS="<from-secret-manager>"

HashiCorp Vault

# Retrieve credentials from Vault
export MIRTHSYNC_PASSWORD=$(vault kv get -field=password secret/mirthsync)
./mirthsync.sh pull -s $MIRTH_URL -u $MIRTH_USER -t .

Access Control

Create a dedicated backup user in Mirth Connect with minimal permissions:

1. Create a new user: mirthsync-backup
2. Assign only “Read” permissions for channels and settings
3. Do not grant “Deploy” or “Write” permissions

Security

Your configuration backup contains sensitive information including database credentials, API keys, and integration endpoints. Ensure your Git remote repository has appropriate access controls and consider encrypting sensitive values.

Testing Your Recovery Plan

Test Quarterly

Schedule quarterly disaster recovery drills to ensure your team can execute the recovery process under pressure. Document any issues and update procedures accordingly.

Recovery Drill Checklist

1. Clone backup repository to a clean machine
2. Verify MirthSync can connect to test server
3. Perform full restoration
4. Verify all channels are present and configured correctly
5. Test message processing on restored channels
6. Document time to recovery (TTR)
7. Note any issues or improvements needed

Next Steps

Now that you have a backup strategy in place:

• CI/CD Setup - Automate testing and deployment
• Multi-Environment Management - Manage dev, staging, and production
• Best Practices - Optimize your MirthSync workflow