Labs Documentation

“That brain of mine is something more than merely mortal; as time will show.” ― Ada Lovelace

Getting Started

This page contains documention for Lucidwork's Labs, which has been designed to enable quick evalution of Lucidwork Fusion and its various applications. Documentation for Lucidworks Fusion is located here.

The Lucidworks Streams Repo on Github contains additional code, scripts, instructions and video guides to help you get started using Fusion quickly.

If you are looking to download the Fusion binary, please visit the Fusion Download page.

Github Authentication

Lucidworks Labs uses your Github account for authentication. The first time you navigate to any of the instance pages hosted on the streams.lucidworks.com subdomain, you will be redirected to Github and prompted for read permissions on your Github user profile.

To authenticate now, click on the Launch Instance button in the next section.

Quickstart an Instance

Lucidworks Labs allows you to launch demo Fusion instances with a single click. Try it now:

Update Your Profile

Your Lucidworks Labs account settings may be updated by navigating to the Account Settings page.

Two Factor Authentication

To enable 2FA, click on the on/off slider at the top of your setting page and then use Google Authenticator to scan the QR code on the screen.

Unlink Account

To revoke the Lucidworks Labs application from your Github account, navigate to your Github Applications list and click on the revoke button next to the Lucidworks Labs application.

Instances

Instances may be created directly from your instances page, by visiting the various application templates on the Labs main page or using the APIs below. Once a Fusion instance has been created for you, the Fusion admin UI will be accessable from the instance's IP address and a set of credentials created for the instance.

A sample URI format used to access the Fusion admin UI:

http://35.185.228.240:8764/admin/login

Creating & Naming

To create a Fusion instance from your instances page, click on the Create Instance button and then select a Fusion template to use to start the instance. The time for startup and provisioning takes about 5-8 minutes, but sometimes can be instant if there are hotstarts available to assign.

If you are looking to start an empty, vanilla instance of Fusion use the Fusion 4.1.2 template.

To name an instance to something more useful, navigate to its detail page and then click on the name at the top. Type in a new name and then hit enter to save.

To revert the instance name to the one used at provisioning time, delete the entire name and hit enter.

Credentials & Admin UI

Once a Fusion instance is running, the credentials to login to the instance will be shown, along with the IP address of the instance.

You may access Fusion's admin interface for the instance by using the Click to Login button. You'll login with the credentials provided above, which is located on the instance detail page.

Timers

Fusion instances started on Labs have both run and life timers. If an instance's run timer runs out, it will be stopped and halted. If an instance's life timer reaches zero, it will be permanently deleted regardless of whether or not it is running.

Note on Preemption

Instances may be occasionally preempted and stopped before their run timer expires. If one of your instances is stopped early, simply start it again by clicking on the start button.

Deletion

Once you are finished with an instance, you may delete it from your list of instances by clicking on its button.

You may also delete the instance from its detail view. To delete an instance, click on the Delete Instance button at the bottom of the page and then click Delete Instance again in the confirmation dialog that pops up.

Applications

Fusion applications combine configuration specific parameters with an optional user interface. Applications can be a simple as data source using a web connector with a few start links.

Depending on complexity, Fusion applications may or may not include an application link once the instance is running. When a Fusion application supports it, a link to the application's UI will become available from the instance detail page:

Templates

Application templates are managed by Lucidworks. Templates include an application zip file and a simple installation script which configures the instance with the application and any required data and or setup.

You may view the example application templates on Github.

A complete list of templates and their accompanying instructions and/or repositories are available over on the Labs index page.

Starting

To start a Fusion application instance, navigate to the Labs index page and click on the the application you'd like to start. Once the application detail page loads, click on the Start Instance button to start the application's instance.

Starting Stopped Instances

To start a stopped/preempted Fusion instance, navigate to the instances page and click on the the button next to the instance you'd like to start. You can also start a stopped instance from its detail view.

At this time there is no feature to allow for the restart of an already running instance.

Application Programming Interfaces

Lucidworks Labs provides a few basic API methods to start, monitor and access your instances programmatically.

API calls are made to the following subdomain:

