diff --git a/docs/_config.yml b/docs/_config.yml index a846286aa..ee69b689f 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -2,8 +2,8 @@ # 'bundle exec jekyll serve'. If you change this file, please restart the server process. title: Bolt description: >- - A framework that makes Slack app development fast and straight-forward. - With a single interface for Slack’s Web API, Events API, and interactive features, + A framework that makes Slack app development fast and straight-forward. + With a single interface for Slack’s Web API, Events API, and interactive features, Bolt gives you the full power of the Slack platform out of the box. baseurl: /bolt-js url: https://slack.dev @@ -15,6 +15,8 @@ collections: output: false steps: output: false + deployments: + output: true tutorials: output: true permalink: /tutorials/:slug @@ -34,6 +36,7 @@ t: advanced: Advanced concepts start: Getting started steps: Workflow steps + deployments: Deployments contribute: Contributing ja-jp: basic: 基本的な概念 @@ -41,6 +44,8 @@ t: start: Bolt 入門ガイド # TODO: translate this title steps: Workflow steps + # TODO: translate this title + deployments: Deployments contribute: 貢献 # Metadata diff --git a/docs/_deployments/heroku.md b/docs/_deployments/heroku.md new file mode 100644 index 000000000..5b7884f8c --- /dev/null +++ b/docs/_deployments/heroku.md @@ -0,0 +1,265 @@ +--- +title: Deploying to Heroku +order: 0 +slug: heroku +lang: en +layout: tutorial +permalink: /deployments/heroku +redirect_from: + - /deployments +--- +# Deploying to Heroku + +
+This guide will walk you through preparing and deploying a Slack app using [Bolt for JavaScript](/bolt-js) and the [Heroku platform](https://heroku.com/). Along the way, we’ll download a Bolt Slack app, prepare it for Heroku, and deploy it. +
+ +When you’re finished, you’ll have this ⚡️[Getting Started with Heroku app][getting-started-with-heroku-app] to run, modify, and make your own. + +--- + +### Get a Bolt Slack app + +If you haven't already built your own Bolt app, you can use our [Getting Started guide][getting-started-guide] or clone the template app below: + +```shell +git clone https://github.com/slackapi/bolt-js-getting-started-app.git +``` + +After you have a Bolt app, navigate to its directory: + +```shell +cd bolt-js-getting-started-app/ +``` + +Now that you have an app, let's prepare it for Heroku. + +--- + +### Prepare the app for Heroku + +Heroku is a flexible platform that requires some configuration to host your app. In this section, we'll update your Bolt app to support Heroku. + +**1. Use a Git repository** + +Before you can deploy your app to Heroku, you'll need a Git repository. If you aren't already using Git, you'll need to [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [create a Git repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository). + +> 💡 Skip this step if you used `git clone` in the previous section because you already have a Git repository. + +**2. Add a Procfile** + +Every Heroku app uses a special file called `Procfile` that tells Heroku how to start your app. A Bolt Slack app will be started as a web server with a public web address. + +Create a new file called `Procfile` (without any extension) in your app's root directory anad paste the following: + +```yaml +web: node app.js +``` + +Once you've saved the file, let's commit it to your Git repository: + +```shell +git add Procfile +git commit -m "Add Procfile" +``` + +> 💡 Are you following this guide with an existing Bolt app? If so, please review the guide on [preparing a codebase for Heroku](https://devcenter.heroku.com/articles/preparing-a-codebase-for-heroku-deployment#4-listen-on-the-correct-port) to listen on the correct port. + +--- + +### Setup the Heroku tools + +Now we can set up the Heroku tools on your local machine. These tools will help you manage, deploy, and debug your app on Heroku's platform. + +**1. Install the Heroku CLI** + +The Heroku tools are available as a Command Line Interface (CLI). Go ahead and [install the Heroku CLI for macOS, Windows, or Linux](https://devcenter.heroku.com/articles/getting-started-with-nodejs#set-up). On macOS, you can run the command: + +```shell +brew install heroku/brew/heroku +``` + +Once the install is complete, we can test the Heroku CLI by displaying all of the wonderful commands available to you: + +```shell +heroku help +``` + +> 💡 If the `heroku` command is not found, refresh your path by opening a new terminal session/tab. + +**2. Log into the Heroku CLI** + +The Heroku CLI connects your local machine with your Heroku account. [Sign up for a free Heroku account](https://heroku.com) and then log into the Heroku CLI with the following command: + +```shell +heroku login +``` +> 💡 If you're behind a firewall, you may need to [set the proxy environment variables](https://devcenter.heroku.com/articles/using-the-cli#using-an-http-proxy) for the Heroku CLI. + +**3. Confirm you're logged into the Heroku CLI** + +Check that you're logged in by displaying the account currently connected to your Heroku CLI: + +```shell +heroku auth:whoami +``` + +You should now be set up with the Heroku tools! Let's move on to the exciting step of creating an app on Heroku. + +--- + +### Create an app on Heroku + +It’s time to [create a Heroku app](https://devcenter.heroku.com/articles/creating-apps) using the tools that you just installed. When you create an app, you can choose a unique name or have it randomly generated. + +> 💡 You can [rename a Heroku app](https://devcenter.heroku.com/articles/renaming-apps) at any time, but you may change your Git remote and public web address. + +**1. Create an app on Heroku** + +Create an app on Heroku with a unique name: + +```shell +heroku create my-unique-bolt-app-name +``` + +or, have some fun with a random name: + +```shell +heroku create +# Creating sharp-rain-871... done, stack is heroku-18 +# https://sharp-rain-871.herokuapp.com/ | https://git.heroku.com/sharp-rain-871.git +``` + +After your app is created, you'll be given some information that we'll use in the upcoming sections. In the example above: + +- App name is `sharp-rain-871` +- Web address is `https://sharp-rain-871.herokuapp.com/` +- Empty Git remote is `https://git.heroku.com/sharp-rain-871.git` + +**2. Confirm Heroku Git remote** + +The Heroku CLI automatically adds a Git remote called `heroku` to your local repository. You can list your Git remotes to confirm `heroku` exists: + +```shell +git remote -v +# heroku https://git.heroku.com/sharp-rain-871.git (fetch) +# heroku https://git.heroku.com/sharp-rain-871.git (push) +``` + +**3. Set environment variables on Heroku** + +Now you'll need to add your Slack app credentials to your Heroku app: + +```shell +heroku config:set SLACK_SIGNING_SECRET= +heroku config:set SLACK_BOT_TOKEN=xoxb- +``` + +> 💡 If you don't know where to find your credentials, please read about [exporting your signing secret and token](/bolt-js/tutorial/getting-started#tokens-and-installing-apps) in the Getting Started guide. + +Now that we have prepared your local app and created a Heroku app, the next step is to deploy it! + +--- + +### Deploy the app + +To deploy the app, we're going to push your local code to Heroku, update your Slack app's settings, and say "hello" to your Heroku app. ✨ + +**1. Deploy the app to Heroku** + +When deploying an app to Heroku, you'll typically use the `git push` command. This will push your code from your local repository to your `heroku` remote repository. + +You can now deploy your app with the command: + +```shell +git push heroku main +``` + +> 💡 Heroku deploys code that's pushed to the [master or main branches](https://devcenter.heroku.com/articles/git-branches). Pushing to other branches will not trigger a deployment. + +Finally, we need to start a web server instance using the Heroku CLI: + +```shell +heroku ps:scale web=1 +``` + +**2. Update your Slack app's settings** + +Now we need to use your Heroku web address as your **Request URL**, which is where Slack will send events and actions. + +Get your Heroku web address with the following command: + +```shell +heroku info +# ... +# Web URL: https://sharp-rain-871.herokuapp.com/ +``` + +In our example, the web address is `https://sharp-rain-871.herokuapp.com/`. + +Head over to the [Slack App page](https://api.slack.com/apps) and select your app name. Next, we'll update your **Request URL** in two locations to be your web address. + +> 💡 Your **Request URL** ends with `/slack/events`, such as `https://sharp-rain-871.herokuapp.com/slack/events`. + +First, select **Interativity & Shortcuts** from the side and update the **Request URL**: + +![Interactivity & Shortcuts page](../assets/interactivity-and-shortcuts-page.png "Interactivity & Shortcuts page") + +Second, select **Event Subscriptions** from the side and update the **Request URL**: + +![Event Subscriptions page](../assets/event-subscriptions-page.png "Event Subscriptions page") + +> 💡 Free Heroku apps sleep when inactive. 💤 If your verification fails, please try it again immediately. + +**3. Test your Slack app** + +Your app is now deployed and Slack is updated, so let's try it out! + +Open a Slack channel that your app has joined and say "hello" (lower-case). Just like in the [Getting Started guide](/bolt-js/tutorial/getting-started#sending-and-responding-to-actions), your app should respond back. If you don't receive a response, check your **Request URL** and try again. + +--- + +### Deploy an update + +As you continue building your Slack app, you'll need to deploy updates. A common flow is to make a change, commit it, and then push it to Heroku. + +Let's get a feel for this by updating your app to respond to a "goodbye" message. Add the following code to `app.js` ([source code on GitHub](https://github.com/slackapi/bolt-js/blob/main/examples/getting-started-with-heroku/app.js)): + +```javascript +// Listens to incoming messages that contain "goodbye" +app.message('goodbye', async ({ message, say }) => { + // say() sends a message to the channel where the event was triggered + await say(`See ya later, <@${message.user}> :wave:`); +}); +``` + +Commit the changes to your local Git respository: + +```shell +git commit -am "Say 'goodbye' to a person" +``` + +Deploy the update by pushing to your `heroku` remote: + +```shell +git push heroku main +``` + +When the deploy is complete, you can open a Slack channel that your app has joined and say "goodbye" (lower-case). You should see a friendly farewell from your Slack app. + +--- + +### Next steps + +You just deployed your first ⚡️[Bolt for JavaScript app to Heroku][getting-started-with-heroku-app]! 🚀 + +Now that you've deployed a basic app, you can start exploring how to customize and monitor it. Here are some ideas of what to explore next: + +- Brush up on [how Heroku works](https://devcenter.heroku.com/articles/how-heroku-works) and understand the [limitations of a free Heroku app](https://devcenter.heroku.com/articles/free-dyno-hours). +- Extend your app with [Bolt's Basic Concepts](/bolt-js/concepts#basic) and [Heroku's Add-ons](https://elements.heroku.com/addons). +- Learn about logging in [Bolt's Advanced Concepts](/bolt-js/concepts#logging) and how to [view log messages in Heroku](https://devcenter.heroku.com/articles/getting-started-with-nodejs#view-logs). +- Get ready for primetime with [how to scale your Heroku app](https://devcenter.heroku.com/articles/getting-started-with-nodejs#scale-the-app). + +[getting-started-guide]: /bolt-js/tutorial/getting-started +[getting-started-with-heroku-app]: https://github.com/slackapi/bolt-js/tree/main/examples/getting-started-with-heroku +[getting-started-with-heroku-app]: https://github.com/slackapi/bolt-js/tree/main/examples/getting-started-with-heroku \ No newline at end of file diff --git a/docs/_includes/sidebar.html b/docs/_includes/sidebar.html index 5d4516204..04deeefbb 100644 --- a/docs/_includes/sidebar.html +++ b/docs/_includes/sidebar.html @@ -62,15 +62,29 @@ {% endfor %} + {% assign deployments_sections = site.deployments | sort: "order" | where: "lang", page.lang %} + {% if deployments_sections.size > 0 %} + + {% endif %} + diff --git a/docs/assets/event-subscriptions-page.png b/docs/assets/event-subscriptions-page.png new file mode 100644 index 000000000..713469575 Binary files /dev/null and b/docs/assets/event-subscriptions-page.png differ diff --git a/docs/assets/interactivity-and-shortcuts-page.png b/docs/assets/interactivity-and-shortcuts-page.png new file mode 100644 index 000000000..1e8853004 Binary files /dev/null and b/docs/assets/interactivity-and-shortcuts-page.png differ diff --git a/examples/getting-started-with-heroku/.gitignore b/examples/getting-started-with-heroku/.gitignore new file mode 100644 index 000000000..49d69386c --- /dev/null +++ b/examples/getting-started-with-heroku/.gitignore @@ -0,0 +1,3 @@ +# node / npm +node_modules/ +package-lock.json \ No newline at end of file diff --git a/examples/getting-started-with-heroku/LICENSE b/examples/getting-started-with-heroku/LICENSE new file mode 100644 index 000000000..c14199fe1 --- /dev/null +++ b/examples/getting-started-with-heroku/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2020 Slack Technologies, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/examples/getting-started-with-heroku/Procfile b/examples/getting-started-with-heroku/Procfile new file mode 100644 index 000000000..207d22f80 --- /dev/null +++ b/examples/getting-started-with-heroku/Procfile @@ -0,0 +1 @@ +web: node app.js \ No newline at end of file diff --git a/examples/getting-started-with-heroku/README.md b/examples/getting-started-with-heroku/README.md new file mode 100644 index 000000000..acd19138f --- /dev/null +++ b/examples/getting-started-with-heroku/README.md @@ -0,0 +1,61 @@ +# Getting Started with Heroku ⚡️ Bolt for JavaScript + +> Slack app example from 📚 [Deploying to Heroku with Bolt for JavaScript][1] + +## Overview + +This is a Slack app built with the [Bolt for JavaScript framework][2] that showcases +deploying to the [Heroku platform][3]. + +## Deploy to Heroku + +### 1. Initialize a Git repository + +```zsh +# Initialize Git repository +git init + +# Commit this project +git add . +git commit -am "Initial commit" + +# Rename master to main (optional) +git branch -m main +``` + +### 2. Create a Heroku app + +```zsh +heroku create +``` + +### 3. Set Heroku environment variables + +```zsh +heroku config:set SLACK_SIGNING_SECRET= +heroku config:set SLACK_BOT_TOKEN=xoxb- +``` + +### 4. Deploy to Heroku + +```zsh +# Deploy to Heroku +git push heroku main + +# Start web server on Heroku +heroku ps:scale web=1 +``` + +### 5. Create Slack App + +1. Follow the [Getting Started with Bolt for JavaScript][4] guide to: + - Create a Slack app + - Add required scopes + - Subscribe to required events +2. Follow the [Deploying to Heroku with Bolt for JavaScript][1] guide to: + - Update your **Request URL** for actions and events + +[1]: https://slack.dev/bolt-js/deployments/heroku +[2]: https://slack.dev/bolt-js/ +[3]: https://heroku.com/ +[4]: https://slack.dev/bolt-js/tutorial/getting-started \ No newline at end of file diff --git a/examples/getting-started-with-heroku/app.js b/examples/getting-started-with-heroku/app.js new file mode 100644 index 000000000..16f8e5109 --- /dev/null +++ b/examples/getting-started-with-heroku/app.js @@ -0,0 +1,51 @@ +const { App } = require('@slack/bolt'); + +// Initializes your app with your bot token and signing secret +const app = new App({ + token: process.env.SLACK_BOT_TOKEN, + signingSecret: process.env.SLACK_SIGNING_SECRET +}); + +// Listens to incoming messages that contain "hello" +app.message('hello', async ({ message, say }) => { + // say() sends a message to the channel where the event was triggered + await say({ + blocks: [ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": `Hey there <@${message.user}>!` + }, + "accessory": { + "type": "button", + "text": { + "type": "plain_text", + "text": "Click Me" + }, + "action_id": "button_click" + } + } + ], + text: `Hey there <@${message.user}>!` + }); +}); + +app.action('button_click', async ({ body, ack, say }) => { + // Acknowledge the action + await ack(); + await say(`<@${body.user.id}> clicked the button`); +}); + +// Listens to incoming messages that contain "goodbye" +app.message('goodbye', async ({ message, say }) => { + // say() sends a message to the channel where the event was triggered + await say(`See ya later, <@${message.user}> :wave:`); +}); + +(async () => { + // Start your app + await app.start(process.env.PORT || 3000); + + console.log('⚡️ Bolt app is running!'); +})(); \ No newline at end of file diff --git a/examples/getting-started-with-heroku/package.json b/examples/getting-started-with-heroku/package.json new file mode 100644 index 000000000..b1286ef1d --- /dev/null +++ b/examples/getting-started-with-heroku/package.json @@ -0,0 +1,15 @@ +{ + "name": "bolt-js-getting-started-with-heroku-app", + "version": "1.0.0", + "description": "Getting Started with Heroku ⚡️ Bolt for JavaScript", + "main": "app.js", + "scripts": { + "ngrok": "ngrok http 3000", + "start": "node app.js", + "test": "echo \"Error: no test specified\" && exit 1" + }, + "license": "MIT", + "dependencies": { + "@slack/bolt": "^2.3.0" + } +}