Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#220] Add deployment guide for Heroku #651

Merged
merged 33 commits into from
Oct 7, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
73b250c
[#220] Create deployments section with empty Heroku article.
mwbrooks Sep 14, 2020
dc1a5e1
[#220] Add 'Setup Heroku tools' section
mwbrooks Sep 14, 2020
aa8acdf
[#220] Update 'Setup the Heroku tools' section
mwbrooks Sep 15, 2020
418fba6
[#220] Add 'Get the Bolt Slack app' section
mwbrooks Sep 15, 2020
09b2ff5
[#220] Outline prepare, deploy, and next steps.
mwbrooks Sep 15, 2020
14ba96c
[#220] Update side bar to be 'Deploying'
mwbrooks Sep 15, 2020
302b6b4
[#220] Move getting and preparing an app to the top sections.
mwbrooks Sep 18, 2020
0168cb8
[#220] Update introduction
mwbrooks Sep 18, 2020
25d4bad
[#220] Update 'Get a Bolt Slack app' section
mwbrooks Sep 18, 2020
fa62107
[#220] Update 'Preparing app for Heroku'
mwbrooks Sep 18, 2020
7550580
[#220] Update the deploy sections
mwbrooks Sep 23, 2020
f85451c
[#220] Update all sections leading up to 'Deploy'
mwbrooks Sep 24, 2020
cbf008a
[#220] Add the Deploy and Next Steps sections.
mwbrooks Sep 24, 2020
6be8739
[#220] Add environment variable section.
mwbrooks Sep 24, 2020
b2e38f4
[#220] Add images for updating the Slack settings.
mwbrooks Sep 24, 2020
b9060b7
[#220] Update GitHub URLs and minor edits.
mwbrooks Sep 28, 2020
17c9f63
[#220] Link to Getting Started with Heroku app
mwbrooks Sep 28, 2020
bac2cd5
[#220] Fix link to Getting Started guide
mwbrooks Sep 29, 2020
be1cafa
[#220] Update Japanese side bar to be consistent with English
mwbrooks Sep 29, 2020
95973f2
[#220] Update /deployments to /deploying for consistency
mwbrooks Sep 29, 2020
a8d2ff1
[#220] Update copy after running through guide end-to-end
mwbrooks Sep 29, 2020
f6eed4f
[#220] Update section and path from 'deploying' to 'deployments'
mwbrooks Oct 2, 2020
6b1d331
[#220] Make Deployments section conditional on having content in lang
mwbrooks Oct 2, 2020
bd33267
[#220] Update intro for getting a Bolt app.
mwbrooks Oct 5, 2020
53a2cfa
[#220] Update explaining how to clone and change into the Bolt app.
mwbrooks Oct 5, 2020
21cdcc2
[#220] Remove unnecessary hint about using an existing app.
mwbrooks Oct 5, 2020
2f4ea61
[#220] Update with feedback from @shaydewael
mwbrooks Oct 6, 2020
dff63f8
[#220] Update based on feedback from @misscoded
mwbrooks Oct 6, 2020
f234481
[#220] Bundle getting-started-with-heroku example app
mwbrooks Oct 6, 2020
4589589
[#220] Update description of example app
mwbrooks Oct 6, 2020
f1e16a2
[#220] Update references to slackapi/bolt-js-getting-started-app
mwbrooks Oct 6, 2020
8cc9d8e
[#220] Fix typos and minor updates.
mwbrooks Oct 6, 2020
bb88411
[#220] Fix formatting of tutorials in sidebar.html
mwbrooks Oct 7, 2020
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/_config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -15,6 +15,8 @@ collections:
output: false
steps:
output: false
deployments:
output: true
tutorials:
output: true
permalink: /tutorials/:slug
Expand All @@ -34,13 +36,16 @@ t:
advanced: Advanced concepts
start: Getting started
steps: Workflow steps
deployments: Deployments
contribute: Contributing
ja-jp:
basic: 基本的な概念
advanced: 応用コンセプト
start: Bolt 入門ガイド
# TODO: translate this title
steps: Workflow steps
# TODO: translate this title
deployments: Deployments
contribute: 貢献

# Metadata
Expand Down
265 changes: 265 additions & 0 deletions docs/_deployments/heroku.md
Original file line number Diff line number Diff line change
@@ -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

<div class="section-content">
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.
</div>

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=<your-signing-secret>
heroku config:set SLACK_BOT_TOKEN=xoxb-<your-bot-token>
```

> 💡 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
24 changes: 19 additions & 5 deletions docs/_includes/sidebar.html
Original file line number Diff line number Diff line change
Expand Up @@ -62,15 +62,29 @@
{% endfor %}
</ul>

{% assign deployments_sections = site.deployments | sort: "order" | where: "lang", page.lang %}
{% if deployments_sections.size > 0 %}
<ul class="sidebar-section">
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/deployments">
<li class="title">{{ site.t[page.lang].deployments }}</li>
</a>
{% for section in deployments_sections %}
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/deployments/{{ section.slug }}">
<li>{{section.title}}</li>
</a>
{% endfor %}
</ul>
{% endif %}

<ul class="sidebar-section">
{% assign tutorials = site.tutorials | where: "lang", page.lang | where_exp: "tutorial", "tutorial.order > 0" %} {%
for tutorial in tutorials %}
{% assign tutorials = site.tutorials | where: "lang", page.lang | where_exp: "tutorial", "tutorial.order > 0" %}
{% for tutorial in tutorials %}
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/tutorial/{{ tutorial.slug }}">
<li class="title">{{tutorial.title}}</li>
</a>
{% endfor %}
<a href="https://github.com/SlackAPI/bolt-js/blob/master/.github/contributing.md"
><li class="title">{{ site.t[page.lang].contribute }}</li></a
>
<a href="https://github.com/SlackAPI/bolt-js/blob/master/.github/contributing.md">
<li class="title">{{ site.t[page.lang].contribute }}</li>
</a>
</ul>
</div>
Binary file added docs/assets/event-subscriptions-page.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/interactivity-and-shortcuts-page.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions examples/getting-started-with-heroku/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# node / npm
node_modules/
package-lock.json
21 changes: 21 additions & 0 deletions examples/getting-started-with-heroku/LICENSE
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions examples/getting-started-with-heroku/Procfile
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
web: node app.js
Loading