Merge pull request #1 from vcapretz/readme-improvements

readme: improve docs on how to start and use the lib

README.md

@@ -1,48 +1,87 @@
 # bulls-eye 🎯
 
-This package provides a queue manager and a UI to inspect jobs. The manager is based on [bull](https://github.com/OptimalBits/bull) and it depends on redis.
+Bull's Eye is a UI built on top of [Bull](https://github.com/OptimalBits/bull) to help you visualize your queues and their jobs.
 
-## Architecture
+<p align="center">
+  <a href="https://github.com/vcapretz/bulls-eye/blob/master/LICENSE">
+    <img alt="licence" src="https://img.shields.io/npm/l/dockest.svg?style=flat">
+  </a>
+  <a href="https://snyk.io/test/github/vcapretz/bulls-eye">
+    <img alt="snyk" src="https://snyk.io/test/github/vcapretz/bulls-eye/badge.svg">
+  </a>
+<p>
 
-Before using bulls-eye, please consider if it is the right solution for your problem. Here's a bunch of cool things it can do:
+## Starting
 
-- Run arbitrary or scheduled (like in cron) jobs in the background.
-- Set prios, retry, pause, resume and limit the rate of your jobs.
-- Concurrently run in a sandboxed process that will not crash your app.
-- Render a UI in your app with all the info you'll need to manage the jobs.
+To add it to your project start by adding the library to your dependencies list:
 
-Most background jobs tools depend on multiple processes to work. This means you would need to use something like a Procfile to keep your server and all your workers running. bulls-eye will use your node service process as the manager of executions and (if you so wish) spawn child processes in your instances to deal with the workload.
+```sh
+yarn add bulls-eye
+```
 
-On the other hand this is also one of its disadvantages. That is, you probably should not use bulls-eye if:
+Or
 
-- you can't afford your server to be doing something else than serving requests.
-  - in this case, consider having a separate service to be a queue manager, or lambdas.
-- you need to aggressively scale your workers independently of your instances.
-  - in this case, probably lambdas.
-- all you need is a simple cron job (UI is just a luxury).
-  - use a cron job. perhaps [node-cron](https://www.npmjs.com/package/node-cron)?
+```sh
+npm i bulls-eye
+```
 
 ## Hello world
 
+Remember that it depends on Redis as well, so the first step is to configure all of your queues:
+
 ```js
-const { createQueues, UI } = require('bulls-eye')
+const { createQueues } = require('bulls-eye')
 
-const queues = createQueues(redisConfig) // sets up your queues
+const redisConfig = {
+  redis: {
+    port: process.env.REDIS_PORT,
+    host: process.env.REDIS_HOST,
+    password: process.env.REDIS_PASSWORD,
+  },
+}
+
+const queues = createQueues(redisConfig)
+```
 
+And then you can setup how your queues will work:
+
+```js
 const helloQueue = queues.add('helloQueue') // adds a queue
 
+// defines how the queue works
 helloQueue.process(async job => {
   console.log(`Hello ${job.data.hello}`)
-}) // defines how the queue works
+})
 
 helloQueue.add({ hello: 'world' }) // adds a job to the queue
+```
+
+And finally, add `UI` to your middlewares (this can be set up using an admin endpoint with some authentication method):
 
-app.use('/queues', UI) // serves the UI at /queues, don't forget authentication!
+```js
+const app = require('express')()
+const { UI } = require('bulls-eye')
+
+app.use('/admin/queues', UI)
+
+// other configurations for your server
 ```
 
+## Developing
+
+To try it out locally you can clone this repo and run:
+
+```sh
+yarn && yarn start:example
+```
+
+Just make sure you spin up a Redis instance locally (default port is 6379).
+
 ## Further ref
 
-For further ref, please check [bull's docs](https://github.com/OptimalBits/bull). Appart from the way you config and start your UI, this library doesn't hijack bull's way of working.
+For further ref, please check [Bull's docs](https://optimalbits.github.io/bull/). Apart from the way you configure and start your UI, this library doesn't hijack Bull's way of working.
+
+If you want to learn more about queues and Redis: https://redis.io/
 
 ## UI
 

package.json

@@ -16,9 +16,10 @@
   },
   "scripts": {
     "build": "NODE_ENV=production webpack",
-    "start:example": "node example.js",
-    "start": "yarn watch & yarn start:example",
-    "watch": "NODE_ENV=production webpack --watch"
+    "build:watch": "NODE_ENV=production webpack --watch",
+    "start": "node example.js",
+    "start:dev": "yarn build:watch && yarn start",
+    "start:example": "yarn build && yarn start"
   },
   "devDependencies": {
     "babel-preset-react-app": "^7.0.2",