Main Page | About | Installing the server | Installing the client | Using the server | Using the client |

About Butler

There are two parts to Butler: butler (lower case b) is a web app server companion to the desktop program Pooter; Butler, (capital B) is a Pooter module and client program to the server.

The server runs in a java app server, either on an internet connected machine or on a local network. It should be OS independant, but at the moment only the tomcat app server is supported. Contact me if you'd like to use it with an alternative to tomcat. It displays your Calendar, Contacts and Notes data in a browser. It also provides an easy way to sync your data between two machines on the same network and can also provide help monitoring the performance of the server machine. It bundles several additional technologies that it depends on, notably the stripes web framework, the groovy programming language and the jquery javascript library.

The client archives your data into a zip file, authenticates with the server and uploads. It can also download the archive and extract it to update your local data files.

Installing the server

Download and decompress the zip archive and copy the butler.war file to the tomcat webapps directory. If you're testing on the local machine with a standard tomcat setup, a login page is displayed at http://localhost:8080/butler. If you installed earlier versions of butler any config directory in your tomcat install (.butler or butler) must be removed first. Note that although the browsable pages can be accessed over https provided the web app server settings accomodate this, http access must be offered for the REST interfaces to function.

Installing the client

Copy the Butler.jar file into your Pooter module directory and restart Pooter. If you installed an earlier version (prior to 2.0) you must delete first delete the butler.cfg file in the Pooter data directory. Settings in the Preference tab are those needed to communicate with a server running on the local machine with the default login credentials.

Using the server

The default credentials are Login Name admin and Password password; once you login for the first time you will be taken to the config page. If you're running over the public internet you should change these and also reflect these changes in the client program. The default page setting determines which of the five pages you see after logging in; you'll want to change this setting from config to one of monitor, calendar, contacts or notes.

The last three of these need little further explanation; butler reads the appropriate xml file and transforms it into html for display. In the case of the notes page, this display is identical to that created by the export option in Pooter's Notes module. The navigation bar at the top of the displays enables easy switching between the pages.

The default monitor page displays some information about the JVM and the app server, which currently must be a version of tomcat. It also explains how the monitoring information can be extended by creating a monitor.txt file on the server. Each line of this file should contain a single OS specific command, which butler will then execute and add its output when the page is reloaded. The location of the home directory is also displayed, it's here that the server creates its rotated log files.

In addition to the browsable pages already mentioned, butler offers REST style interfaces which the client Butler accesses to upload and download the pooter.zip archive. The upload interface will only accept a correctly named file. The POST request is only checked for the authorization parameters after the file has been received; if these are not correct, the file is deleted. If this results from incorrect configuration of your own Butler module client, it will have displayed an explanatory response from the server and you should check that details on butler's config page and Butler's preference tab are identical. The download interface will not offer the file unless authorization details in the GET request are correct.

The butler.log files in the home directory will largely contain info messages about access, file transfers and page views. Any warn lines are probably a result of unauthorized access attempts, either at the login page or to the REST interfaces. If these cannot be explained by typos or mistakes in configuration, you may want to consider some action against the offending ip addresses. As with any web-based service on a public network, it is good practise to monitor these logs; I suggest logwitch for help with this.

Using the client

There are three configuration options; the URL of server that you are going to exchange data with which must be running the butler web app, the server Login Name and the server Password. The protocol http must be specified as part of the server's url; https is not supported. The default settings are good for initial testing, with a tomcat instance running butler (the web app) on port 8080 of the local machine. Once you deploy the web app on a server, the url will have to be changed to suit. The login name and password must be changed for security reason both on the butler web app and the Butler module and they must continue to match.


Assuming you have connectivity with the running web app, press to create and send an archive of files to the server and to download the same archive from the server and overwrite existing calendar, contacts and notes data.

The server's http response code is displayed; generally a 200 is an indication of success unless the authorization settings are out of sync. A server response message is also displayed, which should make the situation clear.

If an upload is successful, the zip archive created on the desktop machine is immediately unzipped on the server and the information it displays is updated. Before attempting a download any existing archive is backed up to pooter-old.zip. Thus if you mistakenly overwrite more current data files, copies of the originals can be recovered.