Getting Started

Rafał Wojsznis edited this page Mar 21, 2018 · 24 revisions

Want to run some background jobs in Let's get you started!

Install the Dependencies

You need Crystal > 0.18.2 and Redis > 2.8. On Mac OSX:

brew update
brew install crystal-lang
brew install redis

Create an App

Create a new Crystal application if necessary.

crystal init app sample

Integrate into your App

Pull in as a dependency into your application in shards.yml:

    github: mperham/
    branch: master

Run shards update to download the Sidekiq source.

Create your First Worker

In src/sample/

require "sidekiq"

module Sample
  class MyWorker
    include Sidekiq::Worker

    def perform(name : String, count : Int64)
      count.times do "hello, #{name}!"

Note the parameters to the perform method must be explicitly typed. Complex types should use JSON.mapping to marshal correctly.

Create some Jobs using the Client API

Your can create jobs using a Rails app or within any Crystal process by initializing the client API and asynchronously invoking your Worker:

require "sidekiq"
# This initializes the Client API with a default Redis connection to localhost:6379.
# See the Configuration page for how to point to a custom Redis location.
Sidekiq::Client.default_context =

# Now somewhere in your code you can create as many jobs as you want:
Sample::MyWorker.async.perform("world", 3_i64)

# A lower-level, more dynamic API is also supported:
job =
job.klass = "Sample::MyWorker"
job.queue = "default"
job.args = ["world", 3_i64].to_json
client =
jid = client.push(job)

The Crystal and Ruby versions of Sidekiq should be 100% data compatible with each other. Crystal can push jobs for a Ruby process to consume, or vice versa. The Crystal Web UI can monitor Ruby processes, or vice versa, etc.

Building the Binaries

The Sidekiq Process

With Crystal, you build and run a single binary with Sidekiq and all your worker code compiled into it. Put this in and then run it with crystal run

require "sidekiq/cli"
require "./src/sample"

cli =
server = cli.configure do |config|
  # middleware would be added here

You can build Sidekiq with crystal compile --release and run ./sidekiq. It should print "hello, world!" several times based on the job you created in the previous section.

The Web UI

Sidekiq also offers a Web UI to monitor the cluster of Sidekiq processes using Redis. Kemal is similar to Ruby's Sinatra library, you can configure it to enable HTTP Basic Authentication, enable SSL support, change the listening port from 3000, etc. Put this in, build with crystal compile --release

require "sidekiq/web"

# Basic authentication:
# require "kemal-basic-auth"
# basic_auth "username", "password"

Kemal.config do |config|
  # To enable SSL termination:
  # ./web --ssl --ssl-key-file your_key_file --ssl-cert-file your_cert_file
  # For more options, including changing the listening port:
  # ./web --help

# Exact same configuration for the Client API as above
Sidekiq::Client.default_context =

Run ./web and navigate to http://localhost:3000. The Busy tab should show the Sidekiq process we started in the previous section.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.