Deploy OpenShare Engine on Google Cloud

OpenShare Engine is Saga IT’s maintained build of the Open Integration Engine, a healthcare integration engine for HL7 v2, FHIR, DICOM and X12. The Google Cloud Marketplace product deploys it as one Compute Engine VM in your own project: engine 4.7 on Ubuntu 24.04 LTS, with Java 21 bundled and the signed OpenShare admin plugin preinstalled.

The software is free. You pay Google Cloud only for the resources the deployment creates: the VM, its boot disk and network traffic. The engine’s source code is public under the MPL 2.0 at SagaHealthcareIT/open-integration-engine.

Before you deploy

You need:

• A Google Cloud project with billing turned on and the Compute Engine API enabled.
• Permission to deploy Marketplace products and to create VMs and firewall rules in that project. The deployment page also asks for a deployment service account.
• The public address range of the network you will administer the engine from, in CIDR form. A single address is written as 203.0.113.10/32.
• Optional: a launch document from the OpenShare console, to register the engine with OpenShare (see Optional: register with OpenShare).
• Optional: your own PostgreSQL, SQL Server, MySQL or Oracle database that the VM can reach.

Deployment inputs

Input	What to enter	Default
Deployment name	A name for this engine: up to 54 lower-case letters, digits and hyphens. It becomes part of the VM, firewall rule and network tag names	Generated
Image version	Leave as set	The current OpenShare Engine image
Zone	A zone close to the systems the engine exchanges data with	None: choose one
Machine type	e2-standard-2 (2 vCPUs, 8 GB) suits most single-site engines. The form offers types with at least 2 vCPUs and 4 GB. At first boot the engine sets its Java heap to half the VM’s memory, up to 8 GB	e2-standard-2
Boot disk type	Balanced persistent disk suits most engines	pd-balanced
Boot disk size in GB	At least 20. The embedded database and logs live on this disk, so size it for your message volume and retention	30
Network and Subnetwork	The VPC network the engine should live in. Shared VPC networks from a host project are not offered, because the firewall rules are created in this project	default
Assign an external IP address	Leave on to reach the engine from your network over the internet. Turn it off if you reach it over VPN or Interconnect; OpenShare registration then needs Cloud NAT on the subnet. This setting opens no port	On
Source IP ranges for the admin interface (TCP 8443)	Your administration network’s CIDR ranges, comma-separated. Empty opens nothing on 8443. Prefixes shorter than /8 are refused	Empty
Source IP ranges for SSH (TCP 22)	Your administration network’s CIDR ranges. Add 35.235.240.0/20 if you connect through Identity-Aware Proxy. Empty opens nothing on 22	Empty
OpenShare launch document (optional)	See Optional: register with OpenShare and Optional: your own database. Read only at first boot	Empty

The deployment names the VM DEPLOYMENT_NAME-vm and tags it DEPLOYMENT_NAME-engine. Firewall rules you add later target that tag. In the commands on this page, replace VM_NAME with the VM’s name and ZONE with its zone.

Ports

Port	Used for	Open after deployment?
TCP 8443	The engine’s web interface and API, over HTTPS	Only from the ranges you entered. Closed if you entered none
TCP 22	SSH	Only from the ranges you entered, through the rule the deployment creates
Your channel ports, for example an MLLP listener	Your interfaces	Never opened by the deployment. Add rules yourself (step 6)
TCP 80 and 443	Not used by the engine	Don’t open them

The engine’s outbound traffic (to your systems and, if you registered it, to OpenShare over HTTPS) uses your VPC’s egress rules, which allow all outbound traffic unless you have changed them.

Check your network’s existing rules

The default network that comes with a new project already has a rule named default-allow-ssh that allows SSH from any address (0.0.0.0/0). The deployment doesn’t change it. If you deploy into the default network and want SSH only from your own ranges, delete or narrow that rule.

Step 1: Deploy

1. Open the OpenShare Engine listing on Google Cloud Marketplace and select Launch.
2. Fill in the inputs above and select Deploy.
3. Wait for the deployment to finish. After the VM is running, the engine needs a few more minutes for its first start.

Step 2: Get the administrator password

The deployment generates a random password for the engine’s admin user. The engine sets it at first boot. There is no default password.

• Deployment page: the password is among the deployment’s outputs.

• Over SSH:

  curl -s -H "Metadata-Flavor: Google" http://metadata.google.internal/computeMetadata/v1/instance/attributes/openshare-admin-password

If the VM was created from the image some other way and has no openshare-admin-password metadata key, the engine generates the password itself and prints it to the serial console:

• Cloud console: VM instances, select the VM, then under Logs select Serial port 1 (console). Look for the “OpenShare Engine initial login” block.
• gcloud: gcloud compute instances get-serial-port-output VM_NAME --zone ZONE
• Over SSH: sudo cat /etc/openshare/initial-credentials (readable by root only)

