-
Notifications
You must be signed in to change notification settings - Fork 3
Installation
Setting up KudoChest for your organization requires the following:
- A Slack or Discord workspace where you have permission to install apps
- A Slack or Discord App to act as the bot
- A web server running the Ruby on Rails app and dependencies (https://github.com/jcraigk/kudochest)
First, you'll need to setup the chat client App at their website:
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 server
- Discord Gateway Listener (only if integrating with Discord)
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, in which case you may want to restrict logins to only those from your organization. In config/application.rb, see the config.user_email_domains setting. Enter the domain(s) for your organization's email, such as my-company.com to restrict sign up and login to those email addresses.
The KudoChest server can handle multiple teams across multiple chat clients, but by default it assumes a single team installation. If you want to allow more than one installation, change config.max_teams in config/application.rb. Installations occur on a "first come first serve" basis so as long as you are the first user to login to the website and install the app in your workspace, all other users who login will not be presented with the option to install as long as config.max_teams is kept at the default 1.
You may also host the Rails portion on an internal server, requiring VPN or other network-based access. The only endpoints that need to be exposed to the web are:
- Slack webhook endpoints (
https://<your-kudochest-domain/hooks/slack) if you are integrating with Slack - OAuth callback endpoints (
https://<your-kudochest-domain/oauth) if you are supporting OAuth logins
Note that all Slack interactions occur through their REST API and webhooks, whereas most interactions for Discord are handled via WebSocket connection. So depending on your use case, you will be enabling Slack webhooks or running the Discord Gateway Listener. For multi-team installations, you may use both.
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
If you are working on Slack integration, create a Slack App specifically for development and provide its details in the following variables. Make sure you set config.bot_name in config/application.rb accordingly. For a detailed guide, see Slack App Setup.
SLACK_APP_ID
SLACK_CLIENT_ID
SLACK_CLIENT_SECRET
SLACK_SIGNING_SECRET
If you are working on Discord integration, create a Discord App specifically for development and provide its details in the following variables. Make sure you set config.bot_name in config/application.rb accordingly. You'll also want to fire up the Discord Gateway Listener from a fresh terminal using bin/discord_listener. For a detailed guide, see Discord App Setup.
DISCORD_APP_USERNAME
DISCORD_BOT_TOKEN
DISCORD_CLIENT_ID
DISCORD_CLIENT_SECRET
DISCORD_LISTENER_STARTUP_DELAY
DISCORDRB_NONACL=true
If you are working on OAuth integration, create the appropriate apps in the third party services and provide their values. You'll need to add each provider name to a comma-separated list and provide as OAUTH_PROVIDERS=facebook,google, for example. Note that OAuth integrations are automatically disabled if USER_EMAIL_DOMAINS is provided (also a comma-separated list).
OAUTH_PROVIDERS
OAUTH_FACEBOOK_KEY
OAUTH_FACEBOOK_SECRET
OAUTH_GOOGLE_KEY
OAUTH_GOOGLE_SECRET
For working on graphical image responses, setup an AWS bucket to cache the composed images and provide the details.
AWS_REGION
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
RESPONSE_IMAGE_AWS_BUCKET
RESPONSE_IMAGE_HOST
For response image construction/caching, you'll need a disk volume that the Sidekiq service can write to. In the docker-compose.yml file, configure the volume property of the sidekiq service, replacing the default /tmp like so:
services:
sidekiq:
volumes:
- [/your/local/path]:/storage
If you want to change any of the default app config, provide custom values for the following:
SHARED_ADMIN
APP_NAME
BOT_NAME
BASE_URL
FROM_EMAIL
POINT_TERM
POINTS_TERM
SINGULAR_PREFIX
For error tracking, Honeybadger is provided by default. You can activate it by providing your api key:
HONEYBADGER_API_KEY
In config/application.rb you'll want to ensure that the Access Control section reflects the best configuration for your deploy, which you can provide by passing in environment variables.
For single-team installs, leave MAX_TEAMS at the default 1. After the first install occurs, no other users will be prompted to install when they login. Alternatively, if you want to administrate multiple KudoChest installs from a single server, increase MAX_TEAMS.
If you are hosting the app on a public web server and your organization uses a dedicated email domain such as my-company.com, consider limiting logins to emails at that domain using the USER_EMAIL_DOMAINS array. This will automatically disable all OAuth integrations if any domains are specified.
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.
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).
Once the server is running, login and click the "Add to Slack" or "Add to Discord" 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.
For a detailed guide, see Administration.
Just like any other user, you may use the connect command to connect your profile so that your dashboard displays your progress.
If you want to install the app in multiple workspaces under the same admin login, go to "App Settings" and click the team name in the upper left, then click "Install KudoChest" or visit https://<your-kudochest-domain>/teams/new. Ensure that config.max_teams is greater than 1 in config/application.rb.
To monitor Sidekiq asynchronous jobs, view the web UI at /sidekiq. You must be logged in as a user with the admin attribute set to true. This can be done through the Rails console.
After installing and configuring the app, you'll likely want to let your users know about it and encourage them to use the website to view their progress. See Onboarding for helpful materials.