Develop a Haplo plugin

To develop a Haplo plugin, you run the plugin tool on your local computer. As you make changes to files, it automatically uploads them to the server where you can test your plugin.

Install the plugin tool

Follow the instructions to install the plugin tool for Windows or UNIX-like OSes such as Mac OS X or Linux.

Note the requirement to make sure the JRuby bin directory is in your PATH before running the plugin tool.

Create working directory and copy server certificate

The plugin tool is strict about only connecting to servers with SSL certificates it can verify. We need it to tell it to trust our development server’s certificate.

On your local computer, create a directory: (you don’t have to use this exact name)

mkdir ~/haplo-plugins
cd ~/haplo-plugins

Then copy the ~/haplo-dev-support/certificates/server.crt file into this directory as server.local.crt

Authorise with your development server

After following the build instructions, you will be accessing your application at a URL like:


cd to an empty directory, then, taking the hostname and port from this URL, authorise the plugin tool:

cd ~/haplo-plugins
haplo-plugin auth test.your-computer.local:8443

IMPORTANT: Change the hostname in the command above.

Follow the instructions to complete the authentication. On Mac OS X, your browser will open automatically.

Create a plugin

Create an empty plugin with the plugin tool:

haplo-plugin -p your_test_plugin new

Upload the plugin to your development server

Use a similar command (without the new) to automatically upload the plugin as you develop it:

haplo-plugin -p your_test_plugin

The plugin tool watches for changes you make to the plugin files and immediately uploads them.

See it working

Visit the /do/your-test-plugin/example path on your development server, for example


The test plugin will respond to this path, displaying the example template at your_test_plugin/template/example.html — try editing this file and refreshing the page in your browser.

Was it slow to upload the change?

If it took more than a second or so to upload the file, your computer might be trying IPv6 first. Run the plugin tool like this:

env _JAVA_OPTIONS="" haplo-plugin -p your_test_plugin

and it should be much quicker to respond.

Write your plugin

Use the Haplo plugin API documentation to develop your plugin.