Difference between revisions of "LingoBot Installation"

From Lingoport Wiki
Jump to: navigation, search
(Configuration Overview)
(Detailed Steps)
(46 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Configuration Overview ==
+
== Overview ==
 
To start the lingobot service, some configuration is needed first.
 
To start the lingobot service, some configuration is needed first.
 
# A lingobot user needs to be added and configured in Jenkins
 
# A lingobot user needs to be added and configured in Jenkins
 
# A lingobot user needs to be added to the Dashboard
 
# A lingobot user needs to be added to the Dashboard
# A bot needs to be created on your chosen adapter (Slack or Flowdoc)
+
# A bot needs to be created on your chosen adapter (Slack, Spark, or Flowdock)
# All the infomation about these users needs to be encapsulated in the configuration file to start the lingobot service on the globalization server.
+
# All the infomation about these users needs to be encapsulated in the configuration file to start the lingobot service on the globalization server.
  +
# Start the lingoport.lingobot service on server.
   
  +
== Configuration Settings: lingobot_config.sh ==
 
Configuration for LingoBot is intended to be as simple as possible. All that is needed for this friendly chatbot to be ready for use are a few environment variables, all of which should be set in LingoBot's configuration file. The config file can be found in LingoBot's home directory under the "config" sub-directory. By default, LingoBot home is set to:
 
Configuration for LingoBot is intended to be as simple as possible. All that is needed for this friendly chatbot to be ready for use are a few environment variables, all of which should be set in LingoBot's configuration file. The config file can be found in LingoBot's home directory under the "config" sub-directory. By default, LingoBot home is set to:
   
/var/lib/jenkins/lingoport/lingobot-X.Y
+
/var/lib/jenkins/lingoport/lingobot-<x.y>
   
Below is a template of the configuration file's contents. The file itself is called `lingobot_config.sh`
+
Below is a template of the configuration file's contents for a Slack configuration. The file itself is called '''lingobot_config.sh''' and is located in <code>/var/lib/jenkins/lingoport/lingobot-<x.y>/config</code>
 
# REQUIRED CONFIG VARIABLES
 
# REQUIRED CONFIG VARIABLES
 
export LINGOBOT_JENKINS_USERNAME=lingobot # default: lingobot
 
export LINGOBOT_JENKINS_USERNAME=lingobot # default: lingobot
export LINGOBOT_JENKINS_TOKEN=11d018ccbbea23a25cc443c8379aa3beda
+
export LINGOBOT_JENKINS_TOKEN=
export LINGOBOT_JENKINS_DOMAIN=http://acme.company.com/jenkins
+
export LINGOBOT_JENKINS_DOMAIN=
export LINGOBOT_DASHBOARD_TOKEN=b7b190943d79516218b43775975a73f85eb6c67d
+
export LINGOBOT_DASHBOARD_TOKEN=
 
export JENKINS_HOME=/var/lib/jenkins # default: /var/lib/jenkins
 
export JENKINS_HOME=/var/lib/jenkins # default: /var/lib/jenkins
 
export PORT=5001 # default: 5001
 
export PORT=5001 # default: 5001
export LINGOBOT_ADAPTER=slack # Possible values: 'flowdock', 'slack', (coming soon)'sparkwebhook'
+
export LINGOBOT_ADAPTER= # Possible values: 'botframework'(for Microsoft Teams)'flowdock', 'slack', (coming soon)'sparkwebhook'
 
 
# OPTIONAL CONFIG VARIABLES
 
# OPTIONAL CONFIG VARIABLES
 
export LINGOBOT_JENKINS_PORT=8080 # default: 8080
 
export LINGOBOT_JENKINS_PORT=8080 # default: 8080
export LINGOBOT_DASHBOARD_URL=http://acme.company.com # default: same as jenkins domain
+
export LINGOBOT_DASHBOARD_URL=$LINGOBOT_JENKINS_DOMAIN # default: same as jenkins domain
 
export LINGOBOT_DASHBOARD_PORT=9000 # default: 9000
 
export LINGOBOT_DASHBOARD_PORT=9000 # default: 9000
 
export LINGOBOT_NAME=LingoBot # default: LingoBot. This is the name to which lingobot will respond.
 
export LINGOBOT_NAME=LingoBot # default: LingoBot. This is the name to which lingobot will respond.
 
 
# API TOKENS FOR ADAPTERS
 
# API TOKENS FOR ADAPTERS
 
export HUBOT_FLOWDOCK_API_TOKEN=
 
export HUBOT_FLOWDOCK_API_TOKEN=
export HUBOT_SLACK_TOKEN=xoxb-261328978756-rOmdLfqPg45U1Nm6iSczcetv
+
export HUBOT_SLACK_TOKEN=
 
export CISCOSPARK_ACCESS_TOKEN=
 
export CISCOSPARK_ACCESS_TOKEN=
 
export CISCOSPARK_SECRET=
 
export CISCOSPARK_SECRET=
export LINGOBOT_API_TOKEN= #this can be left blank, it will be filled in by the installation
+
export LINGOBOT_API_TOKEN=
  +
export BOTBUILDER_APP_ID=
 
  +
export BOTBUILDER_APP_PASSWORD=
 
# OPTIONAL CONFIGS FOR LINGOBOT API
 
# OPTIONAL CONFIGS FOR LINGOBOT API
  +
export LINGOBOT_API_STATUS_INTERVAL_SECONDS_ARRAY= # example: 15,30,60,150,300 (note: the last interval will continue to be used until the timeout is reached
# If these are unset, the default values are used
 
  +
export LINGOBOT_API_STATUS_TIMEOUT_MINUTES= # identifies how long a JVM request will wait for a response. The default is 2 minutes
export LINGOBOT_API_STATUS_INTERVAL_SECONDS_ARRAY= # example: 15,30,60,150,300 (note: the last interval will continue to be used until the timeout is reached
 
export LINGOBOT_API_STATUS_TIMEOUT_MINUTES= # identifies how long a JVM request will wait for a response. example: 60
 
 
export LINGOBOT_API_STATUS_MINUTES_TO_KEEP_MAXIMUM= # identifies the maximum number of minutes a response message will be retained on the server
 
export LINGOBOT_API_STATUS_MINUTES_TO_KEEP_MAXIMUM= # identifies the maximum number of minutes a response message will be retained on the server
  +
# BETA
  +
export LINGOBOT_USE_NLP=false
   
 
Next, you will find instructions on how to obtain all of the necessary values to properly fill out this configuration file.
 
   
== LingoBot Jenkins Setup ==
+
=== Set the Jenkins and Dashboard Locations ===
The first step in the configuration process is to create a Jenkins user which LingoBot can have access to. This is the primary mechanism that LingoBot uses to access the Lingoport product suite, so it is very important that the configuration is done correctly. Please follow these instructions closely for the best results!
 
   
  +
To get started, set the <code>LINGOBOT_JENKINS_DOMAIN</code> and <code>LINGOBOT_DASHBOARD_URL</code> to the URL values for Jenkins and the Dashboard.
* Navigate to your Lingoport Jenkins instance in a web browser.
 
  +
export LINGOBOT_JENKINS_DOMAIN=<nowiki>http://acme.company.com/jenkins</nowiki>
* If an admin account has been configured, log in as the admin (otherwise no login is necessary) and click on the "'''Manage Jenkins'''" menu item on the left hand side of the window. (indicated by a small gear icon).
 
  +
export LINGOBOT_DASHBOARD_URL=<nowiki>http://acme.company.com</nowiki>
** If you don't see this menu item, this means the current account does not have administrative privileges.
 
* Click on "'''Configure Global Security'''", and on this page make sure that the following boxes are checked:
 
** '''Enable''' security
 
** '''Jenkins' own user database'''
 
** One of the authorization methods (preferably "'''Matrix-based security'''").
 
*** IMPORTANT: If Matrix-based security is selected and no users have been configured yet, make sure that "Anonymous" has full privileges (all boxes next to Anonymous MUST be checked).
 
* Once this is done, click "'''Save'''" and return to the previous "Manage Jenkins" page.
 
* Scroll down and click on "'''Manage Users'''", and on this page, select "'''Create User'''" from the left hand menu and fill out the form with the following information:
 
** Username: "lingobot"
 
** Password: Choose a secure password.
 
** Confirm Password: Repeat your previous entry
 
** Full Name: "LingoBot"
 
** Email: "lingobot@lingoport.com"
 
* Click "'''Create User'''"
 
* Return once again to the "'''Configure Global Security'''" page ('''Manage Jenkins > Configure Global Security''') and scroll down to the "'''Authorization'''" section.
 
* In the "'''User/group to add'''" field under Matrix-based security, enter "lingobot" and click add. This should result in lingobot being added as a row in the security matrix above.
 
* Enable the following security permissions for the lingobot account:
 
** Under "Overall"
 
*** Administer
 
*** Read
 
** Under "Job"
 
*** Build
 
*** Cancel
 
*** Configure
 
*** Create
 
*** Delete
 
*** Read
 
*** Workspace
 
** Under "View"
 
*** Configure
 
*** Read
 
* Once those boxes are checked, click "'''Save'''" and log out if you were previously logged in.
 
* Log in as the newly created "lingobot" account using the password you just created.
 
* Once logged in, in the top-right hand corner of the window, click on the account name ('''LingoBot''')
 
* Select "'''Configure'''" from the menu on the left (or from the dropdown menu below the account-name button)
 
* On this page there should be a section called "'''API Token'''" and a corresponding button labeled "'''Show API Token...'''" or '''Add new Token'''. Click this button.
 
* Copy the API Token that is displayed and paste it into the LingoBot configuration file next to the '''LINGOBOT_JENKINS_TOKEN''' variable declaration.
 
   
  +
Leave the port values as they are defaulted.
Example:
 
  +
export LINGOBOT_JENKINS_PORT=8080
export LINGOBOT_JENKINS_TOKEN=1234567890abcdef14d4f2789bea4f22a
 
  +
export LINGOBOT_DASHBOARD_PORT=9000
   
  +
If you have an a system that uses the port numbers so that the Jenkins URL is something like <nowiki>http://acme.company.com:8080</nowiki> and the Dashboard is <nowiki>http://acme.company.com:9000</nowiki>, then just use the URL before the port value.
You're done with this part! Just make sure that the LINGOBOT_JENKINS_USERNAME is set correctly to the username you chose when creating LingoBot's Jenkins account (by default it is set to "lingobot")
 
  +
export LINGOBOT_JENKINS_DOMAIN=<nowiki>http://acme.company.com</nowiki>
  +
export LINGOBOT_DASHBOARD_URL=<nowiki>http://acme.company.com</nowiki>
  +
but make sure the port values are set.
  +
export LINGOBOT_JENKINS_PORT=8080
  +
export LINGOBOT_DASHBOARD_PORT=9000
   
  +
=== Setting or changing the Optional Configurations ===
== LingoBot Dashboard Setup ==
 
The next step in the configuration process is to create a Dashboard user account for LingoBot. This step is also crucial to the functionality of the bot itself, so it is very important that these steps are followed carefully.
 
   
  +
The optional configuration settings don't need to be set to complete the installation of LingoBot.
* Navigate to your Lingoport Dashboard instance in a web browser.
 
* Log in as the administrator account.
 
** The default credentials are username: "admin", password: "admin".
 
* From the top navigation bar, select the "'''Administration'''" tab.
 
* The following page should have a drop-down menu near the top of the screen labeled "'''Security'''"
 
** From this drop-down menu, select "'''Users'''"
 
* On the right side of this page, click "'''Create User'''" and a form overlay should appear. Fill this form with the following information:
 
** Login: "lingobot"
 
** Name: "LingoBot"
 
** Email: "lingobot@lingoport.com"
 
** Password: Choose a secure password.
 
* Click "'''Create'''", and a new user row should appear on the "'''Users'''" page.
 
* Under the "'''GROUPS'''" column, click the small blue menu icon on the row corresponding to the newly created user account. An overlay should appear.
 
** In this overlay, select the "'''Deselected'''" tab.
 
** Check the box labeled "'''sonar-administrators'''", then click done.
 
* Under the "'''TOKENS'''" column, click the small blue menu icon on the row corresponding to the newly created user account. Another overlay should appear.
 
** In the "'''Generate Tokens'''" field, enter a token name (this can be anything. i.e. "lingobot") and click the "'''Generate'''" button.
 
** Click the "Copy" button that appears, or select and copy the API token that has appeared.
 
* Paste the API token into the LingoBot configuration file next to the '''LINGOBOT_DASHBOARD_TOKEN''' variable declaration.
 
   
  +
To make changes see [[LingoBot_CLI#Server_Modifications|LingoBot CLI Server Modifications]]
Example:
 
export LINGOBOT_DASHBOARD_TOKEN=1234567890abcdef14d4f2789bea4f22a
 
   
  +
# OPTIONAL CONFIGS FOR LINGOBOT API
Once this is complete, you're done configuring this part of LingoBot! The remaining configuration steps depend on which collaboration environment you will be using to communicate with LingoBot.
 
  +
# If these are unset, the default values are used
 
  +
export LINGOBOT_API_STATUS_INTERVAL_SECONDS_ARRAY= # example: 15,30,60,150,300 (note: the last interval will continue to be used until the timeout is reached
Skip to the collaboration environment you will be using:
 
  +
export LINGOBOT_API_STATUS_TIMEOUT_MINUTES= # identifies how long a JVM request will wait for a response. example: 60
* [http://wiki.lingoport.com/LingoBot_Installation#LingoBot_Slack_Setup Slack]
 
  +
export LINGOBOT_API_STATUS_MINUTES_TO_KEEP_MAXIMUM= # identifies the maximum number of minutes a response message will be retained on the server
* [http://wiki.lingoport.com/LingoBot_Installation#LingoBot_Flowdock_Setup CA Flowdock]
 
* [http://wiki.lingoport.com/LingoBot_Installation#LingoBot_Cisco_Spark_Setup Cisco Spark]
 
 
== LingoBot Slack Setup ==
 
This portion of the installation guide only applies if the collaboration environment you will be using is Slack. If you will be using either Flowdock or Cisco Spark, please skip to the corresponding setup instructions.
 
 
* Navigate to the [http://my.slack.com/services/new/bot Slack Custom Bot Creation] page, and log in as an account that is a part of your company's Slack organization.
 
* In the new bot username field, enter the name that you would like LingoBot to respond to.
 
** By default, we recommend simply calling it "'''lingobot'''", however you're welcome to name it whatever you would like.
 
** If you do choose to call it something other than "lingobot", make sure that you set the '''LINGOBOT_NAME''' variable in the configuration file to whatever name you chose.
 
*** Example: <code>export LINGOBOT_NAME=lingobot-123</code>
 
* Once you have decided on a name, click "'''Add Bot Integration'''" to continue to the next page.
 
* On this page, you can set a custom icon for the bot under the "'''Customize Icon'''" section. You can download the following icon and upload it, upload your own custom icon, or simply leave it blank.
 
[[File:Lingoport logo small.jpeg]]
 
* Once this is done, scroll down to the bottom of the page and click "'''Save Integration'''"
 
* Finally, copy the API Token that is provided near the top of the page and paste it into the LingoBot configuration file next to the HUBOT_SLACK_TOKEN variable declaration.
 
 
Example:
 
export HUBOT_SLACK_TOKEN=xoxb-1234567890000-aAbBcCdDeEfFgGtTfF
 
 
Furthermore, make sure the LINGOBOT_ADAPTER variable is set to "slack".
 
 
Example:
 
export LINGOBOT_ADAPTER=slack
 
 
Once this is complete, the bot is now configured and ready to be installed! Follow the instructions below on running the installation script to finish the installation process.
 
 
Skip to the next step: [http://wiki.lingoport.com/LingoBot_Installation#Running_The_Installation_Script Running The Installation Script]
 
 
== LingoBot CA Flowdock Setup ==
 
This portion of the installation guide only applies if the collaboration environment you will be using is CA Flowdock. If you will be using either Slack or Cisco Spark, please follow the corresponding setup instructions.
 
 
Setting up LingoBot to run on CA Flowdock is as simple as creating a new user account through which LingoBot will communicate. If you would rather not deal with the hassle of creating a new Flowdock user account, feel free to ask us to make one for your LingoBot instance. We will send you the API token needed for LingoBot's configuration file and you can simply invite the account to join your Flow once it is ready.
 
 
If you don't mind creating the account yourself, then simply follow these instructions to do so.
 
 
* First, you will need an email account with which you can create a Flowdock account. You can make one for free on [https://accounts.google.com/SignUp?hl=en-US Gmail] if need be.
 
* Once this is completed, navigate to the [https://www.flowdock.com/signup Flowdock Sign Up page] and click "Sign Up Using Google"
 
* When prompted, sign in using the Google account you created for LingoBot (alternatively, you can sign up using a non-google account by filling out the details manually).
 
* Once the account has been created, navigate to the [https://www.flowdock.com/account/edit Profile Editing Page] and set the following information:
 
** Name: Lingoport Chatbot
 
** Display Name: By default, we recommend simply calling it "lingobot", however you're welcome to name it whatever you would like.
 
*** If you do choose to call it something other than "lingobot", make sure that you set the LINGOBOT_NAME variable in the configuration file to whatever name you chose.
 
*** Example: <code>export LINGOBOT_NAME=lingobot-123</code>
 
** Avatar: You can download the following icon and upload it, upload your own custom icon, or simply leave it blank.
 
[[File:Lingoport logo small.jpeg]]
 
* Once this is done, scroll down and click "Update Profile"
 
* The final step is to navigate to the [https://www.flowdock.com/account/tokens API Tokens page]. Here you will find an API token labeled "Personal Api Token".
 
* Copy the API token and paste it into the LingoBot configuration file next to the HUBOT_FLOWDOCK_API_TOKEN variable declaration.
 
 
Example:
 
export HUBOT_FLOWDOCK_API_TOKEN=0a1b2c3d4e5f6g7a8b9c0d
 
 
Furthermore, make sure the LINGOBOT_ADAPTER variable is set to "flowdock".
 
 
Example:
 
export LINGOBOT_ADAPTER=flowdock
 
 
Once this is complete, the bot is now configured and ready to be installed! Follow the instructions below on running the installation script to finish the installation process.
 
 
Skip to the next step: [http://wiki.lingoport.com/LingoBot_Installation#Running_The_Installation_Script Running The Installation Script]
 
 
== LingoBot Cisco Spark Setup ==
 
This portion of the installation guide only applies if the collaboration environment you will be using is Cisco Spark. If you will be using either Slack or CA Flowdock, please follow the corresponding setup instructions.
 
 
Configuring LingoBot to communicate via Cisco Spark is a fairly straight forward process. All that is required is access to an account that has access to your organization's Cisco Spark.
 
 
=== Creating a Custom Bot ===
 
* The first step is to sign in to your Cisco Spark account on the [https://developer.ciscospark.com/# Developer Portal].
 
* Once signed in, navigate to the [https://developer.ciscospark.com/add-bot.html Custom Bot Creation page].
 
* On the bot creation page, fill in the form with the following information:
 
** Display Name: By default, we recommend simply calling it "lingobot", however you're welcome to name it whatever you would like.
 
*** If you do choose to call it something other than "lingobot", make sure that you set the LINGOBOT_NAME variable in the configuration file to whatever name you chose.
 
*** Example: <code>export LINGOBOT_NAME=lingobot-123</code>
 
** Bot Name: Ideally this should be the same as the display name, however due to the necessity that it be unique this can be just about anything. This will only be used to invite the bot to a chat room.
 
** Icon: Paste the following URL into the Icon field: '''http://i.imgur.com/3bzw0zp.jpg'''
 
* Once this is done, click "Add Bot". On the following page, you will find an API token. Click the "Copy" button next to it (or select and copy the token itself) then paste it into the LingoBot configuration file next to the CISCOSPARK_ACCESS_TOKEN variable declaration.
 
 
Example:
 
export CISCOSPARK_ACCESS_TOKEN=LDA5YjBiOTItMTAwOS00ODMxLTk4ZjEtYTQ4OGI4N2FjN2Y2MjVlM2QyNTUtYmM2
 
 
=== Creating a Webhook for LingoBot ===
 
* The final step is to create a webhook that LingoBot can receive message event notifications through. To do this, navigate to the [https://developer.ciscospark.com/endpoint-webhooks-post.html Spark Webhook Creation Page].
 
* Make sure that the "Test Mode" switch is turned ON. This will allow you to generate webhooks directly into your organization's account.
 
* Under the "Request Headers" section, fill in the following information:
 
** Authorization: "Bearer '''[YOUR BOT'S API TOKEN HERE]'''"
 
* In the "Request Parameters" section, fill in the the following information under the "Your values" column:
 
** name: This can be anything. i.e. "lingobot".
 
** targetURL: "'''[YOUR JENKINS INSTANCE URL HERE]''':5001/hubot/ciscospark/incoming"
 
** resource: "all"
 
** event: "all"
 
** secret: This can be just about anything, but ideally it is a random string of letters and numbers that it at least 32 characters long.
 
*** Whatever you chose for this must also be copied to the LingoBot configuration file, next to the CISCOSPARK_SECRET variable declaration.
 
Example:
 
export CISCOSPARK_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
 
* Once all of these values have been entered, click the "Run" button. You should see a response containing the webhook's information on the right.
 
 
Finally, make sure the LINGOBOT_ADAPTER variable is set to "sparkwebhook".
 
 
Example:
 
export LINGOBOT_ADAPTER=sparkwebhook
 
 
Once this is complete, the bot is now configured and ready to be installed! Follow the instructions below on running the installation script to finish the installation process.
 
 
== Running The Installation Script ==
 
=== With Sudo ===
 
This is the final step in the configuration process. If all goes well, your instance of LingoBot will be up and running once this step has been completed.
 
 
* On the command-line shell where you have been modifying the LingoBot configuration file, save and close the file.
 
* if you have been operating as the "jenkins" user, change users so that you are on an account that has root privileges (unrestricted access to the sudo command).
 
** Typically this will be either the "centos" account or the "ec2-user" account, depending on your installation.
 
** If you are unable to access an account with root privileges, skip to the "Without Sudo" section below.
 
* Once this is done, simply execute the install.sh script. This script can be found in LingoBot's home directory under the "lingobot_installer" sub directory.
 
 
Example:
 
/var/lib/jenkins/lingoport/lingobot-<x.y>/lingobot_installer/install.sh
 
 
If everything has been configured correctly, then this script will take only a few seconds to run. Otherwise, the output of the script will tell you which aspects of the bot need to be reconfigured.
 
If something needs to be changed, simply modify the LingoBot config file and rerun the install script until it reports a successful installation.
 
 
Once this is done, your instance of LingoBot will be up and running!
 
 
=== Without Sudo ===
 
If you are unable to access an account that has root privileges, the LingoBot installation script can be run as the "jenkins" user by including the '--nosudo' ('-n') flag.
 
 
Example:
 
/var/lib/jenkins/lingoport/lingobot-<x.y>/lingobot_installer/install.sh --nosudo
 
 
NOTE: if the no-sudo flag is included, the installer will neither configure nor start the LingoBot service.
 
To start the service manually, you must have access to root privileges. The following commands can be run to manually start the LingoBot service.
 
 
sudo cp /var/lib/jenkins/lingobot-1.0/service_files/lingoport-lingobot.service /etc/systemd/system/lingoport-lingobot.service
 
sudo systemctl enable lingoport-lingobot.service
 
sudo systemctl start lingoport-lingobot.service
 
 
Once this is done, your instance of LingoBot will be up and running!
 
 
== Installation Verification ==
 
A quick way to verify that the LingoBot service has successfully launched and can be accessed by your team, go to your collaboration environment and try sending a message to LingoBot. To do this, you may have to invite LingoBot to the room you are currently in.
 
 
Example:
 
@lingobot ping
 
 
if LingoBot responds with "PONG", then you have successfully launched LingoBot. Have Fun!
 
 
Verify that you see the correct projects:
 
@lingobot list projects
 
 
Check that the dashboard comes up. Select the link and make sure it shows the correct dashboard.
 
@lingobot show dashboard
 
   
== Troubleshooting ==
+
== Detailed Steps ==
  +
For step-by-step configuration, execute the following instructions:
=== I ran the install.sh script. I found that I had set some of the variables incorrectly. So, what now? ===
 
If the variables need to be modified:
 
* Stop the LingoBot service (for example <code>sudo systemctl stop lingoport-lingobot.service</code>, see above)
 
* edit the <code>lingobot_config.sh</code> configuration file
 
* Run the <code>install.sh</code> script (See above)
 
* Make sure the LingoBot service has started (for example <code>sudo systemctl status lingoport-lingobot.service</code>, see above)
 
   
  +
#[[Set Up Jenkins Lingobot User]]
== Running LingoBot on the CLI ==
 
  +
#[[LingoBot Dashboard Setup]]
TBD
 
  +
# [[Configure the Collaboration Environment]] or select the step below that corresponds your collaboration environment
  +
## [[Configure_the_Collaboration_Environment#LingoBot_Slack_Setup| Lingobot Slack Setup]]
  +
## [[Configure_the_Collaboration_Environment#LingoBot_MS_Teams_Setup| LingoBot MS Team Setup]]
  +
## [[Configure_the_Collaboration_Environment#LingoBot_CA_Flowdock_Setup| LingoBot CA Flowdock Setup]]
  +
## [[Configure_the_Collaboration_Environment#LingoBot_Cisco_Spark_Setup| LingoBot Cisco Spark Setup]]
  +
#[[Installing the Lingobot Service]]
  +
#[[Lingobot CLI verification]]

Revision as of 19:34, 5 December 2018

Overview

To start the lingobot service, some configuration is needed first.

  1. A lingobot user needs to be added and configured in Jenkins
  2. A lingobot user needs to be added to the Dashboard
  3. A bot needs to be created on your chosen adapter (Slack, Spark, or Flowdock)
  4. All the infomation about these users needs to be encapsulated in the configuration file to start the lingobot service on the globalization server.
  5. Start the lingoport.lingobot service on server.

Configuration Settings: lingobot_config.sh

Configuration for LingoBot is intended to be as simple as possible. All that is needed for this friendly chatbot to be ready for use are a few environment variables, all of which should be set in LingoBot's configuration file. The config file can be found in LingoBot's home directory under the "config" sub-directory. By default, LingoBot home is set to:

/var/lib/jenkins/lingoport/lingobot-<x.y>

Below is a template of the configuration file's contents for a Slack configuration. The file itself is called lingobot_config.sh and is located in /var/lib/jenkins/lingoport/lingobot-<x.y>/config

# REQUIRED CONFIG VARIABLES
export LINGOBOT_JENKINS_USERNAME=lingobot # default: lingobot
export LINGOBOT_JENKINS_TOKEN=
export LINGOBOT_JENKINS_DOMAIN=
export LINGOBOT_DASHBOARD_TOKEN=
export JENKINS_HOME=/var/lib/jenkins # default: /var/lib/jenkins
export PORT=5001 # default: 5001
export LINGOBOT_ADAPTER= # Possible values: 'botframework'(for Microsoft Teams)'flowdock', 'slack', (coming soon)'sparkwebhook'
# OPTIONAL CONFIG VARIABLES
export LINGOBOT_JENKINS_PORT=8080 # default: 8080
export LINGOBOT_DASHBOARD_URL=$LINGOBOT_JENKINS_DOMAIN # default: same as jenkins domain
export LINGOBOT_DASHBOARD_PORT=9000 # default: 9000
export LINGOBOT_NAME=LingoBot # default: LingoBot. This is the name to which lingobot will respond.
# API TOKENS FOR ADAPTERS
export HUBOT_FLOWDOCK_API_TOKEN=
export HUBOT_SLACK_TOKEN=
export CISCOSPARK_ACCESS_TOKEN=
export CISCOSPARK_SECRET=
export LINGOBOT_API_TOKEN=
export BOTBUILDER_APP_ID=
export BOTBUILDER_APP_PASSWORD=
# OPTIONAL CONFIGS FOR LINGOBOT API
export LINGOBOT_API_STATUS_INTERVAL_SECONDS_ARRAY= # example: 15,30,60,150,300 (note: the last interval will continue to be used until the timeout is reached
export LINGOBOT_API_STATUS_TIMEOUT_MINUTES= # identifies how long a JVM request will wait for a response. The default is 2 minutes
export LINGOBOT_API_STATUS_MINUTES_TO_KEEP_MAXIMUM= # identifies the maximum number of minutes a response message will be retained on the server
# BETA
export LINGOBOT_USE_NLP=false


Set the Jenkins and Dashboard Locations

To get started, set the LINGOBOT_JENKINS_DOMAIN and LINGOBOT_DASHBOARD_URL to the URL values for Jenkins and the Dashboard.

export LINGOBOT_JENKINS_DOMAIN=http://acme.company.com/jenkins
export LINGOBOT_DASHBOARD_URL=http://acme.company.com

Leave the port values as they are defaulted.

export LINGOBOT_JENKINS_PORT=8080
export LINGOBOT_DASHBOARD_PORT=9000

If you have an a system that uses the port numbers so that the Jenkins URL is something like http://acme.company.com:8080 and the Dashboard is http://acme.company.com:9000, then just use the URL before the port value.

export LINGOBOT_JENKINS_DOMAIN=http://acme.company.com
export LINGOBOT_DASHBOARD_URL=http://acme.company.com

but make sure the port values are set.

export LINGOBOT_JENKINS_PORT=8080
export LINGOBOT_DASHBOARD_PORT=9000

Setting or changing the Optional Configurations

The optional configuration settings don't need to be set to complete the installation of LingoBot.

To make changes see LingoBot CLI Server Modifications

# OPTIONAL CONFIGS FOR LINGOBOT API
# If these are unset, the default values are used
export LINGOBOT_API_STATUS_INTERVAL_SECONDS_ARRAY= # example: 15,30,60,150,300 (note: the last interval will continue to be used until the timeout    is reached
export LINGOBOT_API_STATUS_TIMEOUT_MINUTES= # identifies how long a JVM request will wait for a response. example: 60
export LINGOBOT_API_STATUS_MINUTES_TO_KEEP_MAXIMUM= # identifies the maximum number of minutes a response message will be retained on the server

Detailed Steps

For step-by-step configuration, execute the following instructions:

  1. Set Up Jenkins Lingobot User
  2. LingoBot Dashboard Setup
  3. Configure the Collaboration Environment or select the step below that corresponds your collaboration environment
    1. Lingobot Slack Setup
    2. LingoBot MS Team Setup
    3. LingoBot CA Flowdock Setup
    4. LingoBot Cisco Spark Setup
  4. Installing the Lingobot Service
  5. Lingobot CLI verification