README

Beehive

Beehive is an event and agent system, which allows you to create your own agents that perform automated tasks triggered by events and filters. It is modular, flexible and really easy to extend for anyone. It has modules (we call them Hives), so it can interface with, talk to, or retrieve information from Twitter, Tumblr, Email, IRC, Jabber, RSS, Jenkins, Hue - to name just a few. Check out the full list of available Hives in our Wiki.

Connecting those modules with each other lets you create immensly useful agents.

Here are just a few examples of things Beehive could do for you:
  • Re-post tweets on your Tumblr blog
  • Forward incoming chat messages to your email account
  • Turn on the heating system if the temperature drops below a certain value
  • Run your own IRC bot that lets you trigger builds on a Jenkins CI
  • Control your Hue lighting system
  • Notify you when a stock's price drops below a certain value

beehive's Logo

Installation

Packages & Binaries

You can find even more official releases here.

Deployment Tools
  • Docker: docker run --name beehive -d -p 8181:8181 fribbledom/beehive
  • Ansible
From source

Beehive requires Go 1.11 or higher. Make sure you have a working Go environment. See the install instructions.

The recommended way is to fetch the sources and run make.

git clone https://github.com/muesli/beehive.git
cd beehive
make

You can build and install the beehive binary like other Go binaries out there (go get) but you'll need to make sure Beehive can find the assets (images, javascript, css, etc). See the Troubleshooting/Notes section for additional details.

Run beehive --help to see a full list of options.

Configuration

Think of Hives as little plugins, extending Beehive's abilities with events you can react on and actions you can execute.

Just as examples, there's a Twitter plugin that can

  • react to someone you follow posting a tweet (an event)
  • post a new tweet for you (an action)
  • ...

or an RSS plugin that lets you

  • monitor RSS feeds and react on new feed items (another event)

or an email plugin that gives you the ability to

  • send emails (another action)

Each Hive lets you spawn one or multiple Bees in it, all working independently from another. That allows you to create separate plugin instances, e.g. one email-Bee for your private mail account, and another one for your work email.

Creating Bees

Sounds complicated? It's not! Just for fun, let's setup Beehive to send us an email whenever an RSS feed gets updated. Start beehive and open http://localhost:8181/ in your browser. Note that Beehive will create a config file beehive.conf in its current working directory, unless you specify a different file with the -config option.

Note: If you built Beehive with go build instead of make you will have to start beehive from within its source directory in order for it to find all the resources for the admin interface. Also see the Troubleshooting & Notes section of this README.

The admin interface will present you with a list of available Hives. We will need to create two Bees here, one for the RSS feed and one for your email account.

New Bees

Setting up a Chain

Now we will have to create a new Chain, which will wire up the two Bees we just created. First we pick the Bee & Event we want to react on, then we pick the Bee we want to execute an Action with. The RSS-Bee's event gives us a whole set of parameters we can work with: the feed item's title, its links and description among others. You can manipulate and combine these parameters with a full templating language at your disposal. For example we can set the email's content to something like:

Title: {{.title}} - Link: {{index .links 0}}

Whenever this action gets executed, Beehive will replace {{.title}} with the RSS event's title parameter, which is the title of the feed item it retrieved. In the same manner {{index .links 0}} becomes the first URL of this event's links array.

New Chain

That's it. Whenever the RSS-feed gets updated, Beehive will now send you an email! It's really easy to make various Bees work together seamlessly and do clever things for you. Try it yourself!

You can find more information on how to configure Beehive and examples in our Wiki.

Troubleshooting & Notes

The web interface and other resources are embedded in the binary by default. When using make noembed, Beehive tries to find those files in its current working directory, so it's currently recommended to start Beehive from within its git repository, if you plan to use the web interface.

Should you still not be able to reach the web interface, check if the config directory in the git repository is empty. If that's the case, make sure the git submodules get initialized by running git submodule update --init.

The web interface does not require authentication yet. Beehive by default accepts all connections from the loopback device only.

If you want to bind Beehive to a different interface/address, run Beehive with the -bind and -canonicalurl parameters. For example:

beehive -bind "192.168.0.1:8181" -canonicalurl "http://192.168.0.1:8181"

or

docker run --name beehive -d -e CANONICAL_URL="http://192.168.0.1:8181" -p 8181:8181 fribbledom/beehive

Development