streams.lucidworks.com

API Tokens

API tokens may be obtained by navigating to your settings page and then clicking on the Generate API Token button.

Status Methods

API Status

Status of the system running the API may be retrieved by making a GET request to the endpoint:

streams.lucidworks.com/api/status

This method takes one parameter:

  • token=<dev_token> - a developer token
curl https://streams.lucidworks.com/api/status?token=qnSNLUQF8YzRjiizDr8J0Ba8z2FBXtfTbYByGoDHsWsXhMwpFLvlUyg7ASFvo13a
{ 
  'response': "ok",
  'result': {
    'message': "system is operating normally",
    'starts_last_five_minutes': 2,
    'confidence': 0.5
  }
}

Template Methods

Template streams are used to launch a specific application running on Fusion.

Calls to the template endpoints require a token parameter be included.

List

A list of templates is returned by making a GET request to the endpoint:

streams.lucidworks.com/api/template/list

This method takes one parameter:

  • token=<dev_token> - a developer token
curl https://streams.lucidworks.com/api/template/list?token=qnSNLUQF8YzRjiizDr8J0Ba8z2FBXtfTbYByGoDHsWsXhMwpFLvlUyg7ASFvo13a
{ 
  [
    {
      "description": "A starter template for Fusion 4.0.2.",
      "name": "Fusion Starter 4.0.2",
      "sid": "starter",
      "api_stub": "/api/template/starter"
    },
    {
      "description": "May I help you?",
      "name": "Lou for Fusion 4.1.1",
      "sid": "lou",
      "api_stub": "/api/template/lou"
    }
  ]
}

Template

Template information may be retrieved by making a GET request to the endpoint:

streams.lucidworks.com/api/template/<template-id>

This method takes one parameter:

  • token=<dev_token> - a developer token
curl https://streams.lucidworks.com/api/template/lou?token=qnSNLUQF8YzRjiizDr8J0Ba8z2FBXtfTbYByGoDHsWsXhMwpFLvlUyg7ASFvo13a
{
  "created": "2018-08-17 17:37:29.827000",
  "updated": "2018-08-17 17:37:29.827000",
  "sid": "lou",
  "name": "Lou for Fusion 4.1.1",
  "description": "May I help you?",
  "distro": "lou-buttons.tgz",
  "fusion_version": "4.1.1",
  "github_repo": "",
  "app_stub": ":8764/webapps/lou-demo/",
  "labs_link": "https://lucidworks.com/labs/apps/lou"
}

Instance Methods

Calls to the instance endpoints require a token parameter be included.

List

A list of instances which the token controls can be retrieved by making a GET request to the endpoint:

streams.lucidworks.com/api/instance/list

This method takes one parameter:

  • token=<dev_token> - a developer token
curl https://streams.lucidworks.com/api/instance/list?token=qnSNLUQF8YzRjiizDr8J0Ba8z2FBXtfTbYByGoDHsWsXhMwpFLvlUyg7ASFvo13a"
{ 
  [
    {
      'name': "button-lou-8uvx1b",
      "status": "PROVISIONING",
      'status_stub': "/api/instance/button-lou-8uvx1b"
    },
    {
      "name": "button-activate-ja9w1c",
      "status": "RUNNING",
      "api_stub": "/api/instance/button-activate-ja9w1c"
    }
  ]
}

Info

Instance info may be retrieved by making a GET request to the endpoint:

streams.lucidworks.com/api/instance/<instance-name>

This method takes one parameter:

  • token=<dev_token> - a developer token
curl https://streams.lucidworks.com/api/instance/button-activate-8uvx1b?token=qnSNLUQF8YzRjiizDr8J0Ba8z2FBXtfTbYByGoDHsWsXhMwpFLvlUyg7ASFvo13a
{ 
  "created": "2019-01-02 00:54:02.610331",
  "updated": "2019-01-02 01:07:05.034839",
  "started": "2019-01-02 00:54:02.610158",
  "expires": "2019-01-09 00:54:02.610139",
  "sid": "activate",
  "name": "button-activate-ja9w1c",
  "topic": "ai",
  "region": "any",
  "preemptible": True,
  "ip": "35.230.80.39",
  "admin_link": "http://35.230.80.39:8764",
  "app_link": "http://35.230.80.39:8764/webapps/Lucidworks_Search_UI/",
  "password": "69nm5pxgaj56",
  "status": "RUNNING",
  "username": "kordless",
  "template": "activate"
}

