progapandist/kuby-core

Kuby

Deploy your Rails app the easy way.

What is Kuby?

At its core, Kuby is a set of tools and smart defaults that encapsulate and codify years of established best-practices around deploying webapps, reducing the amount of time required to take your Rails project from an app that runs on your computer to an app that runs on the Internet.

Under the hood, Kuby leverages the power of Docker and Kubernetes. It tries to make these technologies accessible to the average Rails dev without requiring a devops black belt.

Raison d'etre

One of Rails' most notorious mantras is "convention over configuration," i.e. sane defaults that limit the cognitive overhead of application development. Rails has survived for as long as it has precisely because it makes so many decisions for you, especially compared to other web application frameworks. It's easy to learn and easy to build with. The development experience is fantastic... right up until the point you want to deploy your app to production. It's at that point that the hand-holding stops. Like the Roadrunner, Rails stops right before the cliff and lets you, Wile E. Coyote, sail over the edge.

Perhaps Stefan Wintermeyer said it best during his appearance on the Ruby Rogues podcast, episode 403:

"In my experience, deployment is one of the major problems of normal Rails users. It is a big pain to set up a deployment system for a Rails application, and I don't see anything out there that makes it easier. [...] I believe that we lose quite a lot of companies and new developers on this step. Because everything else [is] so much easier with Rails. But that last step - and it's a super important step - is still super complicated."

Docker and Kubernetes

Why bet the farm on Docker and Kubernetes?

Docker

When Docker came on the scene in 2013 it was seen as a game-changer. Applications that used to be deployed onto hand-provisioned servers can now be bundled up into neat little packages and transferred between computers in their entirety. Since the whole application - dependencies, operating system components, assets, code, etc - can be passed around as a single artifact, Docker images curtail the need for manually provisioned servers and eliminate a whole class of "works on my machine" problems.

Kubernetes

Kubernetes has taken the ops world by storm. It's resilient to failure, portable across a variety of cloud providers, and backed by industry-leading organizations like the CNCF. Kubernetes configuration is portable enough to be used, without modification, on just about any Kubernetes cluster, making migrations not only feasible, but easy. Many cloud providers like Google GCP, Amazon AWS, Microsoft Azure, DigitalOcean, and Linode support Kubernetes. Most of these providers will manage the Kubernetes cluster for you, and in some cases will even provide it free of charge (you pay only for the compute resources).

Getting Started

NOTE: Kuby is designed to work with Rails 5.1 and up.

Choosing a Provider

The first step in deploying your app is to choose a hosting provider. At the time of this writing, Kuby supports DigitalOcean and Linode, but support for more providers is coming soon. Use your provider's dashboard to spin up a Kubernetes cluster. In most cases, this shouldn't involve more than a few button clicks.

The Container Registry

Kuby uses Docker to package up your application into a Docker image. Images are then pushed (i.e. uploaded) to something called a "container registry." Container registries host Docker images so they can be pulled (i.e. downloaded) later.

Although there are a number of container registries available (some free and some paid), consider using the Gitlab registry. Gitlab's registry is free and unlimited. You don't have to host your code on Gitlab to take advantage of the registry, but they're great for that too.

Integrating Kuby

Kuby configuration is done via a DSL. There are two main sections, one for Docker and one for Kubernetes. Put the config into a Rails initializer, eg. config/initializers/kuby.rb.

Here's what a complete config looks like:

Kuby.define(:production) do
  docker do
    credentials do
      username ENV['DOCKER_USERNAME']
      password ENV['DOCKER_PASSWORD']
      email ENV['DOCKER_EMAIL']
    end

    image_url 'registry.gitlab.com/username/repo'
  end

  kubernetes do
    provider :digitalocean do
      access_token ENV['DIGITALOCEAN_ACCESS_TOKEN']
      cluster_id 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
    end

    add_plugin :rails_app do
      hostname 'mywebsite.com'
    end
  end
end

Let's go over this config in detail.

Deploy Environments

The first line defines the deploy environment:

Kuby.define(:production)

Deploy environments usually closely mirror your Rails environments. For example, you might create a new Rails environment called "staging" or "preprod" that's used to test production changes before they go live. You'll want to create a "staging" Kuby deploy environment as well.

If you're a small shop or hobbyist though, chances are the "production" deploy environment is all you need.

Configuring Docker

Kuby can automatically "dockerize" your application. You just need to tell it where to push images and provide some credentials:

docker do
  credentials do
    username ENV['DOCKER_USERNAME']
    password ENV['DOCKER_PASSWORD']
    email ENV['DOCKER_EMAIL']
  end

  image_url 'registry.gitlab.com/username/repo'
end

The username, password, and email fields are used to authenticate with the Docker registry that hosts your images. For Gitlab, you'll need to create a personal access token instead of your password. The image_url field is the full URL to your image, including the registry's domain.

In the example above, the username, password, and email are all provided as environment variables. NEVER hard-code sensitive information like this in your Kuby config or check it into source control (i.e. git). Consider using a tool like dotenv to automatically load the variables from a file when your app starts (NOTE: don't check the .env file into git either!)

Configuring Kubernetes

Now that your app can be packaged up into a Docker image, it's time to use Kubernetes to run it. There are two top-level concerns in the Kubernetes section of your Kuby config: providers and plugins.

Providers

Each Kubernetes definition must have a provider configured. Providers correspond to the hosting provider you chose earlier. For example, you'll need to add the :digitalocean provider to deploy to a managed DigitalOcean Kubernetes cluster.

kubernetes do
  provider :digitalocean do
    access_token ENV['DIGITALOCEAN_ACCESS_TOKEN']
    cluster_id 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
  end
end

Kuby providers are distributed as individual rubygems. Add the one you need to your Gemfile, for example:

gem 'kuby-digitalocean', '~> 0.1'

Providers can have different config options, so make sure you consult the gem's README for the provider you've chosen.

Plugins

Nearly all Kuby's functionality is provided via plugins. For example, simply add the :rails_app plugin to get your Rails app ready to deploy:

add_plugin :rails_app

To indicate your app exists behind a particular domain name, specify the hostname option:

add_plugin :rails_app do
  hostname 'mywebsite.com'
end

Configuring DNS to point to your Kubernetes cluster is outside the scope of this README, but all the hosting providers should have tutorials. For example, here's the one from DigitalOcean.

Deploying

Now that Kuby is configured and your Kubernetes cluster is ready, it's time to deploy!

Build the Docker image
```
bundle exec rake kuby:build
```
Push the Docker image to the container registry
```
bundle exec rake kuby:push
```
Deploy!
```
bundle exec rake kuby:deploy
```
Rejoice

Running Tests

bundle exec rspec should do the trick... or at least it would if there were any tests. Don't worry, it's on my radar.

License

Licensed under the MIT license. See LICENSE for details.

Authors

Cameron C. Dutro: http://github.com/camertron

progapandist / kuby-core