Getting Started

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

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
    branch: master

Run shards update 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 typed and a valid JSON::Type.

Building the Binaries

The Worker 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|
  config.redis = ConnectionPool(Redis).new(capacity: 30, timeout: 5.0) do
    Redis.new(host: "localhost", port: 6379)
  end
end

cli.run(server)

You can build Sidekiq with crystal build sidekiq.cr and run ./sidekiq. It will print "hello, world!" up to 10x faster than Ruby, amazing!

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 web.cr.

require "sidekiq/web"

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
  #
  # Basic authentication:
  #
  # config.add_handler Kemal::Middleware::HTTPBasicAuth.new("username", "password")
end

pool = Sidekiq::Pool.new(
  ConnectionPool(Redis).new(capacity: 3, timeout: 5.0) do
    Redis.new(host: "localhost", port: 6379)
  end
)
Sidekiq::Client.default_context = Sidekiq::Client::Context.new(pool, Sidekiq::Logger.build)

Kemal.run

Run ./web and navigate to http://localhost:3000.

Create some Jobs

Your app must be creating jobs somewhere else, perhaps using a Rails app but you can absolutely create Sidekiq jobs within any Crystal process by initializing the client API and asynchronously invoking your Worker:

require "sidekiq"

pool = Sidekiq::Pool.new(
  ConnectionPool(Redis).new(capacity: 3, timeout: 5.0) do
    Redis.new(host: "localhost", port: 6379)
  end
)
Sidekiq::Client.default_context = Sidekiq::Client::Context.new(pool, Sidekiq::Logger.build)

# Somewhere in your code:
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] of JSON::Type
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.