From 0aa0b29c7e5279dbdfaf90a02e1963f201660ea4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juuso=20Kalliom=C3=A4ki?= Date: Fri, 13 May 2022 10:08:49 +0300 Subject: [PATCH] moved installation info to readme --- README.md | 53 +++++++++++++--- how-to-run/tutorial.md | 71 ---------------------- {how-to-run => images}/AppHome.png | Bin {how-to-run => images}/EnableEvents.png | Bin {how-to-run => images}/commands.png | Bin {how-to-run => images}/event-sub.png | Bin {how-to-run => images}/groups-command.png | Bin {how-to-run => images}/interactivity.png | Bin {how-to-run => images}/name.png | Bin {how-to-run => images}/new.png | Bin {how-to-run => images}/oauth-token.png | Bin {how-to-run => images}/permissions.png | Bin {how-to-run => images}/signing-secret.png | Bin 13 files changed, 46 insertions(+), 78 deletions(-) delete mode 100644 how-to-run/tutorial.md rename {how-to-run => images}/AppHome.png (100%) rename {how-to-run => images}/EnableEvents.png (100%) rename {how-to-run => images}/commands.png (100%) rename {how-to-run => images}/event-sub.png (100%) rename {how-to-run => images}/groups-command.png (100%) rename {how-to-run => images}/interactivity.png (100%) rename {how-to-run => images}/name.png (100%) rename {how-to-run => images}/new.png (100%) rename {how-to-run => images}/oauth-token.png (100%) rename {how-to-run => images}/permissions.png (100%) rename {how-to-run => images}/signing-secret.png (100%) diff --git a/README.md b/README.md index f3dbee9..35beba3 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,54 @@ This project is a Slack application that helps users join and leave user groups. ### Prerequisites -This is an example of how to list things you need to use the software and how to install them -* npm - ```sh - npm install npm@latest -g - ``` +To run the bot locally you need either a Java runtime or Docker installed along with ngrok to ge a tunnel for getting a public url. -### Installation -- PLACEHOLDER +## Installation + +## Setup bot on Slack's [website](https://api.slack.com/apps) +First create a new app from the link above and give it a name and a workspace where it will be working in. + +![new](images/new.png) + +![name](images/name.png) + +After creating the bot, scroll down to the App Credentials in **Basic Information.** The Signing Secret is used in the env file. + +![signing-secret](images/signing-secret.png) + +Then go to the **OAuth & Permissions** tab and scroll down. Add the following permissions for this bot to work. + +![permissions](images/permissions.png) + +On the same tab, scroll up to the OAuth Tokens section and press Install to Workspace. Allow all permissions. The Token will be used in the env file. + +![oauth-token](images/oauth-token.png) + +Next navigate to the **App Home** tab and enable all three settings. You can also change the bot's name here. + +![AppHome](images/AppHome.png) + +Now, run the bot (and ngrok if needed and keep note of the URL) before setting up the rest of the bot functionality. + +Got to the **Event Subscriptions** tab and write the URL where your VM is accessible (either the ngrok URL or your own public one) with the **/slack/events** endpoint specified. Then scroll down to **Subscribe to bot events** and add "app_home_opened" and "app_mention" to the bot events. + +![EnableEvents](images/EnableEvents.png) + +After that, copy that same URL to the Request URL in **Interactivity & Shortcuts**. You may need to enable Interactivity to see this view. + +![interactivity](images/interactivity.png) + +Then create a new command in the **Slash Commands** tab with the **Create New Command** button. + +![commands](images/commands.png) + +The command should be **\*/groups\*** and the URL the same as before. The rest of the options don't matter in regards of the bots functionality. + +![groups-command](images/groups-command.png) + +Now just invite the bot to a channel with **@APPNAME** where you want to use it. + ### Running the image diff --git a/how-to-run/tutorial.md b/how-to-run/tutorial.md deleted file mode 100644 index 2327ca4..0000000 --- a/how-to-run/tutorial.md +++ /dev/null @@ -1,71 +0,0 @@ -## Setup bot on Slack's [website](https://api.slack.com/apps) -First create a new app from the link above and give it a name and a workspace where it will be working in. - -![new](new.png) - -![name](name.png) - -After creating the bot, scroll down to the App Credentials in **Basic Information.** The Signing Secret is used in the env file. - -![signing-secret](signing-secret.png) - -Then go to the **OAuth & Permissions** tab and scroll down. Add the following permissions for this bot to work. - -![permissions](permissions.png) - -On the same tab, scroll up to the OAuth Tokens section and press Install to Workspace. Allow all permissions. The Token will be used in the env file. - -![oauth-token](oauth-token.png) - -Next navigate to the **App Home** tab and enable all three settings. You can also change the bot's name here. - -![AppHome](AppHome.png) - -Now, run the bot (and ngrok if needed and keep note of the URL) before setting up the rest of the bot functionality. - -Got to the **Event Subscriptions** tab and write the URL where your VM is accessible (either the ngrok URL or your own public one) with the **/slack/events** endpoint specified. Then scroll down to **Subscribe to bot events** and add "app_home_opened" and "app_mention" to the bot events. - -![EnableEvents](EnableEvents.png) - -After that, copy that same URL to the Request URL in **Interactivity & Shortcuts**. You may need to enable Interactivity to see this view. - -![interactivity](interactivity.png) - -Then create a new command in the **Slash Commands** tab with the **Create New Command** button. - -![commands](commands.png) - -The command should be **\*/groups\*** and the URL the same as before. The rest of the options don't matter in regards of the bots functionality. - -![groups-command](groups-command.png) - -Now just invite the bot to a channel with **@APPNAME** where you want to use it. - -## Running the bot in a VM -First, install docker on the VM (or your own machine). [https://docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/) - -Run the following commands. - -```bash -# clone repo -git clone https://github.com/NitorCreations/slack-group-bot -cd slack-group-bot -docker build . -t bot # replace bot with a name of your choice - -# check OAuth token and signing secret from the app's settings - -# write env -cat < .env -PORT=[PORT] -SLACK_BOT_TOKEN=[xoxb-TOKEN...] -SLACK_SIGNING_SECRET=[SECRET] -EOF - -# run docker image -docker run -d --env-file .env -p [LOCAL_PORT]:[CONTAINER_PORT] bot - -# if not already on public net, run ngrok tunnel -ngrok http [LOCAL_PORT] - -# finish setting up the URL's for the app now -``` diff --git a/how-to-run/AppHome.png b/images/AppHome.png similarity index 100% rename from how-to-run/AppHome.png rename to images/AppHome.png diff --git a/how-to-run/EnableEvents.png b/images/EnableEvents.png similarity index 100% rename from how-to-run/EnableEvents.png rename to images/EnableEvents.png diff --git a/how-to-run/commands.png b/images/commands.png similarity index 100% rename from how-to-run/commands.png rename to images/commands.png diff --git a/how-to-run/event-sub.png b/images/event-sub.png similarity index 100% rename from how-to-run/event-sub.png rename to images/event-sub.png diff --git a/how-to-run/groups-command.png b/images/groups-command.png similarity index 100% rename from how-to-run/groups-command.png rename to images/groups-command.png diff --git a/how-to-run/interactivity.png b/images/interactivity.png similarity index 100% rename from how-to-run/interactivity.png rename to images/interactivity.png diff --git a/how-to-run/name.png b/images/name.png similarity index 100% rename from how-to-run/name.png rename to images/name.png diff --git a/how-to-run/new.png b/images/new.png similarity index 100% rename from how-to-run/new.png rename to images/new.png diff --git a/how-to-run/oauth-token.png b/images/oauth-token.png similarity index 100% rename from how-to-run/oauth-token.png rename to images/oauth-token.png diff --git a/how-to-run/permissions.png b/images/permissions.png similarity index 100% rename from how-to-run/permissions.png rename to images/permissions.png diff --git a/how-to-run/signing-secret.png b/images/signing-secret.png similarity index 100% rename from how-to-run/signing-secret.png rename to images/signing-secret.png