diff --git a/README.md b/README.md index f91f95d..4fdb326 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -# Asynq +Asynq logo + +# Simple, reliable & efficient distributed task queue in Go -![Build Status](https://github.com/hibiken/asynq/workflows/build/badge.svg) [![GoDoc](https://godoc.org/github.com/hibiken/asynq?status.svg)](https://godoc.org/github.com/hibiken/asynq) [![Go Report Card](https://goreportcard.com/badge/github.com/hibiken/asynq)](https://goreportcard.com/report/github.com/hibiken/asynq) +![Build Status](https://github.com/hibiken/asynq/workflows/build/badge.svg) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Gitter chat](https://badges.gitter.im/go-asynq/gitter.svg)](https://gitter.im/go-asynq/community) -## Overview - -Asynq is a Go library for queueing tasks and processing them asynchronously with workers. It's backed by Redis and is designed to be scalable yet easy to get started. +Asynq is a Go library for queueing tasks and processing them asynchronously with workers. It's backed by [Redis](https://redis.io/) and is designed to be scalable yet easy to get started. Highlevel overview of how Asynq works: @@ -16,16 +16,11 @@ Highlevel overview of how Asynq works: - Server pulls task off queues and starts a worker goroutine for each task - Tasks are processed concurrently by multiple workers -Task queues are used as a mechanism to distribute work across multiple machines. -A system can consist of multiple worker servers and brokers, giving way to high availability and horizontal scaling. +Task queues are used as a mechanism to distribute work across multiple machines. A system can consist of multiple worker servers and brokers, giving way to high availability and horizontal scaling. -![Task Queue Diagram](/docs/assets/overview.png) +**Example use case** -## Stability and Compatibility - -**Important Note**: Current major version is zero (v0.x.x) to accomodate rapid development and fast iteration while getting early feedback from users (Feedback on APIs are appreciated!). The public API could change without a major version update before v1.0.0 release. - -**Status**: The library is currently undergoing heavy development with frequent, breaking API changes. +![Task Queue Diagram](https://user-images.githubusercontent.com/11155743/114697318-727c5100-9d26-11eb-98d3-0e0cc38b613d.jpg) ## Features @@ -47,14 +42,24 @@ A system can consist of multiple worker servers and brokers, giving way to high - [Web UI](#web-ui) to inspect and remote-control queues and tasks - [CLI](#command-line-tool) to inspect and remote-control queues and tasks +## Stability and Compatibility + +**Status**: The library is currently undergoing **heavy development** with frequent, breaking API changes. + +> ☝️ **Important Note**: Current major version is zero (`v0.x.x`) to accomodate rapid development and fast iteration while getting early feedback from users (_feedback on APIs are appreciated!_). The public API could change without a major version update before `v1.0.0` release. + ## Quickstart -First, make sure you are running a Redis server locally. +Make sure you have Go installed ([download](https://golang.org/dl/)). Version `1.13` or higher is required. + +Initialize your project by creating a folder and then running `go mod init github.com/your/repo` ([learn more](https://blog.golang.org/using-go-modules)) inside the folder. Then install Asynq library with the [`go get`](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them) command: ```sh -$ redis-server +go get -u github.com/hibiken/asynq ``` +Make sure you're running a Redis server locally or from a [Docker](https://hub.docker.com/_/redis) container. Version `3.0` or higher is required. + Next, write a package that encapsulates task creation and task handling. ```go @@ -204,10 +209,9 @@ func main() { } ``` -Next, start a worker server to process these tasks in the background. -To start the background workers, use [`Server`](https://pkg.go.dev/github.com/hibiken/asynq?tab=doc#Server) and provide your [`Handler`](https://pkg.go.dev/github.com/hibiken/asynq?tab=doc#Handler) to process the tasks. +Next, start a worker server to process these tasks in the background. To start the background workers, use [`Server`](https://pkg.go.dev/github.com/hibiken/asynq?tab=doc#Server) and provide your [`Handler`](https://pkg.go.dev/github.com/hibiken/asynq?tab=doc#Handler) to process the tasks. -You can optionally use [`ServeMux`](https://pkg.go.dev/github.com/hibiken/asynq?tab=doc#ServeMux) to create a handler, just as you would with [`"net/http"`](https://golang.org/pkg/net/http/) Handler. +You can optionally use [`ServeMux`](https://pkg.go.dev/github.com/hibiken/asynq?tab=doc#ServeMux) to create a handler, just as you would with [`net/http`](https://golang.org/pkg/net/http/) Handler. ```go package main @@ -248,65 +252,52 @@ func main() { } ``` -For a more detailed walk-through of the library, see our [Getting Started Guide](https://github.com/hibiken/asynq/wiki/Getting-Started). +For a more detailed walk-through of the library, see our [Getting Started](https://github.com/hibiken/asynq/wiki/Getting-Started) guide. -To Learn more about `asynq` features and APIs, see our [Wiki](https://github.com/hibiken/asynq/wiki) and [godoc](https://godoc.org/github.com/hibiken/asynq). +To learn more about `asynq` features and APIs, see the package [godoc](https://godoc.org/github.com/hibiken/asynq). ## Web UI [Asynqmon](https://github.com/hibiken/asynqmon) is a web based tool for monitoring and administrating Asynq queues and tasks. -Please see the tool's [README](https://github.com/hibiken/asynqmon) for details. -Here's a few screenshots of the web UI. +Here's a few screenshots of the Web UI: **Queues view** -![Web UI QueuesView](/docs/assets/asynqmon-queues-view.png) + +![Web UI Queues View](https://user-images.githubusercontent.com/11155743/114697016-07327f00-9d26-11eb-808c-0ac841dc888e.png) **Tasks view** -![Web UI TasksView](/docs/assets/asynqmon-task-view.png) + +![Web UI TasksView](https://user-images.githubusercontent.com/11155743/114697070-1f0a0300-9d26-11eb-855c-d3ec263865b7.png) + +**Settings and adaptive dark mode** + +![Web UI Settings and adaptive dark mode](https://user-images.githubusercontent.com/11155743/114697149-3517c380-9d26-11eb-9f7a-ae2dd00aad5b.png) + +For details on how to use the tool, refer to the tool's [README](https://github.com/hibiken/asynqmon#readme). ## Command Line Tool Asynq ships with a command line tool to inspect the state of queues and tasks. -Here's an example of running the `stats` command. - -![Gif](/docs/assets/demo.gif) - -For details on how to use the tool, refer to the tool's [README](/tools/asynq/README.md). - -## Installation - -To install `asynq` library, run the following command: - -```sh -go get -u github.com/hibiken/asynq -``` - To install the CLI tool, run the following command: ```sh go get -u github.com/hibiken/asynq/tools/asynq ``` -## Requirements +Here's an example of running the `asynq stats` command: -| Dependency | Version | -| -------------------------- | ------- | -| [Redis](https://redis.io/) | v3.0+ | -| [Go](https://golang.org/) | v1.13+ | +![Gif](/docs/assets/demo.gif) + +For details on how to use the tool, refer to the tool's [README](/tools/asynq/README.md). ## Contributing -We are open to, and grateful for, any contributions (Github issues/pull-requests, feedback on Gitter channel, etc) made by the community. +We are open to, and grateful for, any contributions (GitHub issues/PRs, feedback on [Gitter channel](https://gitter.im/go-asynq/community), etc) made by the community. + Please see the [Contribution Guide](/CONTRIBUTING.md) before contributing. -## Acknowledgements - -- [Sidekiq](https://github.com/mperham/sidekiq) : Many of the design ideas are taken from sidekiq and its Web UI -- [RQ](https://github.com/rq/rq) : Client APIs are inspired by rq library. -- [Cobra](https://github.com/spf13/cobra) : Asynq CLI is built with cobra - ## License -Asynq is released under the MIT license. See [LICENSE](https://github.com/hibiken/asynq/blob/master/LICENSE). +Copyright (c) 2019-present [Ken Hibino](https://github.com/hibiken) and [Contributors](https://github.com/hibiken/asynq/graphs/contributors). `Asynq` is free and open-source software licensed under the [MIT License](https://github.com/hibiken/asynq/blob/master/LICENSE). Official logo was created by [Vic Shóstak](https://github.com/koddr) and distributed under [Creative Commons](https://creativecommons.org/publicdomain/zero/1.0/) license (CC0 1.0 Universal).