Difference between revisions of "LingoBot Installation"

From Lingoport Wiki
Jump to: navigation, search
 
(95 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Configuration Overview ==
+
== Overview ==
  +
To start the lingobot service, some configuration is needed first.
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 the LingoBot's configuration file:
 
  +
# A Jenkins CLI user needs to have been created. This should have been done at installation. To check this, see [https://wiki.lingoport.com/Set_Up_Jenkins_CLI_User Set Up Jenkins CLI User]
  +
# A LingoBot user needs to be added to the Dashboard
  +
# 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.
  +
# Start the lingoport.lingobot service on the Lingoport server.
   
  +
== Configuration Settings: lingobot_config.sh ==
Below is a template of the configuration file's contents. The file itself can be found under LingoBot's home directory in the config subdirectory, and is called `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 <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
Line 10: Line 20:
 
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= # Possible values: 'flowdock', 'slack', 'sparkwebhook' (Cisco Spark)
+
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
Line 17: Line 26:
 
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= # required if LINGOBOT_ADAPTER is 'flowdock'
+
export HUBOT_FLOWDOCK_API_TOKEN=
export HUBOT_SLACK_TOKEN= # required if LINGOBOT_ADAPTER is 'slack'
+
export HUBOT_SLACK_TOKEN=
export CISCOSPARK_ACCESS_TOKEN= # required if LINGOBOT_ADAPTER is 'sparkwebhook'
+
export CISCOSPARK_ACCESS_TOKEN=
export CISCOSPARK_SECRET= # required if LINGOBOT_ADAPTER is 'sparkwebhook'.
+
export CISCOSPARK_SECRET=
  +
export LINGOBOT_API_TOKEN=
 
  +
export BOTBUILDER_APP_ID=
# NATURAL LANGUAGE PROCESSING (BETA)
 
  +
export BOTBUILDER_APP_PASSWORD=
export LINGOBOT_USE_NLP=false # If set to true, LingoBot will use NLP powered by wit.ai
 
  +
# 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
Below, you will find instructions on how to obtain all of the necessary values to properly fill out this configuration file.
 
  +
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
== LingoBot Jenkins Setup ==
 
  +
# BETA
The first step in the configuration process is to create a Jenkins user which can LingoBot 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!
 
  +
export LINGOBOT_USE_NLP=false
 
* Navigate to your Lingoport Jenkins instance in a web browser (this is typically hosted on port 8080 of the Lingoport server).
 
* 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).
 
** 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 "Apply" 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 "Apply" 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...". 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.
 
 
Example:
 
export LINGOBOT_JENKINS_TOKEN=1234567890abcdef14d4f2789bea4f22a
 
 
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")
 
 
== 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.
 
 
* Navigate to your Lingoport Dashboard instance in a web browser (this is typically hosted on port 9000 of the Lingoport server).
 
* 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.
 
 
Example:
 
export LINGOBOT_DASHBOARD_TOKEN=1234567890abcdef14d4f2789bea4f22a
 
 
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.
 
 
== 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:
 
export LINGOBOT_NAME=lingobot-123
 
* 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 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.
 
 
== Running The Installation Script ==
 
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 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 "No-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.
 
   
  +
=== Set the Jenkins and Dashboard Locations ===
Example:
 
/var/lib/jenkins/lingoport/lingobot-1.0/lingobot_installer/install.sh
 
   
  +
To get started, set the <code>LINGOBOT_DASHBOARD_URL</code> to the URL values for the Dashboard.
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.
 
  +
export LINGOBOT_DASHBOARD_URL=<nowiki>https://acme.company.com</nowiki>
If something needs to be changed, simply modify the LingoBot config file and rerun the install script until it reports a successful installation.
 
   
  +
Leave the port values as they are defaulted.
Once this is done, your instance of LingoBot will be up and running!
 
  +
export LINGOBOT_JENKINS_PORT=8080
  +
export LINGOBOT_DASHBOARD_PORT=9000
   
  +
If you have an older system that uses the port numbers so that the Dashboard URL is something like <nowiki>http://acme.company.com:9000</nowiki>, then just use the URL before the port value.
== Running The Installation Script (No-Sudo) ==
 
  +
export LINGOBOT_DASHBOARD_URL=<nowiki>http://acme.company.com</nowiki>
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.
 
  +
but make sure the port values are set.
  +
export LINGOBOT_JENKINS_PORT=8080
  +
export LINGOBOT_DASHBOARD_PORT=9000
   
  +
=== Setting or changing the Optional Configurations ===
Example:
 
/var/lib/jenkins/lingoport/lingobot-1.0/lingobot_installer/install.sh --nosudo
 
   
  +
The optional configuration settings don't need to be set to complete the installation of LingoBot.
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
 
   
  +
To make changes see [[LingoBot_CLI#Server_Modifications|LingoBot CLI Server Modifications]]
Once this is done, you instance of LingoBot will be up and running!
 
   
  +
# OPTIONAL CONFIGS FOR LINGOBOT API
== Installation Verification ==
 
  +
# If these are unset, the default values are used
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.
 
  +
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 ==
Example:
 
  +
For step-by-step configuration, execute the following instructions:
@lingobot ping
 
   
  +
#[[Set Up Jenkins Lingobot User]]
if LingoBot responds with "PONG", then you have successfully launched LingoBot. Have Fun!
 
  +
#[[LingoBot Dashboard Setup]]
  +
# [[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]]

Latest revision as of 20:30, 15 July 2020

Overview

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

  1. A Jenkins CLI user needs to have been created. This should have been done at installation. To check this, see Set Up Jenkins CLI User
  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 the Lingoport 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_DASHBOARD_URL to the URL values for the Dashboard.

export LINGOBOT_DASHBOARD_URL=https://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 older system that uses the port numbers so that the Dashboard URL is something like http://acme.company.com:9000, then just use the URL before the port value.

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