From fae8cf52b9cea5f86783acfbe9911992c29596ec Mon Sep 17 00:00:00 2001 From: codehobbyist06 <65885804+codehobbyist06@users.noreply.github.com> Date: Tue, 30 Mar 2021 03:00:27 +0530 Subject: [PATCH 1/3] setup.rst: Add docs to setup corobo This illustrates the steps involved in setting up corobo in text mode and with gitter-backend. Closes https://github.com/coala/corobo/issues/668 --- docs/setup.rst | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/setup.rst diff --git a/docs/setup.rst b/docs/setup.rst new file mode 100644 index 00000000..bd9b844e --- /dev/null +++ b/docs/setup.rst @@ -0,0 +1,90 @@ +Setting Up Corobo +================= + +The following documentation illustrates the process to install Corobo and interface it with the gitter API. + +Installation +------------ + +* To install corobo, first you need to setup a virtual environment(it is not mandatory but highly recommended). This can be done as follows: + :: + pip3 install virtualenv + virtualenv venv -p python + cd venv + source bin/activate ----> For Linux + \Scripts\activate ----> For Windows +* Next, you can clone the corobo package via git and install the requirements(dependent packages). + :: + git clone https://github.com/coala/corobo.git + pip install -r requirements.txt + +Configuration of Environment variables(In text mode) +-------------------------------------------------- + +* The following environment variables are required to setup corobo in text mode: + :: + export BOT_PREFIX="any_name" + export BACKEND="Text" + export BOT_USERNAME="@any_other_name" + (**Note:** The BOT_USERNAME always starts with a @ for a person and # for a room) + +Testing Corobo +--------------------------- + +* To run the bot use: + :: + errbot +* You can test the bot using the following commands: + :: + bot_prefix help ----> Lists the set of commands available with the bot + bot_prefix history ----> Lists the command history + + +Setting up Corobo with gitter backend +===================================== + +#. Clone the err-backend-gitter repository in your "corobo" folder. + :: + git clone https://github.com/errbotio/err-backend-gitter.git + +#. Configure the environment variables(for gitter-backend). + :: + export BACKEND="Gitter" + export BOT_EXTRA_BACKEND_DIR="/path_to/err-backend-gitter" +#. To make the bot interact with the gitter API you will need a github account(this account can be used to login to gitter) to generate the gitter access token. + **Remember it is recommended to use a separate account(other than the admin account) for the bot.** + Once the account is setup, run the following script. + :: + ./oauth.py + This will guide you with the gitter token generation process. +#. Now you can assign the above generated token to the BOT_TOKEN environment variable. + :: + export BOT_TOKEN="your_gitter_token" +#. Also to configure the bot with access to your github and gitlab repositories, you will need personal access tokens. + The following links may guide you through this: + https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token + https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html +#. You can also create github organisations and gitlab groups to manage your repositories. + Under a organisation you can make teams to organize the workforce. +#. After completing the above steps, it is time to setup the remaining environment variables with the above gathered information. + :: + export GH_TOKEN="your_github_token" + export GL_TOKEN="your_gitlab_token" + export GH_ORG_NAME="your_github_organisation_name" + export GL_ORG_NAME="your_gitlab_organisation_name" + export ROOMS="rooms_to_join" + export BOT_ADMINS="your_gitter_username" + (**Note:** The admin user account should be different than the bot account.) +#. Hurrah!!! the bot is now ready to be deployed. To run the corobo instance use: + :: + errbot + +Your corobo instance should now be running. You can chat with the bot by logging in through the admin gitter account and +searching its username in the contacts section. You can send it commands via chat. +:: + bot_prefix help + bot_prefix history + +**Note:** Every time you run a new instance of the bot, it is required to set the environment variables(steps 2 and 7). + +To know more about the list of available commands and other features of corobo checkout the other `docs `_. From b78d77d9246038577a1653ab3397b3f534000574 Mon Sep 17 00:00:00 2001 From: Anshul Pandey Date: Sun, 18 Apr 2021 22:36:41 +0530 Subject: [PATCH 2/3] docs/setup.rst: Make required changes --- docs/setup.rst | 67 +++++++++++++++++++++----------------------------- 1 file changed, 28 insertions(+), 39 deletions(-) diff --git a/docs/setup.rst b/docs/setup.rst index bd9b844e..8a9a367e 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -1,7 +1,7 @@ Setting Up Corobo ================= -The following documentation illustrates the process to install Corobo and interface it with the gitter API. +The following documentation illustrates the process to install corobo and interface it with the gitter(or any other backend) API. Installation ------------ @@ -13,61 +13,45 @@ Installation cd venv source bin/activate ----> For Linux \Scripts\activate ----> For Windows + * Next, you can clone the corobo package via git and install the requirements(dependent packages). :: git clone https://github.com/coala/corobo.git pip install -r requirements.txt - -Configuration of Environment variables(In text mode) --------------------------------------------------- - -* The following environment variables are required to setup corobo in text mode: - :: - export BOT_PREFIX="any_name" - export BACKEND="Text" - export BOT_USERNAME="@any_other_name" - (**Note:** The BOT_USERNAME always starts with a @ for a person and # for a room) - -Testing Corobo ---------------------------- - -* To run the bot use: - :: - errbot -* You can test the bot using the following commands: - :: - bot_prefix help ----> Lists the set of commands available with the bot - bot_prefix history ----> Lists the command history -Setting up Corobo with gitter backend -===================================== +Configuring the backend +------------------------ #. Clone the err-backend-gitter repository in your "corobo" folder. :: - git clone https://github.com/errbotio/err-backend-gitter.git - -#. Configure the environment variables(for gitter-backend). - :: - export BACKEND="Gitter" - export BOT_EXTRA_BACKEND_DIR="/path_to/err-backend-gitter" + git clone https://github.com/errbotio/errbot@a0f35732484c8c0692e123c48653517cffa21a42 + + #. To make the bot interact with the gitter API you will need a github account(this account can be used to login to gitter) to generate the gitter access token. **Remember it is recommended to use a separate account(other than the admin account) for the bot.** Once the account is setup, run the following script. :: ./oauth.py This will guide you with the gitter token generation process. -#. Now you can assign the above generated token to the BOT_TOKEN environment variable. - :: - export BOT_TOKEN="your_gitter_token" + +#. Keep this token safe. It will be used later to set the environment variables. + #. Also to configure the bot with access to your github and gitlab repositories, you will need personal access tokens. The following links may guide you through this: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html + #. You can also create github organisations and gitlab groups to manage your repositories. - Under a organisation you can make teams to organize the workforce. -#. After completing the above steps, it is time to setup the remaining environment variables with the above gathered information. + Under a organisation, you can make teams to organize the workforce. + +#. To configure the bot to join rooms, it is required to first manually join those rooms via the bot gitter account. Once this is done, the bot would automatically find these rooms(if mentioned in ROOMS env variable) and establish connection with them. + +#. After completing the above steps, it is time to setup the environment variables with the above gathered information. :: + export BOT_PREFIX="any_name" ----> This will be used to address the bot along with any command + export BACKEND="Gitter" ----> Set the backend(other options are "Text","Zulip",etc.) + export BOT_TOKEN="your_gitter_token" export GH_TOKEN="your_github_token" export GL_TOKEN="your_gitlab_token" export GH_ORG_NAME="your_github_organisation_name" @@ -75,16 +59,21 @@ Setting up Corobo with gitter backend export ROOMS="rooms_to_join" export BOT_ADMINS="your_gitter_username" (**Note:** The admin user account should be different than the bot account.) -#. Hurrah!!! the bot is now ready to be deployed. To run the corobo instance use: + +#. Hurrah!!! the bot is now ready to rock. To run the corobo instance use: :: errbot + (**Note:** You can use the --DEBUG flag to run the bot in debug mode.) + Your corobo instance should now be running. You can chat with the bot by logging in through the admin gitter account and searching its username in the contacts section. You can send it commands via chat. :: - bot_prefix help - bot_prefix history + bot_prefix help ----> Lists the set of commands available with the bot + bot_prefix history ----> Lists the command history -**Note:** Every time you run a new instance of the bot, it is required to set the environment variables(steps 2 and 7). + +**Note:** To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and run it before running the bot. +Refer this `link `_ for more info. To know more about the list of available commands and other features of corobo checkout the other `docs `_. From 0ad88f499e0efdfc620b6c717db7adef2971ad82 Mon Sep 17 00:00:00 2001 From: Anshul Pandey Date: Tue, 27 Apr 2021 16:54:39 +0530 Subject: [PATCH 3/3] setup.rst: Update docs --- docs/setup.rst | 130 +++++++++++++++++++++++++++---------------------- 1 file changed, 73 insertions(+), 57 deletions(-) diff --git a/docs/setup.rst b/docs/setup.rst index 8a9a367e..a3e1f005 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -1,79 +1,95 @@ Setting Up Corobo ================= -The following documentation illustrates the process to install corobo and interface it with the gitter(or any other backend) API. +The following documentation illustrates the process to +install corobo and interface it with the Gitter +(or any other backend) API. Installation ------------ +- To install corobo, first you need to install + python (version 3.6 or more) and set up a virtual environment. + This can be done as follows: + :: + python3 -m venv env + cd env + source bin/activate ----> For Linux + \Scripts\activate ----> For Windows -* To install corobo, first you need to setup a virtual environment(it is not mandatory but highly recommended). This can be done as follows: - :: - pip3 install virtualenv - virtualenv venv -p python - cd venv - source bin/activate ----> For Linux - \Scripts\activate ----> For Windows +- Next, you can clone the corobo package via git and + install the requirements (dependent packages). + :: + git clone https://github.com/coala/corobo.git + cd corobo + pip install -r requirements.txt -* Next, you can clone the corobo package via git and install the requirements(dependent packages). - :: - git clone https://github.com/coala/corobo.git - pip install -r requirements.txt - - Configuring the backend ------------------------- +----------------------- -#. Clone the err-backend-gitter repository in your "corobo" folder. - :: - git clone https://github.com/errbotio/errbot@a0f35732484c8c0692e123c48653517cffa21a42 - +- Clone the err-backend-gitter repository in your "corobo" folder. + :: + pip3 install git+https://github.com/errbotio/\ + err-backend-gitter@14a428bdd0597b473605264c822855da979bd916 -#. To make the bot interact with the gitter API you will need a github account(this account can be used to login to gitter) to generate the gitter access token. - **Remember it is recommended to use a separate account(other than the admin account) for the bot.** - Once the account is setup, run the following script. - :: - ./oauth.py - This will guide you with the gitter token generation process. +- To make the bot interact with the Gitter API, you need to login to + Gitter using your GitHub, GitLab, Twitter, or any other available + account. Remember, it is recommended to use a separate account + (other than the admin account) for the bot. The bot will now use + this account as its Gitter identity. -#. Keep this token safe. It will be used later to set the environment variables. - -#. Also to configure the bot with access to your github and gitlab repositories, you will need personal access tokens. - The following links may guide you through this: - https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token - https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html +- Also, you need to get your Gitter personal access token. It can be + found by logging in `here `_ with + the above-created account. -#. You can also create github organisations and gitlab groups to manage your repositories. - Under a organisation, you can make teams to organize the workforce. +- To configure the bot with access to your + `GitHub `_ + and `GitLab `_ + repositories, you will again need access tokens. + The given hyperlinks would guide you with the process. -#. To configure the bot to join rooms, it is required to first manually join those rooms via the bot gitter account. Once this is done, the bot would automatically find these rooms(if mentioned in ROOMS env variable) and establish connection with them. +- You can also create GitHub organizations and GitLab groups to + manage your repositories. + Under any organization, you can make teams to organize the workforce. -#. After completing the above steps, it is time to setup the environment variables with the above gathered information. - :: - export BOT_PREFIX="any_name" ----> This will be used to address the bot along with any command - export BACKEND="Gitter" ----> Set the backend(other options are "Text","Zulip",etc.) - export BOT_TOKEN="your_gitter_token" - export GH_TOKEN="your_github_token" - export GL_TOKEN="your_gitlab_token" - export GH_ORG_NAME="your_github_organisation_name" - export GL_ORG_NAME="your_gitlab_organisation_name" - export ROOMS="rooms_to_join" - export BOT_ADMINS="your_gitter_username" - (**Note:** The admin user account should be different than the bot account.) +- To configure the bot to join rooms, it must first + manually enter those rooms via the bot Gitter account. Once this + is done, the bot would automatically find these rooms (if mentioned + in the ROOMS env variable) and establish a connection with them. -#. Hurrah!!! the bot is now ready to rock. To run the corobo instance use: - :: - errbot +- After completing the above steps, it is finally time to set up the + environment variables with the above-gathered information. You + can create a .env file with the following variables and source it + before running the bot. + :: + BOT_PREFIX="any_name" ----> This will be used to address the bot + along with any command + BACKEND="Gitter" ----> Set the backend (other options are + "Text","Zulip",etc.) + BOT_TOKEN="your_gitter_token" + GH_TOKEN="your_github_token" + GL_TOKEN="your_gitlab_token" + GH_ORG_NAME="your_github_organisation_name" + GL_ORG_NAME="your_gitlab_organisation_name" + ROOMS="rooms_to_join" + BOT_ADMINS="your_gitter_username" + (**Note:** The admin user account should be different than the + bot account.) - (**Note:** You can use the --DEBUG flag to run the bot in debug mode.) +- Hurrah!!! The bot is now ready to rock. To run the corobo instance, use: + :: + errbot + (**Note:** You can use the --DEBUG flag to run the bot in debug mode.) -Your corobo instance should now be running. You can chat with the bot by logging in through the admin gitter account and -searching its username in the contacts section. You can send it commands via chat. +Your corobo instance should now be running. You can chat with the bot by +logging in through the admin Gitter account and searching it's username in +the conversations tab. +You can send it commands via chat. :: bot_prefix help ----> Lists the set of commands available with the bot bot_prefix history ----> Lists the command history - -**Note:** To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and run it before running the bot. -Refer this `link `_ for more info. - -To know more about the list of available commands and other features of corobo checkout the other `docs `_. +To know more about the list of available commands and other features +of corobo, check out the other +`docs `_.