Installation - jcraigk/kudochest-slack GitHub Wiki

Components

Setting up KudoChest for your organization requires the following:

  • A Slack workspace where you have permission to install apps
  • A Slack App to act as the chatbot
  • A web server running the Ruby on Rails app  
     

Slack App

First, you'll need to setup a Slack App. Follow these instructions: Slack App Setup    

Web Server

The web server will be running the following components. You can split these out into different servers if you wish, but for single team installations, it is not recommended.

  • Postgres
  • Redis
  • Rails (Puma) web server
  • Sidekiq

For a quick start guide, see DigitalOcean Dokku Deploy.

First, you'll need to host the KudoChest Ruby on Rails app. You may host it on a public server, but enterprises should host it on an internal private network. In that case, the Slack webhook endpoints must be able to received traffic from the public web (https://<your-kudochest-domain/hooks/slack).

A single KudoChest server can handle multiple workspaces, but by default it assumes a single team installation. If you want to allow more than one installation, set the MAX_TEAMS environment variable to an integer of your choice.  
 

Environment Variables

Environment variables may be provided in a .env file if developing locally.

First, you must generate a secret with rails secret and assign it to RAILS_SECRET_KEY_BASE.

You must set RAILS_ENV to production in production environments.

You may provide DATABASE_URL or [DB_USER, DB_PASS, DB_HOST, and DB_NAME] via environment variables. You may also directly edit config/database.yml.

You may provide REDIS_URL or leave it blank for default localhost:6379.

For privacy reasons, the default log level in production is error. You may change this by passing in a different value as LOG_LEVEL.

Provide the following to enable the web UI where app administration takes place. For local development, these will likely be ASSET_HOST=http://localhost:3000 and WEB_DOMAIN=localhost:3000. Better yet, use an ngrok tunnel.

For production deploys, a sensible solution would be to use a subdomain on your organization's primary domain, such as kudochest.my-company.com or kudos.my-company.com.

ASSET_HOST
WEB_DOMAIN

STMP config must be provided to enable email-based login, password reset, and weekly reports. You may use an external service such as SendGrid or you may provide your own SMTP server.

SMTP_ADDRESS
SMTP_DOMAIN
SMTP_PASSWORD
SMTP_USERNAME

After you create a Slack App for your workspace, provide its details in the following variables. Make sure you set config.bot_name in config/application.rb accordingly if you don't want it to be called KudoChest. For a detailed guide, see Slack App Setup.

SLACK_APP_ID
SLACK_CLIENT_ID
SLACK_CLIENT_SECRET
SLACK_SIGNING_SECRET

If you want to change any of the default app config, provide custom values for the following:

MAX_TEAMS
APP_NAME
BOT_NAME
WEB_DOMAIN
FROM_EMAIL
POINT_TERM
POINTS_TERM
POINT_SINGULAR_PREFIX
JAB_TERM
JABS_TERM
JAB_SINGULAR_PREFIX

 

Fine Tuning

Most of the app's basic settings are configured in config/application.rb. It is worth browsing the list of configuration options to get a sense of the features and to help debug issues that may arise.  
 

Periodic Jobs

You'll want to configure when WeeklyReport::RecurrentWorker runs in config/sidekiq.yml or disable it. The weekly report requires working SMTP configuration (see above).  
 

Administration

Once the server is running, login and click the "Add to Slack" button. After confirming the installation and being redirected back to the website, you are now the sole administrator of the app. Click your email address in the upper right and select "App Settings". From here you can control various aspects of the user experience. Click on "Administration" under "App Settings" to add other administrators.  
 

To monitor Sidekiq asynchronous jobs, view the web UI at /sidekiq. You must be logged in as a user with the superuser attribute set to true. This can be done through the Rails console.