Create

Instances may be created and started by making a POST request to the Stream endpoint:

streams.lucidworks.com/api/stream/<template-name>

This method takes several parameters:

  • token=<dev_token> - a developer token
  • preemptible=<false|0> - request non-preemptible instance
  • topic=<topic> - topic of interest matching [a-z0-9]
  • region=<region> - region by integer in which to start instance

Integer values for Google regions:

  • 0 - us-central1
  • 1 - us-west1
  • 2 - us-west2
  • 3 - us-east4
  • 4 - us-east1
  • 5 - europe-west2
  • 6 - asia-east2

This method requires the Content-length header be set to 0 in the request.

curl -X POST \
-d 'Content-length: 0' \
"https://streams.lucidworks.com/api/stream/starter41?token=qnSNLUQF8YzRjiizDr8J0Ba8z2FBXtfTbYByGoDHsWsXhMwpFLvlUyg7ASFvo13a&preemptible=0&topic=space"
{ 
  "created": "2019-01-02 01:10:47.578490",
  "updated": "2019-01-02 01:10:47.578501",
  "started": "2019-01-02 01:10:47.578179",
  "expires": "2019-01-09 01:10:47.578157",
  "sid": "lou",
  "name": "button-lou-80543c",
  "topic": "space",
  "region": "any",
  "preemptible": False,
  "ip": "None",
  "admin_link": "None",
  "app_link": "None",
  "password": "6b71nhejs463",
  "status": "PROVISIONING",
  "username": "kordless",
  "template": "lou"
}

Start

Instances with status TERMINATED were preempted and may be restarted by making a GET request to the endpoint:

streams.lucidworks.com/api/instance/<instance-name>/start

This method takes one parameter:

  • token=<dev_token> - a developer token
curl https://streams.lucidworks.com/api/instance/button-starter41-8uvx/start?token=qnSNLUQF8YzRjiizDr8J0Ba8z2FBXtfTbYByGoDHsWsXhMwpFLvlUyg7ASFvo13a
{
  "created": "2018-12-14 01:51:29.417217",
  "updated": "2018-12-17 23:33:41.297202",
  "started": "2018-12-17 23:33:41.293804",
  "expires": "2018-12-21 01:51:29.416775",
  "sid": "starter41",
  "name": "button-lou-ehhd2a",
  "topic": "ai",
  "region": "any",
  "preemptible": True,
  "ip": "None",
  "admin_link": "None",
  "app_link": "None",
  "username": "admin",
  "password": "ntamgl2afdsp",
  "status": "PROVISIONING",
  "username": "kordless",
  "template": "starter41"
}

Status

The status of an instance may be updated from itself by using the instance's password. Instances status update is performed uising a GET on the status endpoint:

streams.lucidworks.com/api/instance/<instance-name>/status

This method takes two parameters:

  • password=<instance_passwords> - the instance password
  • status=<instance_status_string> - one status of PROVISIONING, STAGING, CONFIGURING, RUNNING, STOPPING, TERMINATED
curl https://streams.lucidworks.com/api/instance/button-starter41-8uvx/status?password=ntamgl2afdsp&status=RUNNING
  "created": "2018-12-14 01:51:29.417217",
  "updated": "2018-12-17 23:33:41.297202",
  "started": "2018-12-17 23:33:41.293804",
  "expires": "2018-12-21 01:51:29.416775",
  "sid": "starter41",
  "name": "button-starter41-ehhd2a",
  "topic": "ai",
  "region": "any",
  "preemptible": True,
  "ip": "None",
  "admin_link": "None",
  "app_link": "None",
  "username": "admin",
  "password": "ntamgl2afdsp",
  "status": "RUNNING",
  "username": "kordless",
  "template": "starter41"
}

More API methods coming soon!