MirrorSync 6 advanced topics

From 360Works Product Documentation Wiki
Revision as of 17:00, 18 January 2022 by Ryan (Talk | contribs)

Jump to: navigation, search

The documentation on this page is for MirrorSync 5. Much of this also applies to MirrorSync 6. We are in the process of updating the documentation for MirrorSync 6.


Welcome to the advanced section of the MirrorSync documentation! This guide will help you customize MirrorSync to suit your development needs, and provide detailed instructions for various situations. If you would like a good general overview of the software, please read through the basic set up documentation first!

 360Works Plugins for FileMaker

Contents

Deployment questions

How do I uninstall MirrorSync?

To uninstall on Mac, run the 'Mac Uninstaller.pkg' that comes with the MirrorSync. On Windows, run 'C:\Program Files\360Works\Uninstall.

On either platform, you can also run the '360Works Admin.jar' application (/Applications/360Works Admin.jar or C:\Program Files\360Works Admin.jar) and remove the MirrorSync instance. However, this does not remove the 360Works service, which is shared by other 360Works applications such as Zulu. You must use the uninstaller to completely remove the 360Works service.

Installation for hosting providers

To install multiple instances of MirrorSync, choose the Hosting provider option in the installer. This is exactly the same as the regular installation process, except that it will allow you to rename the instance of MirrorSync. You can continue running the installer as many times as you like, once per client, renaming each instance to something unique. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances. New in MirrorSync 5, log files are now separated by the MirrorSync application name. This is important for hosting providers to be able to see each customers log files separately, and makes troubleshooting with 360Works easier.

Hosting providers should read the next item about using sub-admin accounts with MirrorSync.

If MirrorSync is being installed on a different computer than your FileMaker Server, read the 'split server deployments' section below.

If you are installing MirrorSync on a Linux box, read the section below titled 'How do I install on Linux?' In addition, we recommend customizing your server.xml file and setting the startStopThreads attribute to at least as many instances as you're hosting, to make Tomcat start and stop much faster. Here's an example: <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true" startStopThreads="30">

For installation on Mac or Windows, we recommend you use the installer. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:

  • Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.
  • Downloads and installs an instance of Tomcat 9 into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)
  • Copies and renames the installer's MirrorSync.war, which deploys the web app, as well as the other supporting material into the folder.
  • Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.
  • Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter or a URL Rewrite rule for the URL redirect.
  • Copies a lightweight Admin Utility JAR file to manage Tomcat to either C:\Program Files\360Works or /Applications.

If upgrading from an older version of MirrorSync, we'll remove the URL redirects for the old MirrorSync.

If you prefer to skip the installer and manually deploy using your own instance of Tomcat that you've set up, please note and follow these instructions:

  1. Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as. This is where MirrorSync stores its private data including the internal sync database and the stored configurations. If you have a strong preference for locating this someplace else, because of disk space for example, configure a '360directory' system property in Tomcat to point to some other path.
  2. Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'MyCustomerSync.war' If you decide to run multiple instances of MirrorSync with the same name (using multiple instances of Tomcat), you'll need to set '360directory' separately for each Tomcat instance, otherwise those multiple instances will overwrite each other's private data.
  3. Drop that .war file into the webapps directory in your Tomcat instance.
  4. Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).
  5. If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. See tomcat documentation on how to do this.

Regardless of whether you use the installer or not, if you install enough instances of MirrorSync, you may start to run out of memory. If the memory error messages you get talk about PermGenSpace, then the memory problem is related to loading the MirrorSync classes, not the memory used during actual sync operations. In this case, modify the file at C:\Program Files\360Works\Applications\bin\setenv.bat (Windows) or /Library/360Works/Applications/bin/setenv.sh (Mac) and add this to the list of launch arguments:

-XX:PermSize=64m -XX:MaxPermSize=256m

Using a FileMaker sub-admin account

Unfortunately, the fmsadmin command line tool, which MirrorSync uses for servicing download link requests, does not work with sub-admin accounts. We have reported this as a bug to FileMaker. In the meantime, there is another solution for this problem: In the 360Works/Applications/conf/Catalina/localhost/MirrorSync.xml file, customize the fmsAdminUsername and fmsAdminPassword properties. Insert the full administrative user account information here, and MirrorSync will use that when downloading files or generating download links without prompting the users. In this way, your MirrorSync users can download files without ever needing full FileMaker Server admin credentials.

