Recently one of our customers informed us that they were getting weird numbers from
Facebook and Google in regards to order purchase amounts on their [Solidus][solidus] based
eCommerce.

Facebook and Google reported multiple order confirmations with the same order number, the actual
order total amounts were from 2 to 6 times lower than what was reported by them.

These numbers looked very nice on paper 📈 and could boost some distracted egos (people are
buying plenty of stuff, we're doing much better than expected!!! 💵🤑💰) but unfortunately they were so
inaccurate to be pretty useless. Houston, we have a problem 👨‍🚀.

The first step was to check how Google and Facebook get that data: some JavaScript code that
is supposed to be executed only once sends all tracking information when the customer is
redirected to the order page after completing the checkout.

How do we inject the JS code only once? By leveraging a feature in Solidus frontend
codebase: a convenient `flash` message is set after the order is finalized, and it can
be used as a flag in order to trigger the tracking libraries.

What follows is the [relevant code][checkoutcontroller] in Solidus codebase. Everything starts
in `#update`, then `#finalize_order` is called and eventually the message is set in
`#set_successful_flash_notice`:


```ruby
  # solidus/frontend/controllers/spree/checkout_controller.rb
  def update
    if update_order
      assign_temp_address
      unless transition_forward
        redirect_on_failure
        return
      end
      if @order.completed?
        finalize_order
      else
        send_to_next_state
      end
    else
      render :edit
    end
  end
  private
  def finalize_order
    @current_order = nil
    set_successful_flash_notice
    redirect_to completion_route
  end
  def set_successful_flash_notice
    flash.notice = t('spree.order_processed_successfully')
    flash['order_completed'] = true
  end
```

And this is the code in our customer's eCommerce that uses the `flash` message:

```erb
   <% if flash['order_completed'] %>
      <%= render "facebook_tracking" %>
      <%= render "google_remarketing" %>
      <%= render "adwords" %>
    <% end %>
```

The usual suspect for such issues is __caching__. If the page is cached (either on
the server or the client) then the HTML (JS code included) is not fresh and
will trigger the tracking events multiple times, one time for each page
view.

Testing locally and on the staging environment (which happens to mirror production
in regards to cache settings and such) confirmed that events are
correctly triggered only once: the expected JS code is present on the first page load
but is not on subsequent visits.

Soon we were able to confirm the issue with Safari on iOS. If you complete the
order and close the browser/restart the device then, when you reopen Safari, the
page is reloaded from the cache, not from the web.

The next step was to check the page HTTP headers. This can be done easily and
quickly from the command line using `curl -I <page-url>`.

The response included these results:

```
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/html
```

Let's get some help from [MDN][mdn] website in regards to the `Cache-Control: private`
directive:


>[private] Indicates that the response is intended for a single user and must not be stored
>by a shared cache. A private cache may store the response.
So, this directive does not completely exclude caching.

The fix was easy: customize the HTTP headers to completely avoid caching. This was
done with regular [Ruby on Rails][rails] code by extending the [controller][orderscontroller]
`OrdersController` in Solidus frontend with a decorator:

```ruby
  module OrdersController
    module EditActionCacheHeaders
      def self.prepended(base)
        base.before_action :set_no_cache_headers, only: :show
      end
      private
      def set_no_cache_headers
        response.headers['Cache-Control'] = 'no-cache, no-store'
        response.headers['Pragma'] = 'no-cache'
        response.headers['Expires'] = "Fri, 01 Jan 1990 00:00:00 GMT"
      end
      Spree::OrdersController.prepend self
    end
  end
```

When changing Solidus default behavior, it's better to do it in a decorator that extends the
default functionality with `prepend` rather than reopening and patching its methods directly.
This solution allows for easier maintenance, more clarity of purpose and composition.

The order page is managed by `OrdersController#show` action, which we don't need to modify
at all as adding a new `before_action` suffices to achieve the goal.

The first line of `#set_no_cache_headers` method is the most relevant, as it instructs all
recent browsers (HTTP/1.1) to __absolutely not__ cache and store the page for any reason.<br>
The second line `response.headers['Pragma'] = 'no-cache'` targets older browsers (HTTP/1.0)
that can accept only the `Pragma` header, while the third line set the `Expires` header well in
the past, as an extra safeguard just in case the previous headers failed their purpose.


before saying goodbye let me share a much cited quote from [Phil Karlton][quote-source]:

> There are only two hard things in Computer Science: cache invalidation and naming things.
Have a good one!


[solidus]: https://solidus.io
[mdn]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
[checkoutcontroller]: https://github.com/solidusio/solidus/blob/master/frontend/app/controllers/spree/checkout_controller.rb
[orderscontroller]: https://github.com/solidusio/solidus/blob/master/frontend/app/controllers/spree/orders_controller.rb
[rails]: https://rubyonrails.org/
[quote-source]: https://skeptics.stackexchange.com/questions/19836/has-phil-karlton-ever-said-there-are-only-two-hard-things-in-computer-science

Boosting sales with browser cache!?!

Like all web developers, I love to experiment with new tools, libraries and frameworks.
This time, for one of my side projects (my new portfolio), I decided to use [NuxtJS](https://nuxtjs.org/), which is a framework built on top of VueJS that allows to build SPAs and static websites blazingly fast, and [Prismic](https://prismic.io/), which is a Cloud headless CMS.

I've been using WordPress for years, but recently I've started working with VueJS and Nuxt on other projects, and not much time passed before deciding to build my new portfolio with Nuxt, mostly because of VueJS' ease of use.

But having a static website means that whenever I want to update it I have to:

- Open my code editor
- Make all the changes needed
- Commit to my repository
- Upload the updated/new files to the server

Not the ideal situation to be honest; I wanted to have a static website but manage its content without writing code, this is why I decided to add Prismic to the project.

By using Prismic, I can have a static website that fetches its content from an API; sounds perfect!

But there's a downside: whenever I add new content (a blog post or a case study), I still have to add the new content's page to the site's source code, meaning I'm back at the starting point.

The solution is quite simple: during the generation of the site, I tell Nuxt to make calls to the Prismic API and dynamically create those pages.<br>
Doing so, I don't have to write a single line of code anymore, bingo!

But I wanted to push it a bit further because it's true that this mechanism works, but every time a page is visited it makes a call to the Prismic API to fetch the content; this is pretty useless, and on a large scale website it can become costly.

I mean that I wanted to make those API calls only when generating the website, creating a completely static website, and at the same time having a CMS to manage its content.

> "But how do I regenerate the website everytime I update the content?"

The website is hosted on [Netlify](https://www.netlify.com/) and I've configured a webhook that whenever is triggered by Prismic it regenerates the whole website.

It's really easy to configure:

- [Create an incoming webhook on Netlify](https://www.netlify.com/docs/webhooks/#incoming-webhooks)
- [Configure webhooks on Prismic](https://user-guides.prismic.io/webhooks/webhooks)

## TL;DR;

You can find the code in [this GitHub repository](https://github.com/kekkorider/nuxt-prismic-app).

There's also a [demo available](https://determined-panini-7baf61.netlify.com/).

### 01. Creating the NuxtJS app

[Creating a new NuxtJS application](https://nuxtjs.org/guide/installation#using-code-create-nuxt-app-code) is pretty straightforward, all you have to do is open your terminal and launch

```
yarn create nuxt-app <my-project>
```

At this point, `nuxt-create-app` asks a couple of questions like the project's name, description, server, UI framework to use and so on

![create nuxt app command](https://cdn.sanity.io/images/kqgmf0g2/production/af880aca6b4ee5b59f337269f484bb799c506e21-1378x1162.png?fit=clip)

The next step is to `cd` into the project's folder and run

```
yarn run dev
```

and voilà, the new application is running at `http://localhost:3000/`.

![nuxt app created](https://cdn.sanity.io/images/kqgmf0g2/production/708e9deec984925fd5b91f6bb498f74cd4e1e411-1309x777.png?fit=clip)

## 02. Creating the Prismic backend

The website will be quite standard: it will have a homepage, an about page, a list of posts and an X amount of single post pages.

Let's start by [logging in into our Prismic account](https://prismic.io/dashboard) and create a new repository with three content types:

- Homepage (single type)
- About page (single type)
- Blog post (repeatable type)

### Important note

When creating the `Blog Post` content type, make sure you set up a `UID` field, it will be the slug of each post.

Noticed that I haven't set up a "Posts index" custom type? That's because I'll setup Nuxt to create that page when generating the website.

With the content types created, the custom types list will look like this

![prismic custom types list](https://cdn.sanity.io/images/kqgmf0g2/production/0b783ae71d8acfd1e8ef1a80812ba000b3d670b0-1189x634.png?fit=clip)

Now, let's fill in some content in the **Content** section

![prismic content created](https://cdn.sanity.io/images/kqgmf0g2/production/db99fbc5dd003154187e4af8409664c014ddd44c-1230x675.png?fit=clip)

## 03. Set up Nuxt to retrieve content from Prismic

The first thing to do is to add the `prismic-javascript` and `prismic-dom` modules, which are the two libraries that allow to query and parse content from Prismic.

Install `prismic-javascript` and `prismic-dom` by running

```
yarn add prismic-javascript prismic-dom
```

and then create a `prismic-config.js` file at the root of the project with the following content:

```javascript
// prismic.config.js
import Prismic from 'prismic-javascript'
import PrismicDOM from 'prismic-dom'
const config = {
  baseUrl: '<API_ENDPOINT>',
  access_token: '<ACCESS_TOKEN>'
}
export const initApi = req => {
  return Prismic.getApi(config.baseUrl, {
    accessToken: config.access_token,
    req: req
  })
}
export const linkResolver = doc => {
  if (doc.type === 'blog_post') return `/blog/${doc.uid}`
  return `/${doc.uid}`
}
export const generatePageData = (documentType, data) => {
  switch (documentType) {
    case 'homepage':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
    case 'about_page':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
    case 'blog_page':
      return {
        posts: data
      }
    case 'blog_post':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
  }
}
```

This file contains the Prismic's configuration and a couple of functions that are used in every template to initialize the APIs (`initApi`) and generate each page's content (`generatePageData`)

The Prismic `API_ENDPOINT` can be found in `Settings -> API & Security -> API Endpoint`.

An `ACCESS_TOKEN` is required only if the backend is set as `Private` in `Settings -> API & Security -> Repository security`

Now, open the `nuxt.config.js` file and add the following code:

```javascript
// nuxt.config.js
const Prismic = require('prismic-javascript')
import { initApi } from './prismic.config'
module.exports = {
  ...
  generate: {
    routes: function() {
      // Fetch content for the homepage and generate it
      const homepage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'homepage'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: '/',
                payload
              }
            })
          })
      })
      // Fetch content for the about page and generate it
      const aboutPage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'about_page'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: '/',
                payload
              }
            })
          })
      })
      // Fetch all the blog posts to generate the Blog page
      const blogPage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return [{
              route: `/blog`,
              payload: response.results
            }]
          })
      })
      // Fetch again all the blog posts, but this time generating each post's page
      const blogPosts = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: `/blog/${payload.uid}`,
                payload
              }
            })
          })
      })
      // Here I return an array of the results of each promise using the spread operator.
      // It will be passed to each page as the `payload` property of the `context` object,
      // which is used to generate the markup of the page.
      return Promise.all([homepage, aboutPage, blogPage, blogPosts]).then(values => {
        return [...values[0], ...values[1], ...values[2], ...values[3]]
      })
    }
  },
  ...
}
```

What the code above does is pretty simple: it queries all of our custom types (`homepage`, `about_page` and `blog_post`) from Prismic and passes the data to our templates.

## 04. Create templates and components

I'll try to explain all of these templates and components, but you can just copy-paste them in their respective locations.

```html


<template>
  <nav class="nav">
    <nuxt-link to="/">Logo goes here</nuxt-link>
    <ul class="nav-links">
      <li class="nav-link"><nuxt-link to="/">Homepage</nuxt-link></li>
      <li class="nav-link"><nuxt-link to="/about">About</nuxt-link></li>
      <li class="nav-link"><nuxt-link to="/blog">Blog</nuxt-link></li>
    </ul>
  </nav>
</template>

<style scoped>
.nav {
  align-items: center;
  display: flex;
  justify-content: space-between;
  padding: 20px;
}
.nav-links {
  list-style-type: none;
  margin: 0;
  padding: 0;
}
.nav-link {
  display: inline-block;
  margin-left: 20px;
}
</style>
```

☝ The navigation top bar

```html


<template>
  <div>
    <main-nav/>
    <nuxt/>
  </div>
</template>

<script>
import MainNav from '@/components/MainNav.vue'
export default {
  components: {
    MainNav
  }
}
</script>


<style>
html {
  font-family: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, 'Segoe UI',
    Roboto, 'Helvetica Neue', Arial, sans-serif;
  font-size: 16px;
  word-spacing: 1px;
  -ms-text-size-adjust: 100%;
  -webkit-text-size-adjust: 100%;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: antialiased;
  box-sizing: border-box;
}
body {
  background-color: #fafafa;
  margin: 0;
}
a {
  text-decoration: none;
  color: #5CBEFD;
}
*,
*:before,
*:after {
  box-sizing: border-box;
}
</style>
```
☝ The default layout with common styles

```html


<template>
  <section class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </section>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('homepage', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'homepage'))
          .then(response => {
            return generatePageData('homepage', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ Our homepage.

As you can see, I've set up an `asyncData()` method. This method is [part of NuxtJS](https://nuxtjs.org/api/) and is responsible for fetching the data before rendering the page.

Inside of `asyncData()` I check if the `context` object has the `payload` property (if the `yarn generate` script is running).

If so, we directly return the data using the `generatePageData()` function I created in `prismic.config.js`.

But the `payload` is only available when I'm generating the site using `yarn generate`, during development `payload` doesn't exist, so we have to fetch our data from Prismic first and then return the data with `generatePageData()`.

```html


<template>
  <section class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </section>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('about_page', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'about_page'))
          .then(response => {
            return generatePageData('homepage', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ The About page, same as the homepage

```html
// pages/blog/index.vue

<template>
  <div class="container">
    <h1>Blog page</h1>
    <hr>
    <article class="post" v-for="(post, index) in posts" :key="index">
      <header>
        <h1>
          <nuxt-link :to="`/blog/${post.uid}`">{{ "{{" }} "{{ "{{" }}" }} Dom.RichText.asText(post.data.title) }}</nuxt-link>
        </h1>
      </header>
    </article>
  </div>
</template>

<script>
import Prismic from 'prismic-javascript'
import PrismicDOM from 'prismic-dom'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  data() {
    return {
      Dom: PrismicDOM
    }
  },
  asyncData(context) {
    if (context.payload) {
      return generatePageData('blog_page', context.payload)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return generatePageData('blog_page', response.results)
          })
      })
    }
  }
}
</script>
```
☝ The blog page.

Here, the code inside the `asyncData()` method is a bit different from the one of Homepage or the About page; that's because there's an **array of contents**.

The difference here is that we do not pass the `data` property of the `payload` to `generatePageData()`, but directly the `payload`.

Also, we include the `PrismicDOM` library to the component's `data`, so that we can use it to print all our contents into the template by writing

```javascript
Dom.RichText.asText(post.data.title)
```

where needed.

(Yes, I _could_ avoid using the `PrismicDOM` library, but in that case we have to write something like `post.data.title[0].text[0]`)

```html


<template>
  <div class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </div>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('blog_post', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('my.blog_post.uid', context.params.slug))
          .then(response => {
            return generatePageData('blog_post', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ The single post template

First of all, did you notice the file structure? The folder's name starts with an underscore, that means that its name will be auto-generated via our configuration in `nuxt.config.js`.

For our single posts we wrote

```javascript
route: `/blog/${payload.uid}`
```

This means that `_slug` will be replaced with the `UID` of our post, resulting in a tree that will look like this:

```
/root
  /blog
    /post-01
      index.html
    /post-02
      index.html
    /post-03
      index-html
```

## Conclusion

You did it, you've managed to create a NuxtJS website that fetches its content only during the build process (except for development of course).

This allows you to save a lot of bandwidth (and also money) because it only calls the APIs once per content type instead of every page load. Cool uh?

I hope you found this post useful, if you have questions, found a bug or just want say hi, leave a comment.

Create a fast NuxtJS website using Prismic

Ensuring privacy of customer data is undoubtedly a matter of great importance
for any reputable retail business going online. Setting up an online presence
entails global access to business resources including goods, services and
personal information collected during interaction with customers. It is,
therefore, necessary that adequate mechanisms are put in place to guarantee
confidentiality and integrity of business data made available online.

Access control is a primary security concern. Generally, there are two main
ingredients to the access control equation:

- **Authentication**. To grant access, the system must first establish the
identity of the subject initiating the request to the server. The
identification process is called authentication and can be performed by
either a human or by yet another system;
- **Authorization**. With the obtained identity the system can proceed to
reason about the actions available to the current user within the system.
Restricting access to resources based on the given identity, or the absence of
one (e.g. guest user), is called authorization.

Both authentication and authorization are off the shelf features of [Solidus](https://solidus.io/).
This article delves into authorization and how it can be set up within Solidus
to align with your business needs.

## Built on CanCan(Can)

Authorization in Solidus is built upon the [CanCan(Can)](https://github.com/CanCanCommunity/cancancan)
gem, which offers an expressive DSL to [define](https://github.com/CanCanCommunity/cancancan/wiki/defining-abilities)
and [verify](https://github.com/CanCanCommunity/cancancan/wiki/checking-abilities) user permissions against application resources.
CanCan allows one to avoid access control logic being scattered throughout the
application source code. Instead, it enables one to define all user permissions
in Ability classes. For instance, here is a simplified Ability class for an
eCommerce application:

```ruby
class Ability
  include CanCan::Ability
  def initialize(user)
    user ||= User.new
    if user.admin?
      can :manage, :all
    else
      can :display, Product
      can :display, Taxon
      can :display, Taxonomy
      can :display, Variant
    end
  end
end
```

With the growth of the application, ability files like the one above tend to
quickly become massive and hence hard to maintain. With that in mind, Solidus
augments CanCan interface to facilitate implementation and maintenance of
complex ability specifications.

Let's go through the steps required to set up a custom permission system within
Solidus by examining the configuration of those permissions that already ship
with the eCommerce platform.

## Roles

Solidus comes with two preconfigured roles: *admin* and *default*. User that
`has_spree_role?(:admin)` has access to the admin panel and can manage all
resources. User that `has_spree_role?(:default)` resembles a client or a website
visitor, that can view certain resources, manage their shopping carts, etc.
Here are two main options to create a new `Spree::Role`:

- Manually add a row in the `spree_roles` table by executing
`Spree::Role.create(name: 'role_name')` in the rails console;
- In one of the configuration files (`config/intializers/spree.rb`, `config/application.rb`,
`db/migrations`, `db/seeds`) add a line `Spree::Role.find_or_create_by(name: 'role_name')`
for each role you wish to create.

With the user roles identified and created, we can proceed with assigning them
permissions sets.

## Permission sets

Addition of each new role to your application (e.g. `:blog_editor`,
`:promotion_manager`, `:retail_admin`, etc) increases the overall authorization
logic complexity. Solidus enhances the permission management process by solving
three issues:

- Enable one to split the Ability class into smaller chunks of related
permissions;
- Enable reuse by allowing one to mix and match various user roles with
various permission sets;
- Enable one to extend abilities (think pushing roles and permissions to an
array), rather than directly overriding or decorating the Ability class;

For example, by extending `PermissionSet::Base` it is now possible to decouple
the admin role permissions from the rest of the access control logic:

```ruby
# lib/spree/permission_sets/super_user.rb
module Spree
  module PermissionSets
    class SuperUser < PermissionSets::Base
      def activate!
        can :manage, :all
      end
    end
  end
end
```

The same decoupling is then applied to the default user role permissions:

```ruby
# lib/spree/permission_sets/default_customer.rb
module Spree
  module PermissionSets
    class DefaultCustomer < PermissionSets::Base
      def activate!
        can :display, Product
        can :display, Taxon
        can :display, Taxonomy
        can :display, Variant
      end
    end
  end
end
```

New permission sets should be created in their dedicated classes that extend
`Spree::PermissionSets::Base`. Permission rules defined with the CanCan DSL
should be created in the `activate!` method. Following the examples above,
place your custom permission sets under the `lib/spree/permission_sets` folder.
Finally, remember to load Solidus lib files in your application configuration:

```ruby
# config/application.rb
config.before_initialize do
  Dir.glob(File.join(File.dirname(__FILE__), "../lib/spree/**/*.rb")) do |c|
    require_dependency(c)
  end
end
```

## Role configuration

Permission sets organize related permissions without binding them to any user
role. A role can be associated with a list of permission sets through a call
to `assign_permissions` in the Solidus initializer:

```ruby
# config/initializers/spree.rb
Spree.config do |config|
  config.roles.assign_permissions :admin, ['Spree::PermissionSets::SuperUser']
  config.roles.assign_permissions :default, ['Spree::PermissionSets::DefaultCustomer']
  ...
end
```

## Conclusion

An authorization system is an integral part of any modern application that
assumes user interaction. Both development and maintenance of authorization
logic quickly become non-trivial with the growth of the application.
Specifically, adding new roles and permission logic contributes to the
increasing complexity of the system.

Solidus provides a built-in solution for user permission management. Extending the CanCan interface, the proposed approach allows one to group related permissions into separate sets and later assign them to different roles. Defining role permissions from smaller permission sets, or "componentization", allows to reduce the perceived complexity of the overall system while preserving a modular and easily maintainable system.

Your eCommerce Needs Authorization: Enter Solidus

When we work on a project, we like working with short-lived feature
branches in the form of small pull requests. PRs are great, but sometimes it can
be hard for other people to see the changes you're about to merge. To make
testing more manageable, we've been using Docker containers as preview containers.

## Architecture

![Docker preview branches architecture](https://cdn.sanity.io/images/kqgmf0g2/production/ab16b21590e8ebf234effbc632bfe686b09ff16f-3039x1661.png?fit=clip)

This architecture is made of:

- [CircleCI][CircleCI] to build Docker images for the previews;
- a server to run the containers;
- some DNS configuration to map a subdomain to a particular container;
- GitHub PRs to get deployment notifications with urls for each preview.

We figured out this architecture after trying a couple of different approaches.
We tried [Dokku][Dokku] and [Docker Compose][Docker Compose] and failed: they
were too complex... we just need disposable app containers that easy to create and
destroy.

We ended up running all the services the app needs inside a single container.
This is actually a bad practice in Docker terms, but it's rock solid compared to
running multiple containers for each open PR.

## Containerization

To run everything in a single container, we've created the [nebulab/baywatch][baywatch hub]
repository where we store every combination of tools and services we need.

If you take a look at the [baywatch source][baywatch gh], you'll see we have a
ton of different combinations of tools and services. It's pretty basic: the
`Dockerfile` installs all the requirements and the `entrypoint.sh` is used
to run multiple services with a single command.

We use these images as the base image for the `Dockerfile` that runs the
application. An example could be:

```docker
FROM nebulab/baywatch:ruby-2-4-redis-postgres
ENV APP_HOME=/preview \
  RAILS_SERVE_STATIC_FILES=true
RUN mkdir $APP_HOME
WORKDIR $APP_HOME
ADD . $APP_HOME
COPY dump.sql /dump.sql
RUN gem install bundler && bundle check --path vendor/bundle || bundle install --path vendor/bundle
RUN /entrypoint.sh && \
    su --command 'createuser --superuser root' postgres && \
    bundle exec rake db:create && \
    bundle exec rails dbconsole < /dump.sql && \
    bundle exec rails db:migrate && \
    bundle exec rake assets:precompile && \
    service postgresql stop
RUN echo "#!/bin/bash" >> /rails-entrypoint.sh
RUN echo "/entrypoint.sh" >> /rails-entrypoint.sh
RUN echo "bundle exec sidekiq -c 1 -d -L log/sidekiq.log" >> /rails-entrypoint.sh
RUN echo "bundle exec rails server --port 3000 --binding 0.0.0.0" >> /rails-entrypoint.sh
RUN chmod +x /rails-entrypoint.sh
EXPOSE 3000
ENTRYPOINT ["/rails-entrypoint.sh"]
```

The above example is something we would use for a [Ruby on Rails][rails]
application that uses Ruby 2.4, PostgreSQL, Redis and Sidekiq.

Three things are worth noticing:

1. `RAILS_SERVE_STATIC_FILES=true`: preview containers do not receive a lot of
traffic, we can serve assets directly with Ruby on Rails;
2. `COPY dump.sql /dump.sql`: we load data for the preview app from an external
database dump;
3. `ENTRYPOINT ["/rails-entrypoint.sh"]`: we use an entrypoint that runs both
services and application-specific commands.

## Docker Server

We run all these containerized apps on a bare metal server (it's cheaper and more
powerful than a cloud server) of size and power directly related to the number
of Docker containers we want to run simultaneously.

The server is configured with:

1. [nginx-proxy][nginx-proxy]: this routes a particular subdomain to a
particular container;
2. [docker-letsencrypt-nginx-proxy-companion][nginx-ssl]: this will generate
valid certificates for every running container.

Install instructions for both are available on the projects' README. The only
extra configuration we added is `--restart always` so that the containers will
be restarted in the unlikely event they go down.

The other server related configuration is the DNS: the `qa.com` server needs to
be targeted by a `*.qa.com` CNAME so that subdomain requests land on the server
where the containers are running (`nginx-proxy` handles the rest).

It's not hard to configure a server like this but, to make it even easier,
everything can be configured with the [docker-preview-server cookbook][cookbook]
which is a [Chef][chef] cookbook that configures the server automatically.

## CircleCI

We then use a CI server (we like [CircleCI][CircleCI], but any CI should work)
to build the Docker containers and tell them the preview server to run them.

Here is the CircleCI job configuration we use (this only runs for
branches with a PR open):

```yaml
jobs:
  preview:
    docker:
      - image: circleci/ruby
    steps:
      - checkout
      - run:
          name: Set Feature Branch Name
          command: |
            echo "export SUBDOMAIN=`echo $CIRCLE_BRANCH | sed \"s/[^[:alnum:]]/-/g\"`" > $CIRCLE_BUILD_NUM
            echo "export CONTAINER=$CIRCLE_PROJECT_REPONAME-\$SUBDOMAIN" >> $CIRCLE_BUILD_NUM
            echo "export DIRECTORY=$CIRCLE_PROJECT_REPONAME/\$SUBDOMAIN" >> $CIRCLE_BUILD_NUM
      - run:
          name: Notify Preview Deploy Started
          command: |
            source $CIRCLE_BUILD_NUM
            curl -X POST -H "Content-Type: application/json" -H "Accept: application/vnd.github.ant-man-preview+json" \
            "https://api.github.com/repos/nebulab/awesomeprj/deployments?access_token=<token>" \
            -d '{ "ref": "'$CIRCLE_SHA1'", "auto_merge": false, "required_contexts": [], "environment": "preview", "transient_environment": true }' | \
            grep '"id"' | head -1 | awk '{gsub(/,/,""); print $2}' > github_deploy_id
      - run:
          name: Upload Application To Docker Server
          command: |
            source $CIRCLE_BUILD_NUM
            ssh ubuntu@qa.com "rm -fr $DIRECTORY && mkdir -p $DIRECTORY"
            tar c . | ssh ubuntu@qa.com "tar xC $DIRECTORY"
      - run:
          name: Run Docker Container On Docker Server
          command: |
            source $CIRCLE_BUILD_NUM
            ssh ubuntu@qa.com "\
            docker rm -f $CONTAINER; \
            docker run -d --restart always --name $CONTAINER \
            -e VIRTUAL_HOST=$SUBDOMAIN.qa.com \
            -e APP_HOSTNAME=$SUBDOMAIN.qa.com \
            $CONTAINER"
      - run:
          name: Notify Preview Deploy Complete
          command: |
            source $CIRCLE_BUILD_NUM
            curl -X POST -H "Content-Type: application/json" -H "Accept: application/vnd.github.ant-man-preview+json" \
            "https://api.github.com/repos/nebulab/awesomeprj/deployments/`cat github_deploy_id`/statuses?access_token=<token>" \
            -d '{ "state": "success", "environment_url": "http://'$SUBDOMAIN'.qa.com/", "environment": "preview"'
```

Some parts of the configuration were removed for simplicity. Here is what is
happening:

1. CircleCI has the application code;
2. GitHub is notified that a deploy has started for that particular branch;
3. CircleCI has ssh access to the preview server;
4. application code is uploaded to the preview server;
5. Docker image is built;
6. Docker container is run;
7. GitHub is notified the deploy URL once the container is ready.

This configuration can be completely streamlined by using the
[feature-branch-preview Orb][orb] we released to make the configuration more
manageable. The Orb also generates [Let's Encrypt][letsencrypt] certificates
automatically so that your preview containers will have a valid SSL certificate.

Your CircleCI configuration when using the Orb will be something like this:

```yaml
jobs:
  - feature-branch/preview:
      domain: qa.com
      github_repo: nebulab/awesomeprj
      github_token: <token>
      letsencrypt_email: <email-for-ssl-cert>
      server: qa.com
      user: ubuntu
```

## Results

Once everything is configured this way pull requests will start showing deploys
links to subdomains that can be easily visited by both clients and developers to
check the status of a particular PR:

![PR deployment 1](https://cdn.sanity.io/images/kqgmf0g2/production/6430d3bd5428799156d7939d1f476b0062a3777b-1418x266.png?fit=clip)

You can also visit the environments section of your repository to get the latest
deployed branch:

![PR deployment 2](https://cdn.sanity.io/images/kqgmf0g2/production/fe3d4c5ea8be7d7d6748f2d076e874bc95cd2d1f-1980x302.png?fit=clip)

## Conclusions

This way of using Docker completely changed the way we work: easy and fast QA
can happen as soon as PR is made and translates in faster and safer PR merges.

One downside? It's complex and has many moving parts but, once it's ready,
it works flawlessly and only breaks if the preview server runs out of resources.

Got questions or suggestions? Leave a comment!

[CircleCI]: https://circleci.com
[Dokku]: http://dokku.viewdocs.io/dokku/
[Docker Compose]: https://docs.docker.com/compose/
[baywatch hub]: https://hub.docker.com/r/nebulab/baywatch
[baywatch gh]: https://github.com/nebulab/baywatch
[nginx-proxy]: https://github.com/jwilder/nginx-proxy
[nginx-ssl]: https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion
[cookbook]: https://github.com/nebulab/docker-preview-server
[chef]: https://www.chef.sh
[orb]: https://circleci.com/orbs/registry/orb/nebulab/feature-branch-preview
[letsencrypt]: https://letsencrypt.org
[rails]: https://rubyonrails.org/

Preview your PRs with Docker

100% code coverage, right? Yes, I know, you don't merge code in master that is
not fully tested and all that stuff. Yet I'm almost sure there's one thing
that you may be pushing to production without any tests on it: your data
migrations.

For example you could have this code:

```ruby
class RemoveEmailFromUsers < ActiveRecord::Migration[5.1]
  def up
    # Before dropping the email column from users table let's
    # create a new record with that email on the emails has many association.
    users.find_each do |user|
      user.emails.find_or_create_by(value: user.email)
    end
    remove_column :users, :email
  end
  def down
    add_column :users, :email, :string
  end
end
```

How do you test the code into the `up` method that creates a new record on a
newly added association between `User` and `Email` before removing the `email`
column from the `User` table?

It's a pretty common scenario and you could think that this logic should live
into a separate object that you can test in isolation. I agree, but you still
can't really test it since if you call that object with the last version of
your database schema (after this migration run), you'll have an exception
since `User` has no more the `email` column. 🤷‍

This example is easily fixable by just stubbing the email message on any
instance of User:

```ruby
allow_any_instance_of(User).to receive(:email).and_return(["test@email.com](mailto:%22test@email.com)")
```

This would probably fix it, but if you have a complex migration to run, you
may want to perform some more high level tests of how the system works when
the migration happens.

The good news is that you can do that. The mechanism is quite simple:

- Rollback to the migration that precedes the one you under test
- Add data to your database
- Set expectations
- Re-migrate the migration under test up

Let's make an example, we have these migrations:

```
db/
  migrate/
    20181110082123_do_cool_things_with_database.rb
    20181204143322_create_emails.rb
    20190106184413_remove_email_from_users.rb
```

If we want to test that the new association's record between User and Email
is correctly created by this migration we have to:

- Rollback database to `20181204143322_create_emails.rb`
- Create some users with the `email` field filled
- Set the expectation that for each user a new `Email` record has been created and associated with that same user
- Re-Run `20190106184413_remove_email_from_users.rb` migration.

This is how our code will look like:

```ruby
require 'rails_helper'
require Rails.root.join('db/migrate/20190106184413_remove_email_from_users.rb')
RSpec.describe RemoveEmailFromUsers do
  let(:migrations_paths) { ActiveRecord::Migrator.migrations_paths }
  let(:migrations) { ActiveRecord::MigrationContext.new(migrations_paths).migrations }
  let(:previous_version) { 20181204143322 }
  let(:current_version) { 20190106184413 }
  subject { ActiveRecord::Migrator.new(:up, migrations, current_version).migrate }
  around do |example|
    # Silence migrations output in specs report.
    ActiveRecord::Migration.suppress_messages do
      # Migrate back to the previous version
      ActiveRecord::Migrator.new(:down, migrations, previous_version).migrate
      # If other tests using User table ran before this one, Rails has
      # stored information about table's columns and we need to reset those
      # since the migration changed the database structure.
      User.reset_column_information
      example.run
      # Re-update column information after the migration has been executed
      # again in the example. This will make user attributes cache
      # ready for other tests.
      User.reset_column_information
    end
  end
  context 'when there are users with email' do
    let(:user_with_email) { create(:user, email: 'test@email.com') }
    it 'creates an Email associated with the same user' do
      expect { subject }
        .to change { Email.all.size }
        .from(0)
        .to(1)
      expect(Email.first.user).to eq user_with_email
      expect(Email.first.value).to eq 'test@email.com'
    end
  end
end
```

**Gotchas**

There is a case when running migrations within an example execution makes
Ruby on Rails generate a particular exception:

```
ActiveRecord::StatementInvalid:
  Mysql2::Error: SAVEPOINT active_record_1 does not exist: ROLLBACK TO SAVEPOINT active_record_1
```

This only happens with MySql in combination with cleaning up specs with a
transaction strategy. The latter can be both set with the RSpec configuration
`config.use_transactional_fixture` to `true`, which is the default (you should
find that in your `spec/rails_helper.rb`) or via DatabaseCleaner `transaction`
strategy. The reason behind this error is basically that we are asking to RSpec
to rollback the MySql database to the previous state with a transaction
rollback, but it can't handle rollbacks of schema changes as well.

There is also a quick way to fix this: we just need to use `truncation` for
all those specs by adding:

```
# Without DatabaseCleaner
before(:all) { self.use_transactional_tests = false }
after(:all)  { self.use_transactional_tests = true }
```

or:

```
# With DatabaseCleaner
before(:all) { DatabaseCleaner.strategy = :truncation }
after(:all)  { DatabaseCleaner.strategy = :transaction }
```

**Is testing migrations really needed?**

I don't know! These kind of specs looks fragile and poorly maintainable, even
if they can be removed once the migration has been pushed since they do not
provide any regression value. I still think they are worth it for some very
**critical data migrations** or in **OSS projects**, where it's important to
keep backwards compatibility in mind; that migration could run in the future,
when code is changed and no one can ensure it's still valid. Also, I think
they can help writing code with confidence and help thinking about all
possible scenarios.

It's worth mentioning that this post comes from a real need I had while
working on [Solidus,
the open source eCommerce platform based on Ruby on Rails](https://solidus.io) that we use.
I created [a PR that removes a field from the database](https://github.com/solidusio/solidus/pull/3028) and I provided three ways to
handle the data migration for Solidus users.
Having the ability to test the migration really helped me being sure all
approaches works without the need to test them by running the migration on
specifically crafted databases. Also, I didn't know when this migration will
be executed since it will run when users upgrade Solidus to the version that
contains PR's commits. At that point, without migration tests, we couldn't
be sure that the migration is still working.

Testing Ruby on Rails Migrations

## Introduction

I'm a long time [Ruby on Rails](https://nebulab.com/ruby-on-rails-development/) developer.
When [Action Cable](https://guides.rubyonrails.org/action_cable_overview.html)
was released, the first thing that came to mind was: "[will it perf?](https://www.youtube.com/watch?v=qg1ckCkm8YI)",
given that Ruby has never been recognized for its ability with concurrency management, nor Rails for its lightness.

Browsing around, I stumbled upon [AnyCable](https://github.com/anycable/anycable), an alternative to Action Cable created
for some reason. What if that reason is performance? Let's find out!

### How Action Cable works

Action Cable runs in an application server instance separate from the one that handles the standard HTTP requests. It uses
the [`hijack` API](https://www.rubydoc.info/github/rack/rack/master/file/SPEC#label-Hijacking), a Rack API added
specifically for sessions requiring evented IO, like Server-Sent Events and WebSockets, giving to the application the
whole control of the socket. Within Action Cable, the WebSocket management is fully implemented in Ruby.

### How AnyCable works

Like for Action Cable, AnyCable receives and sends messages using Ruby, but the socket management is forwarded via
[gRPC](https://grpc.io/) to a server compatible with AnyCable specifications, which can be written in any language.
Currently, the official implementations are [AnyCable-Go](https://github.com/anycable/anycable-go), written in Go, and
[ErlyCable](https://github.com/anycable/erlycable), written in Erlang. For details about AnyCable architecture, I
recommend reading the related posts listed in the [AnyCable README](https://github.com/anycable/anycable/blob/master/README.md).

## Setup

*If you're trying to run the test by yourself you should read the Caveats section first*

We are going to load test Action Cable and AnyCable with [Tsung](https://www.process-one.net/en/tsung/) (credits to
[this excellent post](https://www.thegreatcodeadventure.com/load-testing-rails-5-action-cable-with-tsung/) which showed me the
right way). Below the testing environment details:

 - CPU: Intel i7-2600K

 - OS: Ubuntu 18.04.1

 - Ruby: 2.5.3

 - Rails (along with Action Cable): 5.2.2

 - AnyCable: 0.6.0

 - AnyCable-Go: 0.6.0

 - Load testing: Tsung 1.7.0

I wrote two Procfile configurations respectively for [Action Cable](https://github.com/nebulab/rails-websocket-bench/blob/master/Procfile.actioncable) and
[AnyCable](https://github.com/nebulab/rails-websocket-bench/blob/master/Procfile.anycable)
in order to run them using [Foreman](https://github.com/ddollar/foreman):

```
# Action Cable
foreman start -e .env.production,.env.actioncable -f Procfile.actioncable
# AnyCable
foreman start -e .env.production,.env.anycable -f Procfile.anycable
```

 Once the server is up and running, we can start Tsung:

```
tsung -f tsung.xml -k start
```

[Tsung is configured](https://github.com/nebulab/rails-websocket-bench/blob/master/tsung.xml) to
open 500 WebSocket connections per second (and keep them open) until it gets 60000 connections. 60000 is around the
limit that can be reached on a single machine since each connection needs a port to go through. Tsung writes its
results in the `~/.tsung` directory and serves them live at `http://localhost:8091`.

### Caveats

Performing the test is a bit tricky; there are some workarounds and tweaks we have to take:

#### tsung_stats.pl not found error

Tsung runs correctly, but it fails to generate the report showing an error like the following:

```
Fail to generated reports: tsung_stats.pl was not found in the $PATH
```

It happens because Tsung can't find its binaries. Add them to `$PATH`:

```
export PATH=/usr/lib/x86_64-linux-gnu/tsung/bin:$PATH
```

#### Overcome OS caps

As suggested [here](https://github.com/hashrocket/websocket-shootout#open-file-limits), we need to increase OS limits
related to open files and port ranges. Add the following to `/etc/sysctl.conf`:

```
net.ipv4.tcp_tw_reuse = 1
net.ipv4.ip_local_port_range = 1024 65000
fs.file-max = 2097152
```
And add the following to `/etc/security/limits.conf`:

```
*    soft nofile 1048576
*    hard nofile 1048576
```

Reboot or reload the configuration and everything should be fine.

#### Image paths are broken

Visiting `http://localhost:8091/es/ts_web:graph` we can't see any report image, basically because image paths are
broken. Run the following code in your browser console:

```js
const prependSlash = (_i, attr) => (attr.charAt(0) !== '/') ? `/${attr}` : undefined
$('.graph').attr('src', prependSlash).closest('a').attr('href', prependSlash)
```

## Benchmarks

Enough talking! Let's look at the results:

### Action Cable

![Action Cable maximum simultaneous users](https://github.com/nebulab/rails-websocket-bench/blob/master/public/benchmark-results/actioncable/images/graphes-Users-simultaneous.png?raw=true)

Action Cable performs fairly well for the first 20000 users, then it starts suffering and honorably tries to overtake
this limit. Not without issues, as we can see from the errors rate report:

![Action Cable errors rate](https://github.com/nebulab/rails-websocket-bench/blob/master/public/benchmark-results/actioncable/images/graphes-Errors-rate.png?raw=true)

### AnyCable

![AnyCable maximum simultaneous users](https://github.com/nebulab/rails-websocket-bench/blob/master/public/benchmark-results/anycable/images/graphes-Users-simultaneous.png?raw=true)

AnyCable doesn't miss a beat, facing up to all the 60000 connections we throw at it. Moreover, the errors rate is…
inexistent! Tsung refused to generate it.

## Conclusion

Action Cable is rather capped regarding the connections amount that it can handle, though it can be enough for use cases
with a restricted amount of users. If instead your application has stronger requirements, AnyCable is a perfectly viable
option.

Action Cable vs AnyCable: fight!

There's no debate around the fact that good API design is an art. When we stumble into a properly
designed API, we can feel it. Just like good visual UIs, good APIs are not just beautiful, it's
functional and it saves everyone's time. With this mind, it's not a stretch to say that APIs are, in
fact, UIs. They're not just meant for machines either: since there are people programming and using
those machines, creating an API that users are delighted to interact with is a deliberate choice of
its development team, and one we ought to make.

There are many resources about design principles for visual UIs, as well as a lot of good examples
to take inspiration from. When it comes to APIs, on the other hand, there is a lot of documentation
explaining the different protocols, languages and frameworks for their implementation, but nearly
not enough material on the underlying principles and choices that make certain APIs a joy to work
with and others a complete nightmare.

While nothing can beat experience and each team comes up with their own rules for what makes an API
great, we can all benefit by applying some basic principles to the design of our APIs. These are
very abstract and can be implemented in many different ways, but they should always guide our
technical decisions.

## Consistency

Consistency means that similar endpoints should behave in similar ways, including in edge scenarios.
You should always strive to keep vocabulary, URL structure, request/response formats and error
handling consistent across your entire API.

This provides several benefits:

* It makes it much simpler to interact with your API, since users always know what to expect and
  don't have to read the documentation of every endpoint, but can simply go with their gut.
* It allows writing client libraries that don't know the exact schema of the API, just the rules
  you commit to respecting. The Stripe API client is a good example of this: because the structure
  of requests and responses is always the same, it can build objects dynamically and only needs to
  be updated when one of the API rules changes.
* It creates a set of battle-tested guidelines that you can abide by when you are implementing new
  features in the API. No more discussions around whether to use numeric IDs or UUIDs, because
  you'll just go with whatever you already have in place.

Consistency is probably the most impactful trait you can implement in the design of your API, and your users will love you for it.

## Performance

Performance in HTTP APIs is a tricky matter. Because APIs are not directly consumed by end users,
it's easy for performance issues to go unnoticed for a very long time, especially in the context of
server-to-server interactions. Unfortunately, because software is made for people, all types of
performance issues will eventually impact the end user.

I strongly advise against early optimization, for the usual reasons: it will slow down the
development of your MVP and you can't know what parts of your product need to be optimized without
having the right metrics in place first. You should optimize based on data, not instinct.

With that said, it is extremely important that you start collecting the data from day one. Setting
up an APM tool is a matter of seconds nowadays, and it will provide you with a ton of useful
information about how your API is being used in the real world.

## Documentation

No matter how consistent your API is, users will still need a place they can go to in order to get
started or obtain additional details about certain aspects or capabilities of the API.

Furthermore, API documentation should not just be about presenting request and response templates.
It's useful and recommended to add any information your users might find helpful, such as
explanations as to what happens in the background when a certain API call is made or what other
endpoints the user might need to complete the transaction at hand.

It is extremely important that your API documentation is accurate and up to date. The only way to
accomplish this is by creating a workflow to integrate documentation into your development process.
A good way is to check documentation into your VCS and require developers to update it whenever they
change the API.

Having developers write documentation might seem like a waste of time, but the more time you spend
documenting, the less time you'll spend answering questions and investigating bogus bug reports.

Finally, ensure the documentation is not just available, but a joy to consult. Since it is meant to
be consumed by humans, put extra care into the UI and UX of reading the documentation. Instead of
doing this yourself, you can just adopt a service such as [Stoplight](https://stoplight.io) that will store and present the content in a standard format for you.

## Usability

While there is nothing inherently wrong with having a 1:1 mapping between your database tables and
your API resources, you should know that this is not the only way to build an API. In fact, for
complex APIs, it's often not the best way, because it puts all the burden of stringing the right set
of operations together in the right order on the user's shoulders.

If you can simplify a business transaction to only require one API call instead of two, why not do
it? It would be unthinkable for a visual UI to require user input for every single operation that
happens in the background - and yet, that's exactly what we do in many APIs, when we ask our users
to do our work out of laziness.

One example of this is an API that allows users to add a new payment method and mark a payment
method as the default one. If we expect situations where the user wants to add a new method and
immediately mark it as default, we can add a mark_as_default attribute to the payment method
creation endpoint and do everything in one transaction without requiring two API calls. This saves
both development time and bandwidth.

This kind of simplification is not always possible: when you are not able to determine the exact use
cases of your API in advance (e.g. in the case of public APIs), you ought to be as flexible as
reasonably possible (in the example above, this would mean adding the field but also maintaining a
separate endpoint for setting the default payment method).

The rule of thumb is to consider all aspects of your API as means to an end, i.e. to complete a
business flow. How can you best help the user achieve that goal? Once you have that in mind, design
choices become much easier.

## Simplicity

Build your API on top of simple, universally accepted standards and tools. There's no need for
envelopes, schemas, API gateways or any other esoteric solutions unless you have very good reasons
for using them.

The HTTP RFC already provides you with most of the tools you'll need to build a Web service that is
reliable and interoperable, so [go
ahead and read it](https://tools.ietf.org/html/rfc2616#section-10.1.1) (yes, it's long, but I can guarantee it's worth it).

Stick to the basics and do them well. Simplicity means less overhead for humans and machines, as
well as less room for mistake. For instance, here's what it takes to charge a credit card using the
Stripe API:

```console
curl https://api.stripe.com/v1/charges \
  -u your_api_key: \
  -d amount=999 \
  -d currency=usd \
  -d description="Example charge" \
  -d source=tok_visa
```

It's so simple you can do it without looking up the documentation, and it's virtually impossible to
mess it up. This is the kind of simplicity you want to strive for.

(By the way, the Stripe API is an excellent example of thoughtful API design, so take a look at the
[API reference](https://stripe.com/docs/api) if you have some time.)

## Evolution

Traditional Web applications are updated all the time: new features are designed and added, popular
ones are improved and streamlined, unused ones are deprecated and removed. Users are accustomed to
living and operating in an environment that's constantly changing, sometimes quite dramatically.

Most of the time, products do a very good job of nudging users to adopt new features: newsletters,
in-app tours and good design practices ensure that the UX is never disrupted by the latest round
updates.

For APIs, on the other hand, it looks like there are only two possible options: either you never
change your interface for fear of breaking implementations, or you change it without notice,
disrupting the most of your customers' work. This happens because API teams are often disconnected
from their user base, since they don't interact with users directly.

But a third option is entirely possible: with the right infrastructure and tooling in place, you can
have an API that changes in a way that is manageable for its users. You can use metrics to make
informed decisions about the interface you expose to the world: how often is an endpoint used? What
users called a specific API endpoint in the last 6 months? Make sure you can always answer this kind
of questions, because they will allow you to evolve your API without making your users' day a
nightmare.

## Over to You!

Do you have any other principles that you apply when designing APIs? Or have you seen examples of
very well-designed APIs? We'd love to hear from you and discuss, just leave a comment below!

6 Design Principles for your HTTP APIs

A few weeks ago, after deploying some new code to production I received
a notification about a strange new-to-me error:

```
ActiveRecord::ConcurrentMigrationError: Cannot run migrations because another migration process is currently running
```

The new deployed code consisted only of [Solidus](https://solidus.io/) and
[Rails](https://rubyonrails.org/) minor version upgrades, so at first I suspected some unanticipated bug/incompatibility. But the error had not happened either on CI or on the staging server, so I concluded that it was
probably something more pertinent to the application environment.

Let's get back to the error message, which happens to be quite self-explanatory.
I started to reason about what could have gone wrong: while staging and CI run on single Amazon instances, the production environment is based on multiple AWS `t2.large` instances, and the Rails deploy procedure is basically concurrent on each of them... that's just how [Opsworks](https://aws.amazon.com/opsworks) does it.

![Image of AWS instances](https://cdn.sanity.io/images/kqgmf0g2/production/18bde4a3af504a27430c4340c8585671533aa4b3-1978x854.png?fit=clip)

So, during the deploy process one instance was still running migrations when also `uhura` tried to run them as well, eventually raising the error.

The error is generated by a Rails feature named [Advisory locking](https://github.com/rails/rails/pull/22122) added in 2015:

> Attempting to run a migration while another one is in process will
> raise a ConcurrentMigrationError instead of attempting to run in
> parallel with undefined behavior. This could be rescued and
> the migration could exit cleanly instead. Perhaps as a configuration
> option?
This error can be quite insidious, as the deploy will fail on that instance, which
will retain the previous application code. This time we were quite lucky as the new code
was still functionally the same as before, but in other cases this could have easily
caused a few headaches.

Imagine having one instance of the application serving outdated pages, not showing new
Solidus' features, or showing features that don't exist anymore. And this is not the worst case
scenario... the instance could be throwing `500 server error` to each visitor if something more serious was wrong.

So, in order to fix the error (or, better said, ignore it and live happily) we customized the migration rake as follows:

```ruby
# lib/tasks/migrate_ignore_concurrent.rake
namespace :db do
	namespace :migrate do
		desc 'Run db:migrate but ignore ActiveRecord::ConcurrentMigrationError errors'
		task ignore_concurrent: :environment do
			begin
				Rake::Task['db:migrate'].invoke
			rescue ActiveRecord::ConcurrentMigrationError
				# Do nothing
			end
		end
	end
end
```

and run this instead of the usual one:

`bundle exec rake db:migrate:ignore_concurrent`

This solution is, as often happens in life, not without _caveat_.

Consider the rare case when the first instance that got the lock is running a long DB migration (I'm not judging here, but you should not have long running migrations) which eventually fails. All other instances that tried to acquire the lock would now be already running the new code which also probably requires the new DB... what a day! So, all in all, it's just a matter of tradeoffs, I chose mine :)

The strange case of ActiveRecord ConcurrentMigrationError

for extracting data from each schema. This approach is cheaper than
multi-db because it requires less hardware, time and resources to
manage a large number of customers.

### Shared schema

In this implementation the tenants' records share the same tables within the same database, using an ad-hoc column in each table to discriminate among all tenats' records.

There is no data isolation and no fault tolerance: every problem with our
persistent layer affects on all tenants; all backups, restores, extraction
operations for a single tenant do not come for free: you should implement all these mechanisms by yourself at the application level because you could have different policies for different customers.

Just like the multi-schema approach we'll face less costs in terms of hardware in the long period but considerable development costs of a shared-architecture.

### Which approach should I use?

The answer is always the same: it depends. When you choose a solution you have to face several trade-offs. [This article][msdn-multi-tenant-data-architecture] provides some interesting considerations.

As a rule of thumb it's better avoid a multi-db approach if you don't know for
sure how many tenants you're about to manage. Avoid a shared approach if you expect a huge amount of data per tenant or when particular capabilities are required for each tenant.

> Choose the right tool for the right job.
## Within Rails

Now back to the topic of this blogpost: how to migrate our newly created Solidus eCommerce to multi-tenant?

First of all, Solidus is a Rails app and achieving multi-tenancy within Ruby on
Rails is quite easy due to the highly flexible and extendible
nature of the Ruby language and Rails' engine-based architecture. After all, that's one of the main reason [we work with Solidus!][nebulab-blogpost-why-solidus]

I recommend this *old-but-gold* [Railscast][ryan-bates-railscast-multi-tenant] that shows how to implement a shared-schema multi-tenant architecture by yourself using ActiveRecord scopes.

However there are already a bunch of gems implementing all types of
multi-tenancy.

### Apartment

There is an amazing, mature - and veeery well documented - gem made by
[**Influitive Corp.**][influitive-homepage] called [Apartment][apartment-gh]
that will implement both multi-db and multi-schema architectures pretty well and
almost *out-of-the-box*. This gem basically introduces a [Rack][rack-homepage]
middleware (called *Elevator*) that is responsible of intercepting the
requests, selecting the target tenant according to some criteria
(like the domain/subdomain name or, for example, the authenticated user) and
preparing ActiveRecord queries with all the stuff needed to switch to the
correct database or schema.

There are a lot of articles on how to migrate your RoR application to
multi-tenant using the Apartment gem. We really appreciated [Troy
Anderson's Zero to Multi-Tenant in 15 Minutes – A Rails
Walkthrough][zero-to-multi-tenant], and [this blogpost by Brad Robertson][influitive-blogpost-multi-tenant-journey-with-apartment].
There are also some useful screencasts (see *Credits*).

## Within Solidus

As mentioned above Apartment basically interacts with ActiveRecord and the Rack middleware system on which Rails relies on, so should work pretty well together with Solidus. And so it is! However, there are some known issues we have to keep in mind when switching a Solidus app to multi-tenant.

In fact, as the application complexity and dependencies grow, we could face
some conflicts or issues, expecially when we use some specific or intrusive
gems. Here I'll summarize the most common I found around the web. I've created [this tutorial project][multi-tenant_shop] that aims to serve two different online stores: `www.pescara-shop.com` and `www.latina-shop.com`. The project relies on the Apartment gem and adopts a multi-schema implementation. This project has a good README and a list of self-explaining commit messages you can follow as step-by-step instructions. Here you can find more details about the encountered issues and some advice on how to make Solidus and Apartment work.

#### Preferences

Since Solidus preferences could be persisted in the database
(`legacy_db_preferences` mode), we could store the preferences for each tenant when the application starts and retrieve the correct preferences with each request, depending on tenant. Unfortunately, saving preferences on database is currently deprecated and it might be removed:

> Replace the default legacy preference store, which stores preferences in the
> spree_preferences table, with a plain in-memory hash. This is faster and less
> error-prone.
But using a plain in-memory hash requires [some
workarounds][multi-tenant-shop-preferences-ext] to properly store the preferences.

#### Testing

Since Solidus uses [RSpec][rspec-homepage], I've focused my analysis on how this testing suite works with the Apartment gem.  Let's start by looking at the [Apartment wiki page][apartment-testing]. Here we can find most of the instructions and the best practices we need:

> The number one thing that has helped us in testing is to create a single
> tenant before the whole test suite runs and switch to that tenant for the run
> of your tests.
In fact, using feature specs is almost impossible, and as far as I know, the
reason is the same why we cannot use __transactional tests__ with Capybara:

> Transactional fixtures do not work with Selenium tests, because Capybara uses
> a separate server thread, which the transactions would be hidden from. We
> hence use DatabaseCleaner to truncate our test database.
See [this issue][apartment-capybara-issue444] for more details.

The combination of the mandatory use of [DatabaseCleaner][dbcleaner-gh] and the need to test against a single test-tenant, produces a quite standard
configuration like this:

```ruby
# spec/rails_helper.rb
RSpec.configure do |config|
  config.use_transactional_fixtures = false
  config.before(:suite) do
    # Clean all tables to start
    DatabaseCleaner.clean_with :truncation
    # Use transactions for tests
    DatabaseCleaner.strategy = :transaction
    # Truncating doesn't drop schemas, ensure we're clean here, app *may not* exist
    Apartment::Tenant.drop('test_app') rescue nil
    # Create the default tenant for our tests
    Apartment::Tenant.create('test_app')
  end
  config.before(:each) do
    # Start transaction for this test
    DatabaseCleaner.start
    # Switch into the default tenant
    Apartment::Tenant.switch! 'test_app'
  end
  config.after(:each) do
    # Reset tentant back to `public`
    Apartment::Tenant.reset
    # Rollback transaction
    DatabaseCleaner.clean
  end
end
```

#### Seeding

I reccomend using Rails' plain-old seeds mechanism instead of external gems. One of the most famous is [Seedbank][seedbank-gh], but it doesn't seem to be working with Apartment (and lacks support for Rails 5). A little code has to be written in order to setup a very basic tenant-based seed loading mechanism. Something like:

```ruby
# config/db/seeds.rb
NebulabShop::Stores.each do |tenant, domain|
  Apartment::Tenant.switch(tenant) do
    Rails.root.join("db/seeds/#{tenant}").each_child do |seed_file|
      puts "Loading seed file: #{seed_file}"
      load seed_file
    end
  rescue Errno::ENOENT => e
    puts "there was an error while accessing #{e.message}"
  end
end
```

#### Asynchronous jobs

[Sidekiq][sidekiq-homepage] is probably the best known background processor for Ruby and Rails. Although it's not a gem included in Solidus there's plenty of situations where you probably need asynchronous jobs. Luckily, as mentioned in the Sidekiq wiki

> You can use client middleware to add job metadata to the job before pushing it
> to Redis. The same job data will be available to the server middleware before
> the job is executed, if you need to set up some global state, e.g. current
> locale, current tenant in a multi-tenant app, etc
it's possible to exploit the middleware architecture of Sidekiq to inject
tenant-switching logic into the Sidekiq workflow. Moreover, there's no need to
implement this by yourself! Influitive developed an Apartment adapter
for Sikdekiq called [apartment-sidekiq][apartment-sidekiq-gh].

## Conclusions

In this blogpost I've briefly introduced the concept of multi-tenancy and
investigated on how the adoption of this architecture could impact our Solidus
application, giving a sum up of some useful resources I've found along the way.
I've highlighted the amazing extendable architecture of the framework which allows us to highly customize our business logic and behaviors - and so multi-tenancy - by simply decorating Solidus objects. If you're interested in a more
deep dive into implementation or configuration details, you can refer to the
[*Multi-tenant shop*][multi-tenant_shop] project. Hope this helped you! Feel free to comment or ask for any questions.

## References and Credits

#### Articles

+ [Ruminations on multi-tenant][ruminations-on-multi-tenant]
+ [Multi-tenant ecommerce platform][multi-tenant-ecommerce]
+ [Multi-Tenant Data Architecture][msdn-multi-tenant-data-architecture]
+ [Zero to Multi-Tenant in 15 Minutes – A Rails Walkthrough by Troy Anderson][zero-to-multi-tenant]
+ [Our Multi-tenancy Journey with Postgres Schemas and Apartment by Brad Robertson][influitive-blogpost-multi-tenant-journey-with-apartment]
+ [Building a multi-tenant app is easy…if you have an apartment! by Igor Petrov][credits-apartment-freecodecamp]

#### Screencasts

+ [Railscasts PRO #388: Multi-Tenancy with Scopes by Ryan Bates][ryan-bates-railscast-multi-tenant]
+ [Rails Pacific 2014 Multi-Tenancy with Rails by Ryan Bigg][ryan-bigg-railspacific-rails-multi-tenancy]
+ [GoRails: Multi-Tenancy in Rails with the Apartment gem][gorails-railscast-apartment]

#### Books

+ [Multitenancy with Rails][ryan-bigg-book-multi-tenancy-with-rails]

[ruminations-on-multi-tenant]: http://www.db.in.tum.de/research/publications/conferences/BTW2007-mtd.pdf
[multi-tenant-ecommerce]: https://medium.com/@riyajohn9495/multi-tenant-ecommerce-platform-979da8c5554c
[postgresql-multi-schema]: https://www.postgresql.org/docs/9.1/static/ddl-schemas.html
[spof-wiki]: https://en.wikipedia.org/wiki/Single_point_of_failure
[msdn-multi-tenant-data-architecture]: http://ramblingsofraju.com/wp-content/uploads/2016/08/Multi-Tenant-Data-Architecture.pdf
[ryan-bates-railscast-multi-tenant]: https://www.youtube.com/watch?v=jwILy2GB7XE
[ryan-bigg-railspacific-rails-multi-tenancy]: https://www.youtube.com/watch?v=uwWBuqmQb0o
[ryan-bigg-book-multi-tenancy-with-rails]: https://leanpub.com/multi-tenancy-rails-2
[influitive-homepage]: https://influitive.com
[apartment-gh]: https://github.com/influitive/apartment
[rack-homepage]: http://rack.github.io/
[rspec-homepage]: http://rspec.info/
[dbcleaner-gh]: https://github.com/DatabaseCleaner/database_cleaner
[gorails-railscast-apartment]: https://youtu.be/L5y72hfIT_M
[zero-to-multi-tenant]: https://www.alliedcode.com/zero-to-multitenant-in-15-minutes-a-rails-walkthrough/
[influitive-blogpost-multi-tenant-journey-with-apartment]: https://influitive.io/our-multi-tenancy-journey-with-postgres-schemas-and-apartment-6ecda151a21f
[nebulab-blogpost-why-solidus]: /blog/why-solidus
[multi-tenant_shop]: https://github.com/nebulab/multitenant_shop
[multi-tenant-shop-preferences-ext]: https://github.com/nebulab/multitenant_shop/blob/master/lib/multitenant/
[seedbank-gh]: https://github.com/james2m/seedbank
[sidekiq-homepage]: https://sidekiq.org/
[apartment-sidekiq-gh]: https://github.com/influitive/apartment-sidekiq
[apartment-capybara-issue444]: https://github.com/influitive/apartment/issues/444
[apartment-testing]: https://github.com/influitive/apartment/wiki/Testing-Your-Application
[credits-apartment-freecodecamp]: https://medium.freecodecamp.org/building-a-multitenant-app-is-easy-if-you-have-an-apartment-3465f6eda85b

How to switch a Solidus eCommerce to Multi-tenant

CSS Grid is a great feature! What I want to share here is a little tweak that
should be used when working with grids and scalable contents. In a responsive context, a way to proportionally scale contents is making their dimensions to depend from a percentage of window's width, using **vw** units. If we don’t care about the overall grid element dimension (width and height), the enclosed cells could not be proportional, and will stretch over the two dimensions.
There is no evidence of the problem with a square grid but it is instead evident
with a rectangular one. If your goal is to maintain the internal cells with 1:1
proportion, even when the column and row counts do not match, this is a solution for you. The trick is to calculate the ratio of the grid's **width**, given its **height** (in vw units), number of **rows** and number of **columns**.

### A South Park example
###### (Inspired by [http://4x4pixels.blogspot.com](4x4pixels))

Kyle is a nice, square, CSS Grid guy... right click on him on the Pen, and turning on the inspector you'll see it has a 4x4 grid layout..

![](https://cdn.sanity.io/images/kqgmf0g2/production/23c2b160b9924a3cc1d169121bcc6aa06269daa5-600x600.png?fit=clip)


Also check he shares his dimensions along with his friends Stan and Kenny.

![](https://cdn.sanity.io/images/kqgmf0g2/production/60e4c339cb7819002ac419cbbecab7a217404916-600x600.png?fit=clip)
![](https://cdn.sanity.io/images/kqgmf0g2/production/23c2b160b9924a3cc1d169121bcc6aa06269daa5-600x600.png?fit=clip)
![](https://cdn.sanity.io/images/kqgmf0g2/production/c682b1476f22e896fffc6e3ab73c8dafd28a1b55-600x600.png?fit=clip)

[CodePen here](https://codepen.io/aleph1ow/pen/bjgdYP/)

#### I'm big boned!

Ah! There’s also Cartman! …but, wait a second… he should be a bit wider than the others! What happened to him? Did he go on a diet? Let’s turn on the inspector…

[CodePen here](https://codepen.io/aleph1ow/pen/JBEdgv/)

We can see that all these CSS Grid guys have a **4x4 layout**, but Cartman has **6X4**. His grid cells are not 1:1. Since the container's width equals its height, the cells look rectangular because there are more columns than rows in Eric's body :)

![](https://cdn.sanity.io/images/kqgmf0g2/production/60e4c339cb7819002ac419cbbecab7a217404916-600x600.png?fit=clip)
![](https://cdn.sanity.io/images/kqgmf0g2/production/79dc3e1e341d9312648d7fb08e5ecbf731ef78d0-600x600.png?fit=clip)

We are going to introduce a mixin that solves the problem by calculating the width ratio based on the height and the number of columns/rows.

```scss
@mixin scalable-grid($columns, $rows, $height) {
	width: $columns * $height / $rows;
	display: grid;
	grid-gap: 0;
	grid-template-columns: repeat($columns, minmax(1%, 1fr));
	grid-template-rows: repeat($rows, minmax(1%, 1fr));
}
```

[CodePen here](https://codepen.io/aleph1ow/pen/OwWyVJ/)


This way the cells' aspect ratio will always be 1:1.

![](https://cdn.sanity.io/images/kqgmf0g2/production/c60b0b6c6c884b79b0a1cda3d9b204ec758dfcc1-898x600.png?fit=clip)

Ha-ha! Now I recognize you little bastard!

### A close friend of everybody

Of course, this is also valid when there are more rows than columns, like when it’s Christmas and Mr.Hanky **2X6** comes…

![](https://cdn.sanity.io/images/kqgmf0g2/production/edfde6e0f9a5ffc00056b0e25ccef3eb32ec675b-600x600.png?fit=clip)

[CodePen here](https://codepen.io/aleph1ow/pen/RBKWRz/)

Better maintain his proportions with our mixin :D


![](https://cdn.sanity.io/images/kqgmf0g2/production/60e4c339cb7819002ac419cbbecab7a217404916-600x600.png?fit=clip)
![](https://cdn.sanity.io/images/kqgmf0g2/production/c60b0b6c6c884b79b0a1cda3d9b204ec758dfcc1-898x600.png?fit=clip)
![](https://cdn.sanity.io/images/kqgmf0g2/production/93a63a4aa4bfcab3bd3b2069344cd0593adce19a-202x600.png?fit=clip)
![](https://cdn.sanity.io/images/kqgmf0g2/production/23c2b160b9924a3cc1d169121bcc6aa06269daa5-600x600.png?fit=clip)
![](https://cdn.sanity.io/images/kqgmf0g2/production/c682b1476f22e896fffc6e3ab73c8dafd28a1b55-600x600.png?fit=clip)

[CodePen here](https://codepen.io/aleph1ow/pen/djNYvr/)

And now you can kill Kenny :)

### Usefulness?

Besides this (funny?) example, I found this approach useful in my front-end experience anytime I needed to show images inside a grid &mdash; a very complex rectangular grid with some empty cells &mdash; but I wanted to keep the aspect ratio of every cell 1:1 (with some of the images spanning over multiple cells), and also get the CSS grid to be fully responsive.

The Nebulab