Launcher Service Interface

When you run the Desktop Launcher, you may add one or more launcher services that provide connection settings for instances. You may use launcher services as an alternative to manually entering the settings for each instance.

A launcher service is an external web service that returns a list of existing Platform processes to the desktop launcher. The launcher will only know the URL to the service and uses this information to retrieve the list of instances via HTTP GET.

Launcher services are useful in a dynamic environment, e g cloud deployments, where platforms are expected to change IP addresses and ports often. But it can also be useful in a static environments since it reduces the need for manual configuration.

Response Format

In order for the Desktop Launcher to correct parse the response from launcher service, it must adhere to the following format.

mz.<unique identifier>.<attribute>=<value>

The unique identifier is used for grouping attributes of a  instance. You may use e g a UUID for this purpose. 

The following attributes are available:

AttributeDescription
urlThe URL Platform Container host, e g https://example.com. This attribute is mandatory. 
nameAn arbitrary name of the instance that will be displayed in the Desktop Launcher. This is attribute is mandatory.
overrides.pico.rcp.platform.port
When the Desktop connects to the Platform it retrieves the value of the property pico.rcp.platform port from the STR. If the Desktop will run on a different network than the Platform, you may need to include this attribute in order to override the retrieved value with an external port number. This attribute is optional.

Example - GET request with curl and response from launcher service

$ curl examplehost.com
mz.139808b7-b9ad-4434-9dbd-5233188c6b2c.url=http://10.10.46.1:9000
mz.139808b7-b9ad-4434-9dbd-5233188c6b2c.name=test-environment
mz.a01884d2-cd76-4080-857c-db1d42d8ecdc.url=https://example.com:32768
mz.a01884d2-cd76-4080-857c-db1d42d8ecdc.name=prod-environment
mz.a01884d2-cd76-4080-857c-db1d42d8ecdc.overrides.pico.rcp.platform.port=32770

Example Implementation

Below is an example of a launcher service implementation written in Python. The script will return the contents of the file that is specified in the first argument.

#!/usr/bin/env python
import sys
from BaseHTTPServer import BaseHTTPRequestHandler, HTTPServer

class LauncherService(BaseHTTPRequestHandler):
    def do_GET(self):
        try:
            f = open(sys.argv[1], 'r')
            self.send_response(200)
            self.send_header('Content-type', 'text/plain')
            self.end_headers()
            self.wfile.write(f.read())
            f.close()
            return
        except IOError:
            self.send_error(404, 'file not found')

def run():
    server_address = ('0.0.0.0', 80)
    httpd = HTTPServer(server_address, LauncherService)
    print('http server is running...')
    httpd.serve_forever()

if __name__ == '__main__':
    run()

To run the script:

  1. Install python 2x.

  2. Save the code above in a file named launcher_service.py.

  3. Create a file that contains the instance information. For further information, see Response Format above.

  4. Set executable permissions on the file:

    $ chmod +x launcher_service.py
  5. Run the script:

    $ ./launcher_service.py <file>

    You may now add the service in the Desktop Launcher. For further information, see 1.1.1 Desktop Launcher in the Desktop User's Guide.