Need help? Want to hack on your own Hives? Join us on IRC (irc://freenode.net/#beehive) or Gitter. Follow the bees on Twitter!

GoDoc Build Status Go ReportCard

Expand ▾ Collapse ▴

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
api Package api is Beehive's RESTful api for introspection and configuration go-bindata (https://github.com/kevinburke/go-bindata) stub so beehive also works without embedded assets.
api/context
api/resources/actions
api/resources/bees
api/resources/chains
api/resources/hives
api/resources/logs
app Package app is Beehive's application container.
bees Package bees is Beehive's central module system.
bees/alertoverbee Package alertoverbee is able to send notifications on AlertOver.
bees/anelpowerctrlbee Package anelpowerctrlbee is a Bee for talking to Anel's PowerCtrl network power sockets.
bees/cfddnsbee
bees/cleverbotbee Package cleverbotbee is a Bee that can interact with cleverbot
bees/cricketbee
bees/cronbee Package cronbee is a Bee that acts like a time-based job scheduler (cron).
bees/cronbee/cron Package cron allows you to schedule events.
bees/devrantbee Package devrantbee is a Bee that can post blogs & quotes on Devrant.
bees/discordbee Package discordbee is a bee for sending and receiving messages with Discord servers.
bees/efabee Package efabee is a Bee that interfaces with the public EVA API.
bees/emailbee Package emailbee is a Bee that is able to send emails.
bees/emailserverbee
bees/execbee Package execbee is a Bee that can launch external processes.
bees/facebookbee Package facebookbee is a Bee that can interface with Facebook.
bees/fsnotifybee
bees/githubbee Package githubbee is a Bee that can interface with GitHub Package githubbee is a Bee that can interface with GitHub Package githubbee is a Bee that can interface with GitHub
bees/gitterbee Package gitterbee is a Bee that can interface with Gitter Package gitterbee is a Bee that can interface with Gitter
bees/hellobee Package hellobee is an example for a Bee skeleton, designed to help you get started with writing your own Bees.
bees/horizonboxbee
bees/htmlextractbee Package htmlextractbee is a Bee that can extract metadata from HTTP URLs.
bees/httpbee Package httpbee is a Bee that lets you trigger HTTP requests.
bees/huebee Package huebee is a Bee that can talk to Philips Hue bridges.
bees/instapaperbee
bees/ipifybee
bees/ircbee Package ircbee is a Bee that can connect to an IRC server.
bees/ircbee/irctools Package irctools is a collection of convenient IRC styling methods.
bees/jabberbee Package jabberbee is a Bee that can connect to a Jabber/XMPP server.
bees/jenkinsbee Package jenkinsbee is a Bee that can interface with a Jenkins server.
bees/mastodonbee * Copyright (C) 2020 Christian Muehlhaeuser * 2020 Nicolas Martin * * 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.
bees/mixcloudbee
bees/mumblebee Package mumblebee is a Bee that can connect to a Mumble/XMPP server.
bees/nagiosbee Package nagiosbee is a Bee that can interface with a Nagios instance.
bees/notificationbee Package notificationbee is a Bee that can trigger desktop notifications.
bees/openweathermapbee Package openweathermapbee is a Bee that can interact with cleverbot
bees/pastebinbee Package pastebinbee is a Bee that can interface with Pastebin.
bees/prometheusbee Package prometheusbee is a bee designed to expose metrics for scraping by Prometheus.
bees/pushoverbee Package pushoverbee is a Bee that can send pushover notifications.
bees/rocketchatbee Package rocketchatbee is a Bee that can connect to Rocketchat.
bees/rssbee Package rssbee is a Bee for handling RSS feeds.
bees/s3bee
bees/serialbee Package serialbee is a Bee that can send & receive data on a serial port.
bees/simplepushbee Package simplepushbee is a Bee that is able to send push notifications to Android.
bees/slackbee Package slackbee is a Bee that can connect to Slack.
bees/socketbee Package socketbee is a Bee that lets you transmit data via UDP sockets.
bees/spaceapibee Package spaceapibee is a Bee that can query a spaceapi server.
bees/telegrambee Package telegrambee is a Bee that can connect to Telegram.
bees/timebee Package timebee is a Bee that can fire events at a specific time.
bees/transmissionbee Package transmissionbee is a Bee that can send torrents to Transmission.
bees/travisbee Package travisbee is a bee for monitoring and reacting to the status of TravisCI builds.
bees/tumblrbee Package tumblrbee is a Bee that can post blogs & quotes on Tumblr.
bees/twiliobee Package twiliobee is a Bee that is able to send SMS messages.
bees/twitchbee Package twitchbee is a Bee that can connect to Twitch.
bees/twitterbee Package twitterbee is a Bee that can interface with Twitter.
bees/webbee Package webbee is a Bee that starts an HTTP server and fires events for incoming requests.
cfg
filters Package filters contains Beehive's filter system.
filters/template Package templatefilter provides a template-based filter.
templatehelper Package templatehelper provides a func-map of common template functions