Getting Started

Want to run some background jobs in Sidekiq.cr? Let's get you started!

Install the Dependencies

You need Crystal >= 1.0.0 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 Sidekiq.cr as a dependency into your application in shards.yml:

dependencies:
  sidekiq:
    github: mperham/sidekiq.cr

Run shards update --ignore-crystal-version to download the Sidekiq source.

Create your First Worker

In src/sample/workers.cr:

require "sidekiq"

module Sample
  class MyWorker
    include Sidekiq::Worker

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

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 = Sidekiq::Client::Context.new


# 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 = Sidekiq::Job.new
job.klass = "Sample::MyWorker"
job.queue = "default"
job.args = ["world", 3_i64].to_json
client = Sidekiq::Client.new
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 sidekiq.cr and then run it with crystal run sidekiq.cr:

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

cli = Sidekiq::CLI.new
server = cli.configure do |config|
  # middleware would be added here
end

cli.run(server)

You can build Sidekiq with crystal build --release sidekiq.cr 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 web.cr, build with crystal build --release web.cr.

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
end

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

Kemal.run

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