Split server deployments

If your FileMaker deployment is split onto multiple machines, you can use any of these three configurations:

  1. Run MirrorSync on just the FileMaker Server, instead of the Web Publishing Engine
  2. Run MirrorSync on the Web Publishing Engine. If you choose this option, then it is also recommended that you install MirrorSync on the FileMaker Server. This will enable download links to work. You do not need to enter a license key for the extra copy of MirrorSync running on FMS.
  3. Run MirrorSync on some computer other than the Web Publishing Engine or FileMaker Server. This is a good option if you prefer to deploy MirrorSync on Linux. If you choose this option, then it is also recommended that you install MirrorSync on the FileMaker Server. This will enable download links to work. You do not need to enter a license key for the extra copy of MirrorSync running on FMS.

Regardless of which computer you install on, be sure that when you are configuring MirrorSync, you specify that the Web Publishing and Database Servers are on different computers. This option is on the first screen in the configuration process.

How do I install MirrorSync on Linux?

MirrorSync runs very well in Linux - it's our preferred deployment platform, and it's how we deploy our live demo file.

We assume that you are familiar with Linux, and have already installed Java and Tomcat (version 7 or later should work. We do our testing with Tomcat 9). Here is the setup process:

  • Create directory at /var/lib/360works - make it readable and writeable to Tomcat user (you can put the directory anywhere you want on the filesystem - if you choose a different location, set the '360directory' system property to the location you select).
  • Copy the MirrorSync.war file into your webapps directory.
  • Wait a few seconds for this to deploy, and then modify the file at ${TOMCAT_HOME}/conf/Catalina/localhost/MirrorSync.xml. Set the adminUsername property, and either the adminPassword or preferably the adminPasswordHash. While you're in this file, skim over the other properties to see if you want to customize any of them. Note: This file may not be called MirrorSync.xml. In some cases the settings file will be in this location and named context.xml instead of MirrorSync.xml. If this is the case, open that file and confirm it is indeed the the correct file. If it is you will see the adminUsername and adminPassword properties, amongst other properties . Once you have confirmed that it is the correct file, rename it to MirrorSync.xml and then edit it again, this time adding the values for adminUsername and adminPassword. Tomcat should scan this directory every 10 seconds looking for modifications and if it finds them it will restart the service. This usually takes a few minutes.If you do not see a context.xml file in ${TOMCAT_HOME}/conf/Catalina/localhost/ look in ${TOMCAT_HOME}/webapps/MirrorSync/META-INF for a context.xml file and then copy it from there into ${TOMCAT_HOME}/conf/Catalina/localhost/ , rename it MirrorSync.xml, and then edit it and add values for adminUsername and adminPassword

If desired, configure Apache to forward requests on port 80 to Tomcat, using a ProxyPass directive. Otherwise, just access MirrorSync on the Tomcat port (typically 8080).

<Loader className="org.apache.catalina.loader.VirtualWebappLoader" virtualClasspath="/Library/360Works/SyncData4_MirrorSync/*.jar;C:\Program Files\360Works\SyncData4\MirrorSync\*.jar;${360directory}/SyncData4_MS/Extensions/*.jar" /> </pre>

Error from server: user lacks privilege or object not found: SYNCCLIENT in statement [INSERT INTO SyncClient(timestamp, description, device_id, clone) VALUES (?,?,?,?)]

Restarting the MirrorSync application through the 360Work Admin.jar file will resolve this issue.

There is a duplicate ID in node <spoke or hub> in <layout Name> on <device name>. Duplicate ID: <primary key of duplicate>

This error message indicates that there is more than one primary key on the specified device and table. Duplicates will need to be removed before this device can complete a sync. To prevent duplicates in the future, we highly recommend that you 1) on your auto-enter calc (if you use one), UNCHECK the box that says 'Do not replace existing value of field (if any), and 2) change the validation on the primary key in the hub file in the specified table to "always" instead of "only during data entry". After doing so, we also highly recommend that you distribute new offline spoke files.
SetValidation.png

Personal tools
Namespaces

Variants
Actions
Plug-in Products
Other Products
Navigation
Toolbox