OpenCompany Interaction Service
Tell the truth about any situation and you are delivered from lack of progress, but become hypocritical or lying, and you may be in bondage for life.
-- Auliq Ice
Teams struggle to keep everyone on the same page. People are hyper-connected in the moment with chat and email, but it gets noisy as teams grow, and people miss key information. Everyone needs clear and consistent leadership, and the solution is surprisingly simple and effective - great leadership updates that build transparency and alignment.
With that in mind we designed Carrot, a software-as-a-service application powered by the open source OpenCompany platform and a source-available web UI.
With Carrot, important company updates, announcements, stories, and strategic plans create focused, topic-based conversations that keep everyone aligned without interruptions. When information is shared transparently, it inspires trust, new ideas and new levels of stakeholder engagement. Carrot makes it easy for leaders to engage with employees, investors, and customers, creating alignment for everyone.
Transparency expectations are changing. Organizations need to change as well if they are going to attract and retain savvy teams, investors and customers. Just as open source changed the way we build software, transparency changes how we build successful companies with information that is open, interactive, and always accessible. Carrot turns transparency into a competitive advantage.
To get started, head to: Carrot
The OpenCompany Interaction Service handles reading, writing and propagating user comments and reactions.
Prospective users of Carrot should get started by going to Carrot.io. The following local setup is for developers wanting to work on the OpenCompany Interaction Service.
Most of the dependencies are internal, meaning Leiningen will handle getting them for you. There are a few exceptions:
- Java - a Java 8+ JRE is needed to run Clojure
- Leiningen 2.9.1+ - Clojure's build and dependency management tool
- RethinkDB v2.3.6+ - a multi-modal (document, key/value, relational) open source NoSQL database
Your system may already have Java 8+ installed. You can verify this with:
java -versionIf you do not have Java 8+ download it and follow the installation instructions.
An option we recommend is OpenJDK. There are instructions for Linux and Homebrew can be used to install OpenJDK on a Mac with:
brew update && brew cask install adoptopenjdk8
Leiningen is easy to install:
- Download the latest lein script from the stable branch.
- Place it somewhere that's on your $PATH (
env | grep PATH)./usr/local/binis a good choice if it is on your PATH. - Set it to be executable.
chmod 755 /usr/local/bin/lein - Run it:
leinThis will finish the installation.
Then let Leiningen install the rest of the dependencies:
git clone https://github.com/open-company/open-company-interaction.git
cd open-company-interaction
lein depsRethinkDB is easy to install with official and community supported packages for most operating systems.
Assuming you are running Mac OS X and are a Homebrew user, use brew to install RethinkDB:
brew update && brew install rethinkdbIf you already have RethinkDB installed via brew, check the version:
rethinkdb -vIf it's older, then upgrade it with:
brew update && brew upgrade rethinkdb && brew services restart rethinkdbFollow the instructions provided by brew to run RethinkDB every time at login:
ln -sfv /usr/local/opt/rethinkdb/*.plist ~/Library/LaunchAgentsAnd to run RethinkDB now:
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.rethinkdb.plistVerify you can access the RethinkDB admin console:
open http://localhost:8080/After installing with brew:
- Your RethinkDB binary will be at
/usr/local/bin/rethinkdb - Your RethinkDB data directory will be at
/usr/local/var/rethinkdb - Your RethinkDB log will be at
/usr/local/var/log/rethinkdb/rethinkdb.log - Your RethinkDB launchd file will be at
~/Library/LaunchAgents/homebrew.mxcl.rethinkdb.plist
If you don't use brew, there is a binary installer package available for Mac OS X from the Mac download page.
After downloading the disk image, mounting it (double click) and running the rethinkdb.pkg installer, you need to manually create the data directory:
sudo mkdir -p /Library/RethinkDB
sudo chown <your-own-user-id> /Library/RethinkDB
mkdir /Library/RethinkDB/dataAnd you will need to manually create the launchd config file to run RethinkDB every time at login. From within this repo run:
cp ./opt/com.rethinkdb.server.plist ~/Library/LaunchAgents/com.rethinkdb.server.plistAnd to run RethinkDB now:
launchctl load ~/Library/LaunchAgents/com.rethinkdb.server.plistVerify you can access the RethinkDB admin console:
open http://localhost:8080/After installing with the binary package:
- Your RethinkDB binary will be at
/usr/local/bin/rethinkdb - Your RethinkDB data directory will be at
/Library/RethinkDB/data - Your RethinkDB log will be at
/var/log/rethinkdb.log - Your RethinkDB launchd file will be at
~/Library/LaunchAgents/com.rethinkdb.server.plist
If you run Linux on your development environment (good for you, hardcore!) you can get a package for you distribution or compile from source. Details are on the installation page.
RethinkDB isn't supported on Windows directly. If you are stuck on Windows, you can run Linux in a virtualized environment to host RethinkDB.
A secret is shared between the Interaction service and the Authentication service for creating and validating JSON Web Tokens.
An AWS SQS queue is used to pass messages to the Interaction service from Slack. Setup an SQS Queue and key/secret access to the queue using the AWS Web Console or API.
Go to the AWS SQS Console and select the SQS queue configured above. From the 'Queue Actions' dropdown, select 'Subscribe Queue to SNS Topic'. Select the SNS topic you've configured your Slack Router service instance to publish to, and click the 'Subscribe' button.
Make sure you update the CHANGE-ME items in the section of the project.clj that looks like this to contain your actual JWT, and AWS secrets:
;; Dev environment and dependencies
:dev [:qa {
:env ^:replace {
:db-name "open_company_storage_dev"
:liberator-trace "true" ; liberator debug data in HTTP response headers
:hot-reload "true" ; reload code when changed on the file system
:open-company-auth-passphrase "this_is_a_dev_secret" ; JWT secret
:aws-access-key-id "CHANGE-ME"
:aws-secret-access-key "CHANGE-ME"
:aws-sns-interaction-topic-arn "" ; SNS topic to publish notifications (optional)
:log-level "debug"
}An optional AWS SNS pub/sub topic is used to push notifications of interaction changes to interested listeners. If you want to take advantage of this capability, configure the aws-sns-interaction-topic-arn with the ARN (Amazon Resource Name) of the SNS topic you setup in AWS.
Run the interaction service with: lein start
Or start a REPL with: lein repl
Next, you can try some things with Clojure by running the REPL from within this project:
lein migrate-db
lein replThen enter these commands one-by-one, noting the output:
;; start the development system
(go) ; NOTE: if you are already running the service externally to the REPL, use `(go 3737)` to change the port
;; create some interactions
(def author {
:user-id "c133-43fe-8712"
:teams ["f725-4791-80ac"]
:name "Wile E. Coyote"
:first-name "Wile"
:last-name "Coyote"
:avatar-url "http://www.emoticonswallpapers.com/avatar/cartoons/Wiley-Coyote-Dazed.jpg"
:email "wile.e.coyote@acme.com"
:auth-source "slack"
})
(interaction/create-comment! conn
(interaction/->comment {:org-uuid "abcd-1234-abcd"
:board-uuid "1234-abcd-1234"
:resource-uuid "abcd-5678-abcd"
:body "That all looks great to me!"} author))
(interaction/create-reaction! conn
(interaction/->reaction {:org-uuid "abcd-1234-abcd"
:board-uuid "1234-abcd-1234"
:resource-uuid "abcd-5678-abcd"
:reaction "😀"} author))
(interaction/create-comment-reaction! conn
(interaction/->comment-reaction {:org-uuid "abcd-1234-abcd"
:board-uuid "1234-abcd-1234"
:resource-uuid "abcd-5678-abcd"
:interaction-uuid "5678-abcd-5678"
:reaction "👌"} author))The interaction service is composed of 4 main responsibilities:
- CRUD of comments and reactions
- WebSocket notifications of comment and reaction CRUD to listening clients
- Publishing comment and reaction change notifications to interested subscribers via SNS
The Interaction Service shares a RethinkDB database instance with the Storage Service.
Tests are run in continuous integration of the master and mainline branches on Travis CI:
To run the tests locally:
lein kibit
lein eastwoodPlease note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Distributed under the GNU Affero General Public License Version 3.
Copyright © 2015-2021 OpenCompany, LLC.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.