Installation
Instructions on how to properly install the BotCaptain
Prerequisites
It is recommended to have a system that has at least 8GB of RAM and 75GB of storage available.
NodeJS and NPM are required for installation. You can download the package for your operating system here.
If using Apache Cassandra, an endpoint must be properly configured with a valid username and password available. If using Azure Cosmos DB, a contact point and valid certificate must be ready and available. If using Astra services a valid key-space and secure connect bundle must be specified. See CassandraDB docs for more information.
If using Kudu an API endpoint, username, and password must be available.
If using a Learning Record Store with xAPI a valid endpoint, objectID, username and password must be available.
To use email functionality a valid email and password is needed. It is recommended to use a "throw-away" account, to accomodate for credential compromise(s).
Installing Locally
Installation on a local system is simple enough. Simply clone the repository and run npm install in the repo's directory.
Initial Configurations
Three scripts are available for assisting in the initial configuration of bot captain.
Configuration.js
configuration.js will prompt the user for secrets, usernames, and endpoints. The output will be a config.json file which will hold these credentials locally.
The email prompts are required. A valid email address and password is needed for the bot to be able to use reminder functionality.
For security reasons it is best practice to use a throw away account for the email section of the config. That way if credentials are leaked or stolen, damages will be minimal or may not exist at all.
The Cassandra database, xAPI, and kudu API prompts are not required. If these services not being utilized simply press the enter key on related prompts.
A username and password are required if Cassandra wishes to be utilized. For Astra services, a key-space and secure connect bundle is necessary to authenticate. For Azure services a contact point and X.509 certificate is needed (See X.509 section for more info).
A valid endpoint, username, password and objectID are required if an learning record store using xAPI is desired to be used.
A valid endpoint, userName, and password are required if kudu API is desired to be used.
buildDatabase.js
buildDatabase.js will prompt the user for class information to build the necessary directory structure to allow persistence.
A class number and team name must be specified . This will allow for a directory to be created to hold profiles, and messages.
taskCreate.js
After a database is created locally tasks can be added to a specified class and team via this script. Simply run node taskCreate.js and fill in the necessary prompt.
For the date section of the prompt a mm/dd/yyyy format should be followed.
Configuring .env
A file explicitly named ".env" is necessary for deploying to the cloud and testing a channel locally.
The two fields that must be entered in the file are microsoftAppID and microsoftAppPassword.
If testing locally these fields can be left blank. If deploying to Azure these fields can be found under "resources". Look at the following section for more details.
Deploying to Microsoft Azure
To deploy the bot to Microsoft Azure a web bot application and app service must already be set up on a valid subscription. You can view how to create web bot apps in Azure here.
Ensure that Node.js is the chosen language as the PostDeployScripts directory and web.config for BotCaptain follow this schema by default.
Getting microsoftAppID and microsoftAppPassword
Microsoft Azure cloud services keeps related credentials under the Resources directory in a specified deployment.
First click the three lines in the top left and select resource groups.
Next select the group that you wish to get credentials from.
Under settings and deployments select the deployment that you wish to get credentials for.
Under the inputs section of the deployment the AppID and AppPassword will be found. Enter these values into the .env file.
Creating a Private Repository
Once that is completed clone the publicly available Github repository and create your own private repository. Then push the cloned repository to this private repository and remove the public .git file.
Once the above step is completed clone the private repository using your organizations credentials and follow the previous section to make the required changes to allow the bot to work locally.
Do not make sensitive changes to the application on a public repository. Required changes include placing secrets in the config.json file which can be trivially intercepted if the repository is publicly available.
Configuring Continuous Integration / Continuous Deployment
After this log back into your Azure account and go to the App Service that was generated from the previous step. Then go to Deployment Center and choose GitHub for continuous integration. Authorization will be required to move onto the next steps.
Once Authorized pick the team, repository and branch that you want to be integrated into Microsoft Azure.
Once completed simply view the summary and click finish to submit changes.
Unit tests must be passed on the branch chosen in order for a push to be reflected in Azure.
X.509 Certificate for Azure CosmosDB
In order to use Apache Cassandra Functionality securely a X.509 certificate must be generated in order to connect to partitions.
To create a certificate using OpenSSL use enter the following in a terminal
The command above will generate a private key and certificate that will be valid for one year. Simply enter the information requested by the prompts or just press the enter key to accept defaults.
Last updated
