development.md

Development

Tech Stack

• Go
• PostgreSQL
• Vanilla JS
• Tailwind CSS
• OpenTelemetry
• Slack

Design Philosophy

Chat Roulette for Slack was designed to be able to run on the free tier of the various PaaS providers such as Heroku, fly.io, render, etc. The compiled binary is completely standalone with all required files baked into it using embed.FS. The only dependency is PostgreSQL. The application is horizontally scalable.

An effort was made to limit storing any personally identifiable information in the database. Only Slack identifiers (eg, U0123456789) are saved and not display names (eg, @bincyber). For privacy and security reasons, all user data is encrypted at rest using Column-level encryption with 256-bit AES in Galois/Counter Mode (GCM).

Components

The application consists of two components:

1. a web server which receives and handles events and interactions from Slack

2. a background worker which processes jobs in a PostgreSQL queue

Database Schema

Local Development

Install Dependencies

For local development, docker and ngrok need to be installed. Docker is used to run the PostgreSQL server. ngrok is used to create a HTTPS tunnel enabling Slack to send webhooks to the application.

The following tools are also required:

• golangci-lint
• migrate
• gotestsum

To install these tools to $GOPATH/bin, run the following command:

make go/tools

Start ngrok

Start an https tunnel using ngrok with the following command:

make ngrok

Copy the generated forwarding URL:

ngrok by @inconshreveable                                                                     (Ctrl+C to quit)

Session Status                online
Account                       bincyber (Plan: Free)
Version                       3.14.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://36a1-5-193-74-226.ngrok-free.app -> http://localhost:8080

Install the Slack App

To install the Chat Roulette for Slack app in your Slack workspace, do the following:

1. Visit https://api.slack.com/apps and generate an App Configuration token:

Copy the access token:

2. Run the app-manifest-installer CLI to install the Slack app using the provided App Manifest:

go run cmd/app-manifest/main.go -u <NGROK URL HERE> -t <xoxe.xoxp-1-SlackAppConfigurationAccessTokenHere>

3. Refresh your browser to view the new Slack app, then click on it. Scroll down to Display Information and click on Add App Icon to set the image for the bot:

Upload the image in docs/images/bot-icon.png.

4. On the left-hand menu under Features, click on OAuth & Permissions. Click the Install to Workspace button to install the Chat Roulette for Slack app to your Slack Workspace.

You will need to accept the requested permissions:

Note: You will need sufficient permissions on your Slack workspace to install the app and complete the above step.

5. Copy the Bot User OAuth Token. Open the config.json file and set the copied bot token for the value "auth_token".

6. On the left-hand menu under Features, click on App Manifest. After the app is deployed to fly.io, you will need to verify URL ownership by clicking on the button in the banner.

Launch the Development Environment

To bring up the development environment:

make dev/up

This will start the PostgreSQL server in a Docker container, execute database migration, and run the Go app on your machine.

To restart the application, press Ctrl+C and then:

make go/run

To terminate the development environment:

make dev/destroy

Enabling Tracing

This application is instrumented with OpenTelemetry to emit traces to Honeycomb or Jaeger.

Tracing can be enabled by adding the following settings to the config file:

Honeycomb

  "tracing": {
    "enabled": true,
    "exporter": "honeycomb",
    "honeycomb": {
      "team": "honeycomb-api-key-here",
      "dataset": "chat-roulette"
    }
  }

Jaeger

  "tracing": {
    "enabled": true,
    "exporter": "jaeger",
    "jaeger": {
      "endpoint": "http://localhost:4318/api/traces"
    }
  }

Testing

To run the test suite:

make go/testsum

Some tests use ory/dockertest which requires access to the Docker socket (ie, /var/run/docker.sock).