Installation & Setup

Note

If you have not yet installed the Zizq server, follow the Getting Started guide first.

The official Zizq Ruby Client is available through RubyGems. Add it to your application’s Gemfile.

gem 'zizq', '~> 0.1.0'

Or install it manually:

$ gem install zizq -v 0.1.0

Versioning

Zizq client libraries are versioned with the same version numbers as the Zizq server, which follows the SemVer structure [MAJOR].[MINOR].[PATCH].

Whenever a new major or minor version of the server is released, client libraries with the same major and minor version numbers are also released. In short, as long as the major versions match between the client and server, the client should generally have an equal or lower minor version number than the server. The client should never exceed the server version.

• It is safe to assume that a server version with the same major version number as the client and an equal or higher minor version number are fully compatible.
• A client with a different major version number to the server should be assumed to be incompatible.
• A client with the same major version number as the server but a higher minor version number may have support for newer features than the server has implemented and therefore those newer features may not work.
• The patch version numbers do not impact functionality at all.

For access to the latest features applications should generally match the major and minor version numbers between the server and the client.

Examples:

Configuration

Once installed you can load Zizq into your application by requiring "zizq".

require "zizq"

Out of the box, Zizq will communicate with the server on http://localhost:7890, which is the default host and port. This should be sufficient for local development, though you’ll need to configure the client for other environments.

Tip

The best-practice way to do this is by specifying environment variables that your application reads and uses to set each configuration option. That is left as an exercise for the reader. Examples here are hard-coded for clarity.

Configuration is done by calling Zizq.configure { ... } wherever your application typically bootstraps itself. In a Rails app this would be in a config/initializers/zizq.rb file. In a Sinatra app this could be at the top if your app.rb or even in your config.ru file.

Zizq.configure do |c|
  c.url = "https://host.your.network:7890"
  c.tls = { ca: "/path/to/server-ca-cert.pem" }
  c.logger = Logger.new("log/zizq.log")
end

Caution

If your server is exposed directly to the internet, it should be using Mutual TLS otherwise anybody can communicate with it.

Options

String

Hash

String

String

String

Symbol

Logger

Object

Zizq::Middleware::Chain

Zizq::Middleware::Chain