The serial console keeps only the most recent 1 MB of output. If the block has scrolled off, use the file.

Step 3: Open port 8443 to your own network

Skip this if you entered a range for 8443 at deployment. Otherwise allow 8443 to the deployment’s tag from your own range only. Never use 0.0.0.0/0.

gcloud compute firewall-rules create allow-openshare-8443 \
  --network NETWORK --direction INGRESS --action ALLOW --rules tcp:8443 \
  --source-ranges YOUR_RANGE --target-tags DEPLOYMENT_NAME-engine

Step 4: Sign in and change the password

1. Browse to https://EXTERNAL_IP:8443. The VM ships a self-signed certificate, so your browser warns on the first visit.

2. Sign in as admin with the password from step 2.

3. Change the password right away. The initial one stays in the deployment’s outputs, and the engine does not force a change at first sign-in. The new password needs at least 15 characters, with an upper-case letter, a lower-case letter, a digit and a symbol.

4. Remove the initial password from the VM’s metadata. Anyone who can view the VM in your project can read its metadata.

   gcloud compute instances remove-metadata VM_NAME --zone ZONE --keys openshare-admin-password

   Also delete the root-only copy on the VM: sudo rm /etc/openshare/initial-credentials.

Five failed sign-ins lock the account for an hour. For production use, install your own TLS certificate in place of the self-signed one.

Step 5: Connect over SSH and check health

gcloud compute ssh VM_NAME --zone ZONE

Add --tunnel-through-iap if you allowed 35.235.240.0/20 rather than your own address. Then:

sudo systemctl status oieservice
sudo tail -n 100 /opt/OpenShareEngine/logs/mirth.log

The engine is healthy when oieservice is active (running) and the sign-in page loads at https://EXTERNAL_IP:8443.

Step 6: Allow your channel ports

Each listener channel needs its own inbound rule, from your partner’s range only. For example, for an MLLP listener on 6661:

gcloud compute firewall-rules create allow-openshare-mllp-6661 \
  --network NETWORK --direction INGRESS --action ALLOW --rules tcp:6661 \
  --source-ranges PARTNER_RANGE --target-tags DEPLOYMENT_NAME-engine

Optional: register with OpenShare

OpenShare is a separate online service from Saga IT. It is free and optional, and the engine works fully without it. It needs an OpenShare account and acceptance of the OpenShare terms. The service stores no patient data.

1. In the OpenShare console, add a server. In its setup dialog, choose Cloud image, then Generate launch document, and copy the document. It is valid until the time shown under it.

2. Paste it into the OpenShare launch document (optional) field when you deploy.

3. At first boot the engine registers itself. It then connects out to OpenShare over HTTPS. No inbound port is needed.

4. When the console shows the server as registered, remove the document from the VM’s metadata. It holds a single-use token, and any process on the VM can read instance metadata.

   gcloud compute instances remove-metadata VM_NAME --zone ZONE --keys user-data

The document is read only at first boot. Adding it to an existing VM has no effect. If the document is malformed, the engine does not start, and serial port 1 says why. Deploy again with a corrected document.

If you leave the field empty, the engine is never registered and runs standalone.

Optional: your own database

The same field can carry a document that points the engine at your own PostgreSQL, SQL Server, MySQL or Oracle database, alone or together with OpenShare registration. Put TLS in the JDBC URL (for PostgreSQL, sslmode=require). For the document format, email support@saga-it.com. Without such a document, the engine uses its embedded database on the boot disk.

That document contains the database password. After first boot, remove it from the VM’s metadata (gcloud compute instances remove-metadata VM_NAME --zone ZONE --keys user-data). The deployment also keeps its inputs, so anyone who can view the deployment in your project can read the password: use a database account for the engine alone, and rotate its password if that matters to you.

Maintenance

• Operating system updates. Apply Ubuntu updates in a maintenance window: sudo apt update && sudo apt upgrade.
• Backups. With the embedded database, everything is on the boot disk. Set a snapshot schedule on it. With your own database, back that database up as well.
• Machine type. Stop the VM, change its machine type, and start it again. The Java heap was set at first boot and does not follow the new memory size: change the -Xmx line in /opt/OpenShareEngine/conf/custom.vmoptions, then run sudo systemctl restart oieservice.
• New engine versions. Saga IT publishes updated images on Google Cloud Marketplace. Existing VMs are not updated in place.
• Removing the engine. Delete the deployment from the Cloud console’s Solution deployments page. This removes the VM, its disk and the firewall rules the deployment created. Rules you added yourself stay.

Support

Email support@saga-it.com. Include the engine version shown on the sign-in page, the machine type and the relevant lines from /opt/OpenShareEngine/logs/mirth.log. Never include patient data in a support request. See also Getting support.