Skip to content
This repository has been archived by the owner on Dec 14, 2022. It is now read-only.

Latest commit

 

History

History
165 lines (126 loc) · 5.67 KB

CONTRIBUTING.md

File metadata and controls

165 lines (126 loc) · 5.67 KB
Raw

Environment Setup

SlashDeploy uses a Gemfile to document dependencies.

The following external dependencies are also required:

  • Postgresql 9.6
  • Redis
  • Ruby 2.6.7 (optionally rbenv)
  • bundler

macOS

  1. install brew
  2. install PostgreSQL 9: brew install [email protected]
  3. start PostgreSQL 9 : brew services start [email protected]
  4. install rbenv: brew install rbenv
  5. install bundler: gem install bundler

Linux

  1. TODO

Install SlashDeploy

  1. clone slashdeploy: git clone [email protected]:remind101/slashdeploy.git
  2. change dir to project root: cd slashdeploy
  3. install slashdeploy: bundle install
  4. create database schema: bundle exec rake db:setup
  5. migrate database schema: bundle exec rake db:migrate

Tests

The full test suite can be run with:

./bin/rake

Docker

You can also use Docker for development and testing:

make dev  # run the whole stack containerized
make test # run the test suite

Read on for more details about how to set up a full dev environment below.

Development

The basic process is to set up a Slack app and GitHub app which you will need to authenticate with in order to facilitate communication between them. Because you're setting this up locally, you need a way for Slack and GitHub to reach your development server, which is achieved via Ngrok. Ngrok will open a reverse proxy connection to an Ngrok server, which will proxy traffic back to your local machine over a secure tunnel. This both provides a publicly routable address that services like GitHub, Slack and users can reach, and also provides valid TLS encryption for the connection, all the way back to your local server (provided you trust Ngrok, since they're essentially performing MITM on your traffic).

Start Ngrok

IMPORTANT! Ngrok will provide you with both an HTTP and HTTPS URL; make sure you're using the HTTPS version everywhere.

  1. Install ngrok if you don't already have it. Put it somewhere in your PATH.
  2. Run make ngrok. This will start proxying traffic to localhost:3000.

Set up .env

  1. Create an .env file in the root of the repository. This file will be ignored via .gitignore, and is for storing credentials/secrets for your development instance. Start with:
STATE_KEY=""

# the ngrok.io URI. Make sure this is HTTPS!
URL="https://xxx.ngrok.io"

You'll continue adding configuration to this file as we proceed.

Create a Slack App

  1. Create a New Slack Workspace. This is important! If you install the app we're about to create in an existing/production workspace, you'll conflict with the existing SlashDeploy installation, and expose your dev environment to everyone in the workspace. Additionally, you must create the workspace and be signed into the new workspace when you create the Slack app. Slack will not allow you to install the app to another workspace without publishing it.
  2. Create a Slack App
  3. Select 'Slash Commands' from the left sidebar, under the 'Features' heading
    1. Select 'Create New Command'
    2. Enter the following information: Command | /deploy Request URL | https://xxx.ngrok.io/slack/commands Short Description | SlashDeployyour name Usage Hint | Whatever you like Escape channels, users, and links sent to your app | unchecked
    3. Important! Make sure to click 'Save' down in the lower right
  4. Select 'OAuth & Permissions' from the left sidebar, under the 'Features' heading
    1. Select the 'Add New Redirect URL' button under the 'Redirect URLs' section
    2. Set the Redirect URL to https://xxx.ngrok.io/auth/slack/callback
    3. Click the 'Add' button
    4. Click the 'Save' button
  5. Select 'Interactivity & Shortcuts' from the left sidebar, under the 'Features' heading
    1. Turn the feature on with the toggle button
    2. Set the Interactivity Request URL to https://xxx.ngrok.io/slack/actions
    3. Important! Make sure to click 'Save' down in the lower right
  6. Select 'Install App' from the left sidebar, under the 'Settings' heading
    1. Click the 'Install App to Workspace' and add the app to your workspace of choice. Remember, you can only install an app to the workspace specified when you created it.
  7. Select 'Basic Information' from the left sidebar under the 'Settings' heading
    1. Set the following variables in your .env file: 
      SLACK_CLIENT="slack"
SLACK_CLIENT_ID="<Client ID>"
SLACK_CLIENT_SECRET="<Client Secret>"
SLACK_VERIFICATION_TOKEN="<Verification Token>"

Create a Github OAuth App

  1. Register a new Github OAuth Application, using the following config: Application name | Same as the name of your Slack app Homepage URL | https://xxx.ngrok.io Application description | Whatever you want Authorization callback URL | https://xxx.ngrok.io/auth/github/callback
  2. Click 'Create' button
  3. The next screen should have the integration config. Set the following variables in your .env file: 
    GITHUB_CLIENT="github"
GITHUB_CLIENT_ID="<Client ID>"
GITHUB_CLIENT_SECRET="<Client Secret>"

Start the Development server

You can run the development server locally:

  • foreman start -p 3000

Or use Docker:

  • make dev

Visit the App

  1. You can now visit https://xxx.ngrok.io and connect the app. The first time you attempt to use the /deploy command from your test Slack workspace, you'll be asked to authenticate with GitHub.