In this post we'll look at what it takes to set up Splunk with the Traefik reverse-proxy, such that we can send log events using Splunks HTTP Event Collector, and see and query the results in Splunk's admin dashboard.

Splunk is a great tool for capturing and analysing application logs.
Although Splunk is reasonably pricey, they do allow you to use Splunk Enterprise self-hosted for up to 500MB of data per day.

Given that Splunk Enterprise is available as a Docker image, and I've been using Traefik as a reverse proxy for my projects recently, I was curious if I could get the two to work nicely together. Looking for clues as to how others had done this in Google, I came up empty-handed, hence this post.

Splunk configuration

Given that I'm developing on a Mac (though using Linux in production), I ran into the issue that Splunk doesn't yet have robust support for Mac OS High Sierra.
Thankfully there's a workaround that involves adding the OPTIMISTIC_ABOUT_FILE_LOCKING setting to the splunk-launch.conf.

Therefore, when we run Splunk, we'll share an edited version of the splunk-launch.conf via a volume.

Set up the local directory containing an empty splunk-launch.conf:

mkdir -p /opt/splunk
touch /opt/splunk/splunk-launch.conf

The splunk-launch.conf will look like:

#   Version 7.2.4

# Modify the following line to suit the location of your Splunk install.
# If unset, Splunk will use the parent of the directory containing the splunk
# CLI executable.
#
# SPLUNK_HOME=/opt/splunk-home

# By default, Splunk stores its indexes under SPLUNK_HOME in the
# var/lib/splunk subdirectory.  This can be overridden
# here:
#
# SPLUNK_DB=/opt/splunk-home/var/lib/splunk
# Splunkd daemon name
SPLUNK_SERVER_NAME=Splunkd

# Splunkweb daemon name
SPLUNK_WEB_NAME=splunkweb

# If SPLUNK_OS_USER is set, then Splunk service will only start
# if the 'splunk [re]start [splunkd]' command is invoked by a user who
# is, or can effectively become via setuid(2), $SPLUNK_OS_USER.
# (This setting can be specified as username or as UID.)
#
# SPLUNK_OS_USER
# https://answers.splunk.com/answers/306998/why-am-i-getting-homepathoptsplunkvarlibsplunkaudi.html?childToView=578312#answer-578312
OPTIMISTIC_ABOUT_FILE_LOCKING=1

Running a Splunk docker container

Before we setup our docker-compose.yml, we'll run a Splunk container directly, as we need to check that it works, and also set up the HTTP Event Collector.

In order to use Splunk to capture our logs, splunk exposes the HTTP Event Collector service via an https endpoint, which we can ping with our log data.

Setting up the the HTTP Event Collector basically involves generating an authorization token in the Splunk instance, which can then be used to authenticate each request to send data to Splunk.

# Create the local folders
mkdir -p /opt/splunk/etc/
mkdir -p /opt/splunk/var/

# Run the Splunk docker container
docker run \
    -p 8000:8000 \
    -p 8088:8088 \
    -e 'SPLUNK_START_ARGS=--accept-license --no-prompt --answer-yes' \
    -e 'SPLUNK_USERNAME=admin' \
    -e 'SPLUNK_PASSWORD=CHANGEMENOW' \
    -v /opt/splunk/splunk-launch.conf:/opt/splunk/etc/splunk-launch.conf \
    -v /opt/splunk/etc:/opt/splunk/etc \
    -v /opt/splunk/var:/opt/splunk/var \
    splunk/splunk:latest

Presumably you'll want to change the password from CHANGEMENOW to something more appropriate -- note that Splunk enforces a password policy of a length of at least eight ASCII characters.

Given that this is a test, and given that Splunk takes some time to start up, I've not deamonised the above command, so I can follow the progress easily at the terminal. You'll now that Splunk is ready when you see the following:

Ansible playbook complete, will begin streaming var/log/splunk/splunkd_stderr.log

You should now be able to see the Splunk admin interface at http://localhost:8000:

Setting up the HTTP Event Collector

We need to set up the HTTP Event Collector as per the Splunk documentation.

Once done, we should have a Token Value at http://localhost:8000/en-US/manager/search/http-eventcollector:

We can test that this works by pinging the Splunk endpoint with some example data:

curl -ki  https://localhost:8088/services/collector/event \
    -H "Authorization: Splunk a6cb2c21-7dd1-4028-bbee-257f5a5e17db" \
    -d '{"event": "hello splunk"}'
    
HTTP/1.1 200 OK
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Date: Sun, 24 Mar 2019 00:13:53 GMT
Server: Splunkd
Vary: Authorization
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN

{"text":"Success","code":0}

Note a couple of things about the call:

• We need to use https
• Because we probably don't have a valid cert, we need to specify the -k Curl option.

Traefik

As Splunk demands that we call the HTTP Event Collector using an https endpoint, we need to ensure that we set up the Splunk backend service in Traefik as HTTPS.

However, this leads to the problem that Traefik will not be able to call the Splunk backend service via HTTPS as it doesn't have access to the cert.

We could extract the certs from the Splunk container (they live at $SPLUNK_HOME/etc/auth/) and supply these to Traefik, but for a non-production set up, we can use the Traefik insecureSkipVerify global configuration value.

We'll create a local directory in which our traefik.toml will live:

mkdir -p /opt/etc/traefik
touch /opt/etc/traefik/traefik.toml

At a minimum, our traefik.toml will look something like:

################################################################
# Global configuration
################################################################

defaultEntryPoints = ["http", "https"]
insecureSkipVerify = true

################################################################
# Entrypoints configuration
################################################################

# Entrypoints definition
#
# Optional
# Default:
[entryPoints]
  # http should be redirected to https
  [entryPoints.http]
    address = ":80"
    [entryPoints.http.redirect]
      entryPoint = "https"

  # https is now the default
  [entryPoints.https]
    address = ":443"

  # Traefik status page
  [entryPoints.traefik]
     address = ":8080"
     [entryPoints.traefik.auth.basic]
        usersFile = "/usr/local/share/.auth"

# Enable ACME (Let's Encrypt): automatic SSL
# https://docs.traefik.io/user-guide/examples/#basic-example-with-http-challenge
[acme]
  storage = "/etc/traefik/acme.json"
  caServer = "https://acme-v02.api.letsencrypt.org/directory"
  entryPoint = "https"
  acmeLogging = true
  onDemand = false
  onHostRule = true
  [acme.tlsChallenge]

################################################################
# Traefik logs configuration
################################################################

[traefikLog]

filePath = "/var/log/traefik/traefik.log"

################################################################
# Access logs configuration
################################################################

[accessLog]

filePath = "/var/log/traefik/access.log"

docker-compose.yml

We'll assume the following environment variables:

BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD=whatever
DOMAIN=localhost.example.com
EMAIL=whoever@example.com
SPLUNK_USERNAME=admin
SPLUNK_PASSWORD=changemenow
CERT=example.com.pem
KEY=example.com-key.pem

We'll assume that we've added the following entries to our /etc/hosts file:

127.0.0.1	splunk.localhost.example.com
127.0.0.1	splunk-api.localhost.example.com

We'll also assume that we've generated a cert for *.localhost.example.com -- you can use something like mkcert to generate this cert and key, and store the results at /opt/etc/traefik/.

We'll add basic auth to Traefik by using a Dockerfile based on traefik:alpine:

# Dockerfile
FROM traefik:alpine

ARG BASIC_AUTH_USERNAME
ARG BASIC_AUTH_PASSWORD

ENV BASIC_AUTH_USERNAME $BASIC_AUTH_USERNAME
ENV BASIC_AUTH_PASSWORD $BASIC_AUTH_PASSWORD

RUN apk add --update apache2-utils \
  && rm -rf /var/cache/apk/* \
  && mkdir -p /var/log/traefik \
  && mkdir -p /etc/traefik \
  && touch /etc/traefik/acme.json \
  && chmod 0600 /etc/traefik/acme.json \
  && htpasswd -cBb /usr/local/share/.auth $BASIC_AUTH_USERNAME $BASIC_AUTH_PASSWORD

Our docker-compose.yml ends up looking like the following:

version: '2'

services:
  traefik:
    build:
      context: .
      args:
        - BASIC_AUTH_USERNAME=$BASIC_AUTH_USERNAME
        - BASIC_AUTH_PASSWORD=$BASIC_AUTH_PASSWORD
    container_name: "traefik.${DOMAIN}"
    restart: unless-stopped
    command: -c /dev/null --api --docker --logLevel=DEBUG --acme.email=$EMAIL \
      --configFile=/etc/traefik/traefik.toml \
      --entryPoints='Name:https Address::443 TLS:/etc/traefik/${CERT},/etc/traefik/${KEY}'
    ports:
      - 80:80
      - 443:443
      - 8025:8025
    expose:
      - 8080
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /opt/etc/traefik:/etc/traefik
    labels:
      traefik.enable: "true"
      traefik.backend: traefik
      traefik.frontend.rule: "Host:traefik.${DOMAIN}"
      traefik.port: "8080"

  splunk:
    # https://www.splunk.com/blog/2018/10/24/announcing-splunk-on-docker.html
    image: splunk/splunk:latest
    container_name: "splunk.${DOMAIN}"
    environment:
      SPLUNK_START_ARGS: --accept-license --no-prompt --answer-yes
      SPLUNK_USERNAME: $SPLUNK_USERNAME
      SPLUNK_PASSWORD: $SPLUNK_PASSWORD
    restart: unless-stopped
    labels:
      # Use the following yaml formatting to allow our basic auth
      # variables to be properly escaped
      - "traefik.ui.backend=splunk"
      - "traefik.ui.port=8000"
      - "traefik.ui.frontend.rule=Host:splunk.${DOMAIN}"
      - 'traefik.ui.frontend.auth.basic=${BASIC_AUTH_USERNAME}:${BASIC_AUTH_PASSWORD_ENCRYPTED}'
      - "traefik.api.backend=splunk-api"
      - "traefik.api.protocol=https"
      - "traefik.api.port=8088"
      - "traefik.api.frontend.rule=Host:splunk-api.${DOMAIN}"
    volumes:
      # We need to override splunk-launch.conf on Mac OS Sierra:
      # https://answers.splunk.com/answers/306998/why-am-i-getting-homepathoptsplunkvarlibsplunkaudi.html?childToView=578312#answer-578312
      - /opt/splunk/splunk-launch.conf:/opt/splunk/etc/splunk-launch.conf
      - /opt/splunk/etc:/opt/splunk/etc
      - /opt/splunk/var:/opt/splunk/var
    expose:
      - 8000
      - 8088
    depends_on:
      - traefik

We should now be able to run up our stack. Again, we don't daemonise, so we can easily see the logs messages in the terminal, given that Splunk takes some time to start:

docker-compose up --build

We should then be able to see our admin at https://splunk.localhost.example.com.

We should also be able to ping the HTTP Event Collector:

curl -ki  https://splunk-api.localhost.example.com/services/collector/event -H "Authorization: Splunk a6cb2c21-7dd1-4028-bbee-257f5a5e17db" -d '{"event": "hello splunk"}'

HTTP/1.1 200 OK
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Date: Sun, 24 Mar 2019 00:13:53 GMT
Server: Splunkd
Vary: Authorization
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN

{"text":"Success","code":0}

Using the Splunk service

In order to easily send logs to Splunk from docker containers, we'll want to install the docker-logging-plugin:

docker plugin install splunk/docker-logging-plugin:latest --alias splunk-logging-plugin
docker plugin enable splunk-logging-plugin

If we want another service in our docker-compose.yml to direct logs to Splunk, we'll need to ensure it contains an appropriate logging section, specifying the splunk-token and splunk-url we've set up previously:

    logging:
      driver: splunk-logging-plugin
      options:
        splunk-token: a6cb2c21-7dd1-4028-bbee-257f5a5e17db
        splunk-url: https://splunk-api.${DOMAIN}
        splunk-insecureskipverify: 'true'
        labels: whatever

And that should be all we need to do to get Splunk running with Traefik in Docker, at least on a local Mac OS machine.

A production Splunk instance will require significantly more setup than this though, as you'll want to ensure Splunk is secure and robust.

Although React is a great way of doing component-based UI development, when creating web applications that are somewhat complicated or need to perform at scale, we may find ourselves running into situations where React seems to be less than helpful.

One such situation that I've been working with recently is getting our React application to support Edge Side Includes.

However, as I've discovered, with a little bit of work we can ensure our React application is able to gain the benefits of ESIs in an elegant and maintainable fashion.

Edge Side Includes (ESIs)

Edge Side Includes (aka ESIs) are a way of caching parts of the page so that effort is offloaded from your application to an edge server, using a service such as Akamai.

For example, consider a <CustomerList /> React component whose job is to render a list of customer firstnames; the rendered HTML for such a a component might look like the following:

<div>
  <ul>
    <li>Jane</li>
    <li>John</li>
    <li>Abigail</li>
  </ul>
</div>

The component JavaScript could look like the following:

// customerList.js
export default class CustomerList extends React.Component {
  constructor(props) {
    super(props);

    return fetch('https://data.example.com/customer_list')
    .then((res) => res.json())
    .then((data) => {
      this.state = {
        data        
      };
    })
    .catch((error) => {
      console.log('Error: ', error)
    })
  }

  static name = 'CustomerList';

  render() {
    return (
      <div>
        <ul>
          { this.state.data.map((customer) => (
            <li>{ customer.firstname }</li>
          )) }
        </ul>
      </div>
    );
  }
}

The important thing to grasp here is that such a list would require our application to fetch the customer firstnames each time it was called, and if our web application receives a lot of interest, this could result in many thousands of calls being made each minute to the data source to obtain this information.

Although one could argue that the application itself could cache such data internally, this is not really the job of the application, and can even become problematic when we run a cluster with multiple copies of our application (e.g. using Docker containers), as different nodes in the cluster could end up having different cached copies of the data, and the result rendered to the user would therefore depend on which node in the cluster served the page to them.

ESIs are very useful in large-scale web applications as not only can they reduce the load on the backend data source, they can also result in lower costs for serving traffic, as the cost of pages served via Edge Servers can be very cheap.

In order to implement an ESI, instead of the above HTML, our application would render an esi:include tag instead, e.g.

<esi:include src-"https//api.example.com/CustomerList?field=html" onerror="continue" />

Then, when the Edge Server sees this tag, it will call to http//api.example.com/CustomerList?field=html to obtain the content, and replace the <esi:include /> with the retrieved content.

In terms of reducing the load on our data source, this of course would be pointless if the Edge Server had to perform this data fetch for every page that it processes; typically, the content being ESIed (https//api.example.com/CustomerList?field=html) will be served with a cache header indicating that the Edge Server can cache it for a certain period of time, and need not refetch it until this cache period expires.

React

Although it may not be obvious at first, ESIs pose a few problems for our React application.

We need a component API

The first is that our <CustomerList /> component content has to be able to be served as a separate bit of content, and not simply as part of the entire page that our application is rendering.

This means that our application needs to provide a separate API that can be queried for a given component, returning just the HTML (and possibly CSS) for this component.

This is actually reasonably simple to create, as the following illustrates:

// componentServer.js
'use strict';

import React              from 'react';
import { renderToString } from 'react-dom/server';
import Helmet             from 'react-helmet';
import jp                 from 'jsonpath';

// create webpack context containing all components
let requireComponent = require.context(
  './', // context folder
  true, // include subdirectories
  /\/[^\.]+\.js$/ // RegExp
);

export default function(req, res) {
  let sendJson        = req.headers.accepts === 'application/json';
  let componentName   = req.params.componentName;
  let body            = req.body;
  let componentProps  = body.props || {};
  let returnField     = body.field;
  let Component;

  if (req.method === 'GET') {
    componentProps = req.query.props
      ? JSON.parse(req.query.props) 
      : componentProps;

    returnField = req.query.field;
  }

  if (typeof returnField !== 'string' && returnField != void 0) {
    return sendError(res, 400, '"field" prop was not a string.', sendJson);
  }

  try {
    Component = requireComponent(`./${componentName}.js`);
  } catch (e) {
    console.error(`Component ${componentName} not found`); // eslint-disable-line no-console
  }

  if (!Component) {
    return sendError(res, 404, 'A component with that name does not exist.', sendJson);
  } else {
    let html;

    try {
      html = renderToString(
        <Component {...componentProps} />
      );
    } catch (e) {
      console.log('Error:', e.message); // eslint-disable-line no-console
    }

    let header = Helmet.rewind();

    // payload header should only contain strings
    Object.keys(header)
    .forEach((attributeName) => {
      header[attributeName] = header[attributeName].toString();
    });

    let payload = {
      html,
      css: Component.css,
      header,
    };

    const contentTypes = {
      css: 'text/css',
    };

    if (returnField) {
      let field = jp.query(payload, returnField)[0];
      return res
      .type(contentTypes[returnField] || 'text/html')
      .status(200)
      .send(field)
      .end();
    }

    if (sendJson) {
      return res
      .status(200)
      .json(payload);
    }

    // return rendered HTML if JSON was not requested
    payload.state = JSON.stringify(payload.state);
    res
    .status(200)
    .render('component_api_layout', payload);
  }
};

Note that we can ask separately for either the html (https//api.example.com/CustomerList?field=html) or the css (https//api.example.com/CustomerList?field=css) of our component.

We need to think about our rendering

Now that we have a means of allowing our Edge Server to fetch the content to replace the <esi:include /> tag, we have to ensure that our component renders appropriately (i.e. differently) in the various contexts in which it will be called:

• when called via our component API, we expect the component to render the full HTML and / or CSS

• when called to render serverside via a call to our main application (i.e. when it's constructing the page of which our <CustomerList /> is one part), we expect our component to render an <esi:include /> tag, e.g <esi:include src-"https//api.example.com/CustomerList" onerror="continue" />, rather than rendering the actual HTML of the <CustomerList />

• when called to render clientside once our page hits the browser, we expect out component to render the full HTML and / or CSS of our <CustomerList />

The last of these requires some thinking about; we WILL be re-rendering clientside whether we like it or not, as the data-react-checksum generated during the server render (i.e. which took into account the serverside-rendered <esi:include />) will be invalid clientside, as the <esi:include /> has been replaced on the page's journey to the browser with the real markup of our <CustomerList /> by the Edge Server.

As React detects that the data-react-checksum is no longer valid, it will re-render the DOM, and will call our <CustomerList /> to re-render clientside.

It's worth noting that, in the recently-released React 16, data-react-checksum is no longer used, and therefore it may be possible to avoid the clientside re-render immediately that the page is loaded, but you'll still want to be able to cope with clientside re-rendering of the <CustomerList /> at some point.

An exercise in futility?

So, given that clientside our <CustomerList /> needs to render the full HTML, this makes the whole of the article to this point sound like an exercise in futility; what is the point of using an Edge Server to reduce the load on our data source from serverside calls by our application, if we simply end up calling the data source clientside from the browser?

The answer is that, clientside, we have to be a little smarter, in that we don't get our <CustomerList /> component to render the full HTML, but rather we get it to re-use the DOM that was injected by the Edge Server.

Thus, the only time that our <CustomerList /> component actually calls the data source and renders fresh HTML containing the firstnames of our customers is when the Edge Server calls our component via our new component API (i.e. https//api.example.com/CustomerList?field=html).

If we set caching headers on the https//api.example.com/CustomerList?field=html response for, say, 180 seconds, then our component will only be asked to do a data fetch every three minutes or so, rather than on every request.

An ESI higher-order component

So, now that we've worked out the mechansim to get ESI content to appear, we need to implement it.

One naive way would be to amend each component we wish to ESI, such that it renders in different contexts according to the logic described above.

However, this means that, should we have many components that we wish to ESI, we will have to make similar changes in each component, and be prepared to change all of the components whenever we wish to make modifications.

A better approach is to use a higher-order component, which allows us to wrap our <CustomerList /> with the ESI logic, while not having to modify <CustomerList /> at all.

Our main app component would look somewhat like follows where, instead of rendering <CustomerList />, it would now be rendering <WrappedCustomerList />:

// app.js 
import React               from 'react';
import WithEdgeSideInclude from 'withEdgeSideInclude';
import CustomerList        from 'customerList';

const WrappedCustomerList = WithEdgeSideInclude(CustomerList),

class Page extends React.Component {
  constructor(props) {
    super(props);
  }

  render() {
    return (
      <WrappedCustomerList />
    );
  })
}

In the above, we are using <WithEdgeSideInclude /> to wrap our <CustomerList /> component, and in doing so <WithEdgeSideInclude /> will be responsible for deciding whether <CustomerList /> renders its full HTML, or whether something else should be rendered instead.

Our <WithEdgeSideInclude /> higher-order component will look something like the following:

// withEdgeSideInclude.js
'use strict';

import React  from 'react';
import config from 'config';

let SUPPRESS_ESI = config.suppressEsi;
let BUNDLE_TYPE = config.bundleType;

module.exports = function withEdgeServerInclude(WrappedComponent) {
  return class extends React.Component {
    constructor(props) {
      super(props);
    }

    static name = 'WithEdgeServerInclude';

    shouldComponentUpdate() {
      // Only allow rerendering if we're not using an ESI
      return ! SUPPRESS_ESI
        ? false
        : true;
    }

    getExistingHtml(selector, property) {
      const element = global.document.querySelector(selector);
      return element
        ? element[property]
        : null;
    }

    render() {
      // Don't re-render the included ESI client-side, but instead
      // re-use the edge-server-rendered DOM.
      if (BUNDLE_TYPE === 'client') {
        const css = this.getExistingHtml(`#${WrappedComponent.name}__styles`, 'innerHTML');
        const html = this.getExistingHtml(`.${WrappedComponent.name}`, 'outerHTML');

        if (html && css) {
          return (
            <div>
              <style
                id={`${WrappedComponent.name}__styles`}
                dangerouslySetInnerHTML={{ __html: css }}
              />
              <div dangerouslySetInnerHTML={{ __html: html }} />
            </div>
          );
        }
      }

      // Render an esi:include unless we're configured to suppress
      if (! SUPPRESS_ESI) {
        return (
          <div>
            <style
              id={`${WrappedComponent.name}__styles`}
              dangerouslySetInnerHTML={{ __html: `<esi:include src="https//api.example.com/${WrappedComponent.name}?field=css" onerror="continue" />` }}
            />
            <div
              dangerouslySetInnerHTML={{ __html: `<esi:include src="https//api.example.com/${WrappedComponent.name}?field=html" onerror="continue" />` }}
            />
          </div>
        );
      }

      // Render the full component
      return (
        <WrappedComponent {...this.props} />
      );
    }
  }
};

Note the following about withEdgeSideInclude.js:

• We use a config boolean, SUPPRESS_ESI, to determine whether we wish to render the full HTML of our wrapped component; this is helpful for local development, where we want to see the rendered HTML and not the <esi:include /> (as requests to localhost will not be routed via our Edge Server, and therefore any <esi:include /> will not be replaced by the full HTML).
  In this case, the relevant part of the render function is below:

    // Render the full component
    return (
      <WrappedComponent {...this.props} />
    );
  

• If we are rendering serverside, we render the <esi:include >s. In this case, the relevant part of the render function is below; note that in this case we use two <esi:include >s, one for the CSS and one for the HTML.

    // Render an esi:include unless we're configured to suppress
    if (! SUPPRESS_ESI) {
      return (
        <div>
          <style
            id={`${WrappedComponent.name}__styles`}
            dangerouslySetInnerHTML={{ __html: `<esi:include src="https//api.example.com/${WrappedComponent.name}?field=css" onerror="continue" />` }}
          />
          <div
            dangerouslySetInnerHTML={{ __html: `<esi:include src="https//api.example.com/${WrappedComponent.name}?field=html" onerror="continue" />` }}
          />
        </div>
      );
    }
  

• If we are rendering clientside, we re-use the HTML and CSS that was injected by the Edge Server.
  In this case, the relevant code is below:

    getExistingHtml(selector, property) {
      const element = global.document.querySelector(selector);
      return element
        ? element[property]
        : null;
    }
  
    ...
  
    // Don't re-render the included ESI client-side, but instead
    // re-use the edge-server-rendered DOM.
    if (BUNDLE_TYPE === 'client') {
      const css = this.getExistingHtml(`#${WrappedComponent.name}__styles`, 'innerHTML');
      const html = this.getExistingHtml(`.${WrappedComponent.name}`, 'outerHTML');
  
      if (html && css) {
        return (
          <div>
            <style
              id={`${WrappedComponent.name}__styles`}
              dangerouslySetInnerHTML={{ __html: css }}
            />
            <div dangerouslySetInnerHTML={{ __html: html }} />
          </div>
        );
      }
    }
  

Note that in the clientside rendering, we grab the DOM elements that were injected by the Edge Server, and simply render these using dangerouslySetInnerHTML, rather than render them fresh.
In this way we avoid a clientside call to our data source.

Conclusion

As the above examples have outlined, we can gain the substantial benefits of ESIs in React applications with two particular modifications to our application:

• a component API, to allow the Edge Server to retrieve the HTML and CSS for a specific component

• a <WithEdgeSideInclude /> higher-order component, which wraps the component we wish to ESI, and determines whether the wrapped component should be allowed to do the data fetch and render its HTML, or whether an <esi:include /> should be rendered (serverside) or whether the Edge Server injected DOM should be re-used (clientside).

Although, at least in React 15, we can't easily avoid the clientside rerender caused by the invalid data-react-checksum, we can ensure that we don't lose the benefits of ESIs during the clientside rerender.

Our aim with this post is to describe the process to run Kubernetes locally, by demonstrating running MySQL and Wordpress on the Kubernetes cluster.

We won't explain what Kubernetes is, suffice to say it is the container orchestration solution that everyone seems to be leaning towards; normally you'd want to run up a Kubernetes cluster on a cloud provider such as AWS or GCE, however for the purposes of training / evaluation, we run it up locally using a cluster of Vagrant virtual machines.

Prerequisites

We assume we're on Mac OSX, though the Vagrantfile is OS-agnostic, so you should be able to get things working on both Windows and Linux relatively easily.

We need to install a few things, and we'll do so using the brew package manager:

brew install vagrant
brew install kubectl
brew install wget

Creating the Kubernetes cluster

Our first step is to clone the kubernetes-vagrant-coreos-cluster repo, which bills itself as a:

Turnkey Kubernetes cluster setup with Vagrant 1.8+ and CoreOS.

This project provides a comprehensive Vagrantfile which will, by default, run up a cluster of three CoreOS Vagrant virtual machines.

# clone the repo
git clone https://github.com/pires/kubernetes-vagrant-coreos-cluster.git
cd kubernetes-vagrant-coreos-cluster

We can then vagrant up the cluster:

# remove Virtualbox's DHCP server
VBoxManage dhcpserver remove --netname HostInterfaceNetworking-vboxnet0

# run up the cluster, specifying that we want the web ui
USE_KUBE_UI=true vagrant up

Note that we specify that we want the web-based user interface; other settings are described in the project's README.md, but do take a look through the Vagrantfile to get a better idea about what values can be supplied.

The cluster startup will likely take some time, as vagrant will most likely need to pull a number of images; the Vagrantfile does allow the following providers, though we're using Virtualbox here:

• Virtualbox (the default)
• Parallels Desktop
• VMware Fusion or VMware Workstation

Once Vagrant has pulled the necessary VM images, you should be able to inspect them at:

# display the virtualbox image directories
ls -la ~/VirtualBox\ VMs/


# display the uncompressed sizes of the virtualbox image directories
du -sh ~/VirtualBox\ VMs/*

2.8G	/Users/jasondarwin/VirtualBox VMs/kubernetes-vagrant-coreos-cluster_master_1507421853719_25399
4.4G	/Users/jasondarwin/VirtualBox VMs/kubernetes-vagrant-coreos-cluster_node-01_1507422227192_50843
2.7G	/Users/jasondarwin/VirtualBox VMs/kubernetes-vagrant-coreos-cluster_node-02_1507422346442_20718

Inspecting the cluster

Once the cluster has been created, we can then get some information about it.

We'll be using kubectl, and there's a cheatsheet that lists the useful kubectl commands.

# view the three nodes using vagrant
vagrant status

Current machine states:

master                    running (virtualbox)
node-01                   running (virtualbox)
node-02                   running (virtualbox)


# get info about our cluster
kubectl cluster-info

Kubernetes master is running at https://172.17.8.101
KubeDNS is running at https://172.17.8.101/api/v1/namespaces/kube-system/services/kube-dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.


# display nodes
kubectl get nodes

NAME           STATUS                     AGE       VERSION
172.17.8.101   Ready,SchedulingDisabled   3h        v1.7.5
172.17.8.102   Ready                      3h        v1.7.5
172.17.8.103   Ready                      3h        v1.7.5

At this point we might like to ssh into our cluster nodes and have a look around; we can either use vagrant ssh or we can ssh directly by referring to the vagrant insecure_private_key:

# ssh into the master
vagrant ssh master

# ssh directly into a machine
ssh -i ~/.vagrant.d/insecure_private_key core@172.17.8.101

The Kubernetes dashboard

During the creation of the cluster, you'll see messages regarding the creation of the kubernetes-dashboard:

==> master: Configuring Kubernetes dashboard...
deployment "kubernetes-dashboard" created
service "kubernetes-dashboard" created
==> master: Kubernetes dashboard will be available at http://172.17.8.101:8080/ui

Visting the specified URL (in our case http://172.17.8.101:8080/ui) will present you with the dashboard:

Note that visiting the base URL (http://172.17.8.101:8080) will present a JSON file listing all exposed endpoints, including some very handy ones:

{
    "paths": [
        "/api",
        "/api/v1",
        "/apis",
        "/apis/",
        "/apis/admissionregistration.k8s.io",
        "/apis/admissionregistration.k8s.io/v1alpha1",
        "/apis/apiextensions.k8s.io",
        "/apis/apiextensions.k8s.io/v1beta1",
        "/apis/apiregistration.k8s.io",
        "/apis/apiregistration.k8s.io/v1beta1",
        "/apis/apps",
        "/apis/apps/v1beta1",
        "/apis/authentication.k8s.io",
        "/apis/authentication.k8s.io/v1",
        "/apis/authentication.k8s.io/v1beta1",
        "/apis/authorization.k8s.io",
        "/apis/authorization.k8s.io/v1",
        "/apis/authorization.k8s.io/v1beta1",
        "/apis/autoscaling",
        "/apis/autoscaling/v1",
        "/apis/batch",
        "/apis/batch/v1",
        "/apis/batch/v2alpha1",
        "/apis/certificates.k8s.io",
        "/apis/certificates.k8s.io/v1beta1",
        "/apis/extensions",
        "/apis/extensions/v1beta1",
        "/apis/networking.k8s.io",
        "/apis/networking.k8s.io/v1",
        "/apis/policy",
        "/apis/policy/v1beta1",
        "/apis/rbac.authorization.k8s.io",
        "/apis/rbac.authorization.k8s.io/v1alpha1",
        "/apis/rbac.authorization.k8s.io/v1beta1",
        "/apis/settings.k8s.io",
        "/apis/settings.k8s.io/v1alpha1",
        "/apis/storage.k8s.io",
        "/apis/storage.k8s.io/v1",
        "/apis/storage.k8s.io/v1beta1",
        "/healthz",
        "/healthz/autoregister-completion",
        "/healthz/ping",
        "/healthz/poststarthook/apiservice-registration-controller",
        "/healthz/poststarthook/apiservice-status-available-controller",
        "/healthz/poststarthook/bootstrap-controller",
        "/healthz/poststarthook/ca-registration",
        "/healthz/poststarthook/extensions/third-party-resources",
        "/healthz/poststarthook/generic-apiserver-start-informers",
        "/healthz/poststarthook/kube-apiserver-autoregistration",
        "/healthz/poststarthook/start-apiextensions-controllers",
        "/healthz/poststarthook/start-apiextensions-informers",
        "/healthz/poststarthook/start-kube-aggregator-informers",
        "/healthz/poststarthook/start-kube-apiserver-informers",
        "/logs",
        "/metrics",
        "/swagger-2.0.0.json",
        "/swagger-2.0.0.pb-v1",
        "/swagger-2.0.0.pb-v1.gz",
        "/swagger.json",
        "/swaggerapi",
        "/ui",
        "/ui/",
        "/version"
    ]
}

Installing MySQL and Wordpress

Once our cluster is running, we then need to use it; for this demonstration we'll run up MySQL and Wordpress as two separate services.

We're working from the Kubernetes example using MySQL and Wordpress, which is described in detail on the Kubernetes site as a tutorial, though we did find we needed to make a few tweaks to get everything working.

Create our directory and download the yaml files:

mkdir mysql-wordpress
cd mysql-wordpress

wget https://raw.githubusercontent.com/kubernetes/kubernetes/master/examples/mysql-wordpress-pd/local-volumes.yaml
wget https://raw.githubusercontent.com/kubernetes/kubernetes/master/examples/mysql-wordpress-pd/mysql-deployment.yaml
wget https://raw.githubusercontent.com/kubernetes/kubernetes/master/examples/mysql-wordpress-pd/wordpress-deployment.yaml

Amend local-volumes.yaml to add annotations, otherwise we get problems with Kubernetes not being able to connect the persistent volumes:

# Before:
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: mysql-pv-claim
labels:
    app: wordpress


# After:
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: mysql-pv-claim
annotations:
    volume.beta.kubernetes.io/storage-class: ""
labels:
    app: wordpress

Create our local persistent volume mounts.

Note: Any other Type of PersistentVolume would allow you to recreate the Deployments and Services at this point without losing data, but hostPath loses the data as soon as the Pod stops running. However, for the purposes of this demonstration, we're not worried about persisting data.

mkdir -p /tmp/data/pv-1
mkdir -p /tmp/data/pv-2

Create two PersistentVolumes from the local-volumes.yaml file:

kubectl create -f local-volumes.yaml

# display the persistent volumes:
kubectl get pv

NAME         CAPACITY   ACCESSMODES   RECLAIMPOLICY   STATUS    CLAIM                    STORAGECLASS   REASON    AGE
local-pv-1   20Gi       RWO           Retain          Bound     default/wp-pv-claim                               1h
local-pv-2   20Gi       RWO           Retain          Bound     default/mysql-pv-claim                            1h

Creating secrets for MySQL Password

The Kubernetes site has documentation about handling secrets; in our case we need to handle the MySQL password.

One option is to create a secret in a password file:

echo -n "WHATEVER" > ./password.txt
kubectl create secret generic mysql-pass --from-file=password.txt

# Display the existence of the secret
kubectl get secrets

In the mysql-deployment.yaml we'll then need to ensure the container spec is set accordingly:

# mysql-deployment.yaml
- name: MYSQL_ROOT_PASSWORD
  valueFrom:
    secretKeyRef:
      name: mysql-pass
      key: password.txt

Alternatively, we can create a literal secret, which is supplied directly on the command line:

# kubectl create secret generic mysql-pass --from-literal=password=WHATEVER

# Display the existence of the secret
kubectl get secrets

# mysql-deployment.yaml
- name: MYSQL_ROOT_PASSWORD
  valueFrom:
    secretKeyRef:
      name: mysql-pass
      key: password

Deploy MySQL

At this point we're ready to deploy MySQL:

# deploy MySQL
kubectl create -f mysql-deployment.yaml

# Show the pod as deployed
kubectl get pods

NAME                               READY     STATUS    RESTARTS   AGE
wordpress-mysql-2917821887-m4cgc   1/1       Running   0          1h

# Describe the deployment, including the assigned persistent volume
kubectl describe -f mysql-deployment.yaml

Find the node running MySQL via the pods in the Kubernetes UI; amongst other things, it will indicate which node the service is running on (172.17.8.103 in this case):

Inspect MySQL

# ssh into the node
ssh -i ~/.vagrant.d/insecure_private_key core@172.17.8.103


# find the running mysql container
docker ps -l

CONTAINER ID        IMAGE                                             COMMAND                  CREATED             STATUS              PORTS               NAMES
0c24ee28b333        mysql                                             "docker-entrypoint..."   29 seconds ago      Up 29 seconds                           k8s_mysql_wordpress-mysql-2917821887-r67gk_default_c269b585-abcb-11e7-bd0b-08002751ec84_0


# docker exec into the running mysql container
# and run a interactive bash shell
docker exec -it $(docker ps -ql) /bin/bash


# login to mysql with the previously-configured password
mysql -u root -p

Rolling back

If you encounter problems, it's quite easy to rollback the deployment:

# if you need to rollback:
kubectl delete service wordpress-mysql
kubectl delete deployment wordpress-mysql
kubectl delete pvc mysql-pv-claim

If you get really stuck, you can also delete the local persistant volume mounts, though you'll need to then recreate them if you want to re-deploy:

# Delete the local pv mounts
kubectl delete pv local-pv-1 local-pv-2

# Receate the pv mounts using local-volumes.yaml file:
kubectl create -f local-volumes.yaml

# Redeploy MySQL
kubectl create -f mysql-deployment.yaml

Deploy Wordpress

Deploying Wordpress is quite similar

# deploy wordpress
kubectl create -f wordpress-deployment.yaml


# Show the pod as deployed
kubectl get pods

NAME                               READY     STATUS    RESTARTS   AGE
wordpress-559664747-h22qq          1/1       Running   0          1h
wordpress-mysql-2917821887-m4cgc   1/1       Running   0          1h


# Describe the deployment, including the assigned persistent volume
kubectl describe -f wordpress-deployment.yaml

Check the Kubernetes UI to ensure that the Wordpress pod has deployed successfully.

We need to take note of the Cluster IP assigned to Wordpress, which can be seen on the UI under Services, or can be found via kubectl:

# find the internal ip
kubectl get services wordpress

NAME        CLUSTER-IP       EXTERNAL-IP   PORT(S)        AGE
wordpress   10.100.111.132   <pending>     80:32367/TCP   5m

Note that the Wordpress service will be shown as pending; this is nothing to worry about.

We'll also need to take note from the Kubernetes UI of Node that it's been assigned to; in our case it was 172.17.8.102.

Inspect Wordpress

# ssh into the node
ssh -i ~/.vagrant.d/insecure_private_key core@172.17.8.102

# then curl the page using the CLUSTER-IP from
# 'kubectl get services wordpress'.
# Note we follow the redirect
curl -i -L 10.100.111.132

# lots of HTML then follows...

Use the node ip, and the port reported in kubectl get services wordpress to get to the wordpress install screen in a browser; in our case the URL is http://172.17.8.102:32367

You should then see the familiar Wordpress install screen:

Rolling back

If you encounter problems, it's quite easy to rollback the deployment:

# if you need to rollback:
kubectl delete deployment wordpress
kubectl delete service wordpress
kubectl delete pvc wp-pv-claim

If you get really stuck, you can also delete the MySQL deployment and the local persistent volume mounts, though you'll need to then recreate them if you want to re-deploy:

# Delete the MySQL deployment
kubectl delete service wordpress-mysql
kubectl delete deployment wordpress-mysql
kubectl delete pvc mysql-pv-claim

# Delete the local pv mounts
kubectl delete pv local-pv-1 local-pv-2

# Receate the pv mounts using local-volumes.yaml file:
kubectl create -f local-volumes.yaml

# Redeploy MySQL
kubectl create -f mysql-deployment.yaml

# Redeploy Wordpress
kubectl create -f wordpress-deployment.yaml

Cleanup

Once you tire of your kubernetes cluster, cleanup is quite straightforward:

# Destroy the vagrant cluster
vagrant destroy

# Delete the local persistent volumes
kubectl delete pv local-pv-1 local-pv-2

# Remove the local mounts
rm -rf /tmp/data/pv-1/
rm -rf /tmp/data/pv-2/

Summary

There are plenty of other Kubernetes examples to play around with and plenty of other tutorials on the Kubernetes site, and possibly in a future post we'll look at deployment on a cloud service such as AWS.

Building Docker images on EC2 instances rather than on a local machine makes a lot of sense.

You get the benefits of a consistent build environment, as well as a typically much-faster network connection than you often enjoy locally.

However, there are some gotchas, and we look at these below.

Determining the Docker path

If you've been using Docker for Mac, then you've probably been using Docker at:

/usr/local/bin/docker

However, when moving to a Linux box, Docker instead is to be found at:

/usr/bin/docker

Setting Docker storage on EC2

Another particular problem that I've run across is ensuring that there's enough space for building large Docker images.

We use an ansible role to start an EC2 instance, and then push, pull and build Docker images using this EC2 instance.

Using our ansible role, we spin up an m3.large instance, particularly because we want the 32GB SSD that it comes with.

However, when we install Docker on the instance, the default setting for storage is in /var/lib/docker, whereas our 32GB SDD storage is mounted at /mnt.

On an m3.large the /dev/xvda1 mount / has a size of 7.8GB, which is not enough for some of the images we'll be building: ideally, Docker images should be kept as small as possible, however, we need to build some rather large monolithic applications, so we really need the space at /mnt.

This is not a problem when running a container from an image, as we can simply map the volume:

-v /mnt/docker/data:/root/monolithic-app-storage \

However, when building an image, although we can specify the volume in the Dockerfile, we can't map it to a location on disk, and therefore are reliant on there being enough disk space where the Docker images are stored.

Theoretically, we can simply change the $DOCKER_OPTS and restart docker:

mkdir -p /mnt/docker/data
export DOCKER_OPTS="-g /mnt/docker"
service docker restart

If this worked, we should see our $DOCKER_OPTS when we do the following:

ps -aux | grep docker

However, we don't, and this has been a problem that others have run across, such as here and here.

One answer (though possibly not the best), is to edit /lib/systemd/system/docker.service and add our desired storage location to the ExecStart variable:

ExecStart=/usr/bin/docker daemon -H fd:// $DOCKER_OPTS --graph /mnt/docker

When we look, we then see our mount point used for Docker:

ps -aux | grep docker

root     16939 11.0  0.5 540896 42388 ?        Ssl  04:18   2:40 /usr/bin/docker daemon -H fd:// --graph /mnt/docker

Note that if you've already pulled or built images, you'll either need to re-do this, or save and then load them.

AMP: Making the web great again

Since launching in October 2015, Google's Accelerated Mobile Pages (AMP) has quickly been building up momentum, with many of the major news publishers now on board.

AMP is an approach for making content-based websites fast to load, typically less than a second, and for many AMP-powered pages, almost instantly.

AMP can be regarded as similar in performance to Facebook Instant Articles, though with the important distinction of allowing publishers implementing AMP to control the publishing of their own content, unlike Facebook Instant Articles.

AMP is open-source, and the AMP team have been working with many of the third-party providers typically found on content sites (i.e. advertising, analytics, video etc) to ensure that third-party content loads fast on pages that employ the AMP approach.

For this post, we'll assume that you have a general understanding of how AMP works; if you haven't yet seen AMP in action, check the video on the AMP project site, the animated gif below, or see the real thing in action (you'll need to view this link on a mobile device, or in a mobile-sized viewport in dev tools).

We need Discipline

For web developers, AMP can be thought of as a way of enforcing discipline for good practice in making sites fast to load.

If you're a web developer, you can probably empathise with the image below.

Familiar with this?

Source has a great article providing reactions from web developers in the online news space, which includes some interesting allusions to the problems of guaranteeing good performance (in terms of speed) of news websites (my italics).

“I’m not optimistic that there is a business conversation around performance. I think we talk about a lot, as journalists, because we’re plugged into the trends and we love talking about ourselves. But I’m not convinced that news management is paying attention, or if they’re willing to make it a priority. I still have a lot of conversations where speed gets lip service, but we still cut “just this one” corner for business benefit X. Cut enough corners, and eventually you’re right back where you started.

Like so many things that we think are technical problems, these are actually questions of political will and support. If AMP succeeds at all ... it’ll be because its hardline stance on performance and third-party code can provide arguments for that leadership to advance.”

https://source.opennews.org/en-US/articles/what-amp-maybe-means-news-developers/

Importantly, AMP enforces discipline in two respects.

Firstly, development teams implementing AMP sites have to work according to the restrictions that AMP specifies. We'll look at those shortly, but suffice to say that AMP limits the options for teams to make make decisions that adversely affect performance, and provides an easy way to implement many of the measures that should be considered good practice when looking to make fast loading websites.

“AMP is basically web performance best practices dressed up as a file format.

That’s a very clever solution to what is, at heart, a cultural problem: when management (in one form or another) comes to the CMS team at a news organization and asks to add more junk to the site, saying “we can’t do that because AMP” is a much more powerful argument than trying to explain why a pop-over “Like us on Facebook!” modal is driving our readers to drink.”

https://source.opennews.org/en-US/articles/what-amp-maybe-means-news-developers/

Secondly, AMP enforces discipline regarding the performance of third-party code and content; development teams trying to produce fast websites are often hamstrung because of their lack of control over the performance of third-party code and content that the business mandates for inclusion in their pages. Lack-lustre performance from online advertisers, analytics providers, and video providers can often significantly contribute to the less than stellar loading peformance of many web pages, and can be at least partly blamed for the rise in interest in ad-blockers.

The AMP project have been working with many of the leading third-party providers to get them to serve their content via AMP-friendly mechanisms, and these third-party providers include the big names such as Adobe, Brightcove, Comscore, Chartbeat, Double-click. This improvement in performance of content from these providers can probably be regarded as the single most important achievement of the AMP project to date, as it addresses the major area that is beyond the control of the development teams producing news sites.

As one of the AMP team members, Malte Ubl, expressed it:

For AMP I was like: “What if we instrument pages just once and allow configuring the collected data to be sent to N analytics providers?”

So, we went and talked to many of them. And every single one was like: “That sounds like a great idea”.

With this launching really soon in AMP, if you have 15 analytics providers your page will be exactly as heavy as if you only had one.

What AMP is not

Not a solution for every site

AMP is not a universal panacea: it's only really applicable to templated content-based sites, and not really suitable for hand-crafted sites, which could be actually faster than AMP if done correctly.

Interestingly, the AMP team found that, of the major news organisations they partnered with to launch AMP, all but one reported that the AMP version of their content loaded in the browser significantly faster than the non-AMP version, with load times often improved by 50%-100% or more.

The one news organisaton whose AMP site actually performed 15% slower than their normal site was The Guardian, who everyone I think agrees were already doing a pretty good job of optimising their site before AMP appeared.

Not a great mechanism for custom content

AMP's focus is on producing a visual mobile experience that's leaner in some respects than it could be otherwise, and this means that it's not well suited to producing graphic one-off content, such as snow-falls, interactives and infographics.

As Thomas Wilburn from the Seattle Times mentioned in the Source article:

“The interactives team at the Seattle Times probably won’t use AMP directly at all. Our whole mission is to take advantage of everything a browser can do to tell stories–we’re already using best practices for fast pages, and almost everything we do requires custom JavaScript. But our stuff can’t go in our existing CMS either: we’ve had to find workarounds like responsive iframes or just hosting our own pages wholesale.

AMP isn’t really aimed at content like ours, which is a splashy but tiny percentage of everything the news industry puts out. It’s aimed at the article pages that IT departments write, where all our standard text content goes. Because generally, those pages suck.”

That said, there is at least one example from Google where an interactive treatment was achieved within the AMP restrictions, making heavy use of iframes to present the interactive elements.

AMP is geared towards content generators

Given their function in being a large producer of the sort of templated content that the AMP team are targetting, it should be no surprise that there is already support for AMP on Wordpress.com, as well as a plugin allowing those self-hosting their Wordpress sites to easily produce AMP-powered pages.

Medium have also announced that they will be supporting AMP, and we can probably expect other content publishing platforms to adopt AMP over the next few months.

AMP can also be seen as a good fit for those building progressive web apps, another recent technology paradigm that is also being heavily promoted by Google.

Progressive web apps offer some of the advantages enjoyed up to now by mobile apps, including fast load times, offline caching of content, and easy addition to the devices home screen, and allow web developers to better compete with mobile apps.

And if you think that mobile web apps are gaining advantages to the detriment of their app-based cousins, it should be noted that the convergence of mobile and web apps is happening from both directions, with deep-linking of app content offering mobile developers access to one of the web's characteristic advantages.

What's good for Google is good for the web

We shouldn't consider that Google are being solely altruistic with AMP — Google's business model is largely predicated on a healthy web economy, and although they control a number of aspects of the mobile app economy, they are in an on-going battle for advertising revenue with the likes of Facebook, who are successfully building up their share of the mobile app advertising market.

So, ensuring that the mobile web works fast and as seamlessly as possible with mobile apps can only be regarded as good business sense on Google's part.

AMP restrictions

In order to produce an AMP-powered site, you'll have to limit the way in which you create your pages, and major AMP restrictions include the following:

• CSS must be inlined in the head, and must be no larger than 50K (i.e. uncompressed)
• The only JavaScript directly allowed on the page (i.e. not in iframes) is the AMP JavaScript library
• Certain performance-expensive CSS selectors and HTML tags are not allowed, with AMP providing custom HTML tags in place of some, for example the <amp-img> tag instead of the normal <img> tag
• Third-party content is typically iframed in AMP-conformant components
• As a consequence, third-party code is much more restricted in what it can do; for example interstitals or take-over ads are not easily acheiveable on AMP-powered pages.

The good news

It's not all bad news though, and a number of the features that we consider essential on the modern web have good support under AMP:

• Web fonts are privileged, in that they are treated as the first HTTP request to be actioned on the page
• Most CSS selectors are allowed, and of those not allowed, the important (!) qualifier is probably going to be the one that developers miss the most
• AMP provides plenty of AMP-specific components for media including video, slideshows, audo and images
• Third-party JavaScript is allowed within the confines of iframes

AMP performance objectives

AMP considers performance not only in terms of speed, but also in terms of a better user experience when presenting content to the user as the page is loading.

This includes allowing the browser to determine the layout geometry of page components without having to fetch the external assets, such that the content doesn't jump around as the page is loading, and recommending the use of a CSS animation that fades in the page content only when it's ready for viewing.

“Predictable performance is a key design goal for AMP HTML. Primarily we are aiming at reducing the time until the content of a page can be consumed / used by the user. In concrete terms this means that:
HTTP requests necessary to render and fully layout the document should be minimized.
Resources such as images or ads should only be downloaded if they are likely to be seen by the user.

Browsers should be able to calculate the space needed by every resource on the page without fetching that resource.”

Learning from AMP

A number of the techniques that AMP employs can be thought of as simply good practice, and can be used without necessarily having to adopt AMP itself.

The easy stuff

• Ensure that there are zero HTTP requests until fonts start downloading
• Inline critical CSS, and keep overall size small
• Use resource hints: preload / preconnect / prefetch
• Allow browsers to calculate size of all components before fetching
• Lazy-loading of images and ads, such that only those that are in the viewport, or shortly to be in the viewport, are loaded
• Restrict CSS animations to GPU-friendly opacity and transform
• Make use of service workers to control caching

The harder stuff

There's a number of other techniques we can cherry-pick from AMP, though these may be harder to achieve than they would if we were directly using AMP:

• Keep third-party JS out of the critical path: async / defer loading of scripts
• Iframe expensive third-party JS, so that document.write doesn’t block overall page rendering
• Minimise style / layout calculations, using fastdom

Happily, implementing HTTP2 will go some way to promoting faster loading of pages, expecially if you use server-push and take advantage of pipelining assets through a single TCP connection.

Specific techniques

Looking through the AMP code, there's a few techniques that stand out as being particularly useful:

Preconnect polyfill

AMP implements a simple preconnect polyfill in the form of an intentional 404:

const url = origin + '/amp_preconnect_polyfill?' + Math.random();
const xhr = new XMLHttpRequest();
xhr.open('HEAD', url, true);
xhr.send();

“Preconnecting executes DNS lookup, TCP and SSL handshake. This saves 100+ms even on WIFI and can be seconds faster on a crappy mobile connection.”

Prefetch Polyfill

const prefetch = document.createElement('link');
prefetch.setAttribute('rel', 'prefetch');
prefetch.setAttribute('href', url);
document.head.appendChild(prefetch);

The above doesn’t work on Safari iOS; so alternatively (but wastefully):

new Image().src = urlToPrefetch

This will prefetch the URL and when it is actually fetched, it is served from cache. However, next time, when the resource is cached, but it wasn’t an image, it will fetch the resource again which wastes bandwidth.

Reduce Use of ES6 Polyfills

This may give developers piling into ES6 some pause for thought:

“We love ES6 and we love Babel, but unfortunately it turns out that some of its polyfills are heavy with respect to JavaScript size. Quite reluctantly we forked the core-js-shim (just one file) and only kept Array.from, Promise and Math.sign out of all the ES6 goodness.

Additionally we limited the syntactical ES6 features we use in the project to those that can be transpiled efficiently by Babel and created a custom Babel helpers file for that purpose”

The (practically) impossible

There are some techniques that AMP use which are probably very difficult to implement in large scale content publishing sites, including the coordiantion between iframes:

“AMP sandboxes all third party JS in cross-origin iframes.

Whichever is the first third party sandbox iframe on a page declare themselves as “master iframe” and then the second and further frames try to find that master in the parent.

This way we always have one special iframe that is the “master iframe”. This allows easy sharing of resources across iframes. Work can be done only once and reused by all the iframes that need it.”

AMP: the (possible) future

The AMP project is ongoing, and recent commentary from the AMP has been interesting in sketching out future developments.

JavaScript gets more privileges

Currently, AMP restricts custom and third-party JavaScript to second-class citizen status, only being able to operate within iframes.

In a piece about improving concurrency, Matli Ubl described his vision for AMP adopting a coordination role for controlling the execution and scheduling of other JavaScript, such that smooth page performance can be maintained at all times.

This would then allow custom and third-party JavaScript to be libterated from their iframe ghettos, and operate once more in an environment where they have access to the full page model.

Content Performance Policy

In a recent article, Tim Kadlec was critical of AMP's role, and posited the use of browser directives indicating what performance boundaries are not negotiable, using a mechanism similar to Content Security Policy.

As a result of this article, the AMP team got together with Tim Kadlec and Yoav Weiss, and drafted a proposal for something they're calling Sandbox Policy.

The Sandbox Policy is inspired by AMP and shares certain concepts and goals. By having a browser-enforced mechanism of “self-control”, i.e. the ability to modify or disable certain web platform capabilities, it enables the following two scenarios:

• Developers can lock down their application against regressions caused by own and third party resources; it enables violation auditing and reporting against specified standards.

• Third parties can validate enforced policies and use them as signals about runtime/UX/performance characteristics of the content.

This isn't envisaged as being a replacement for AMP, but rather a mechanism that could be used with or without AMP to enforce performance guidelines in the browser.

It'll be interesting to see what adoption this proposal gets, and it'd be great if we see a mechanism like this adopted across the board by the browser manufacturers.

Fast is important

Although those of us living in well-connected cities in the developed world take (reasonably) fast internet access for granted, we'd still find ourselves benefiting from the use of AMP as a mechanism to combat the year-on-year page bloat that we've been seeing for a while now, and which serves to obviate any advantage that we get from having faster devices and better network speeds.

And for those of us living in not-so-well-connected areas of the world, or still stuck on 3G connections, AMP provides something that approaches a seamless browsing experience.

Further reading

Reactions from News Media Organisations

• https://medium.com/@Rich_Harris/don-t-cramp-our-style-9bcef09e638f#.67zblyosk
• https://source.opennews.org/en-US/articles/what-amp-maybe-means-news-developers/
• http://www.niemanlab.org/2015/10/get-ampd-heres-what-publishers-need-to-know-about-googles-new-plan-to-speed-up-your-website/
• http://www.niemanlab.org/2015/12/static-is-the-new-interactive/

More about AMP

• https://medium.com/@cramforce/why-amp-is-fast-7d2ff1f48597#.e6b5smfhy
• https://medium.com/@cramforce/why-amp-html-does-not-take-full-advantage-of-the-preload-scanner-7e7f788aa94e#.7smx1owes
• https://medium.com/@cramforce/amps-and-websites-in-the-age-of-the-service-worker-8369841dc962#.ev2nwm5rq
• https://medium.com/@cramforce/not-so-micro-optimizations-f867c47b832d#.50bfl1j2m
• https://medium.com/@cramforce/2016-will-be-the-year-of-concurrency-on-the-web-c39b1e99b30f#.q5d4ldfuf

Good practice and scalability

In this post we're going to demonstrate running Docker containers using Amazon's Elastic Beanstalk.

When I was figuring out to use Docker containers on Amazon's Elastic Beanstalk, I seemed to find plenty of articles detailing how to manually setup Elastic Beanstalk using the AWS dashboard, but I really wanted a solution that was automatable / repeatable.

Specifically, with this project we want to be able to:

• Install and use Docker on Mac OSX (though other host platforms are fine)
• Build a custom apache-php5 Docker image using a Dockerfile, fully provisioned and ready for our app
• Build a php-app Docker image containing our custom app on top of this apache-php5 Docker image
• Push our Docker images to hub.docker.com
• Run up our application locally from the Docker images using Elastic Beanstalk's eb local run
• Run up our application remotely on AWS using Elastic Beanstalk's eb create / eb deploy
• Do all of the above in an automated fashion, using a Makefile

We want to follow good practice, and this involves splitting our database and application into separate containers. This will then alow us to scale up application containers and database containers independently.

For the local install, we'll deploy both the application and database container on the same host, but when deploying for production, we'll use RDS to serve our database, and an EC2 instance dedicated to each application container.

Presuming that our application is PHP heavy but database light (say, because it only uses the database for login / personal profile storage), we can probably get away with a single
database container / RDS instance, while scaling up more EC2 instances of our application container when demand increases.

Our app will do nothing more arduous than displaying the information generated by phpinfo() (on the php-app container) and show that it can connect to a MySQL database (on the mysql container if local or the using RDS if deployed on AWS).

However, you should easily be able to build out a much more complicated PHP application after
reading through these notes.

Note that we build an apache-php5 Docker image first, and then another php-app image containing our app on top of this image. This allows us to re-use the existing apache-php5 Docker image whenever our app changes, and thus speeds up our builds.

All code for this project can be found at https://github.com/jcdarwin/local-elasticbeanstalk-php-demo

Requirements

We're doing this on OSX, but it should work on typical linux variants.
We're presuming that you've got installed:

• homebrew (Mac OSX package manager)
• GNU make
• a public/private key pair, created and registered on AWS,
  and stored locally, e.g.:

~/.ssh/aws-eb
~/.ssh/aws-eb.pub

We're also presuming that you're reasonably comfortable with the principles behind Docker, and have probably already had some exposure to AWS.

Configuration

We'll use a local shell script, .env_local, not versiond in git, to store our custom / sensitive details and implement them as environment variables.
This should be the only place we have to regularly make changes, and is used by our Makefile when running build steps:

#!/bin/bash

export EB_APP=local-elasticbeanstalk
export EB_ENVIRONMENT=dev-$EB_APP
export EB_SCALE_MIN=2

export DOCKER_MACHINE=default
export DOCKER_USER=mebooks
export DOCKER_EMAIL=jcdarwin@gmail.com
export DOCKER_PASSWORD=bailter

DOCKERED=eval "$(docker-machine env $DOCKER_MACHINE)"

Set execute permissions on this file:

chmod a+g .env_local

Note that running the .env_local loads the environment so we can use docker (once installed) from the local OSX terminal, and does the same as:

eval "$(docker-machine env default)"

Installation

We use docker-machine on OSX via the Docker ToolBox.

The easiest way to do this is:

brew cask install dockertoolbox

As we're using Max OSX, this means that we'll end up with a Virtualbox Linux VM that will be used to run Docker.

Start our docker-machine:

docker-machine start default

Setup docker so we can use it from our current shell

Port-forward in VirtualBox, so we can access port 80 transparently:

VBoxManage list vms
VBoxManage modifyvm "defaut" --natpf1 "guestnginx,tcp,,80,,80"

Once installed, we can see that docker is at version 10.1:

docker -v
$ Docker version 1.10.2, build c3959b1

If we apply our environment variables:

. ./.env_local

we should then see our environment values based on docker-machine config default plus any extra that we've added in .env_local:

env | grep DOCKER

    DOCKER_PASSWORD=WHATEVER
    DOCKER_HOST=tcp://192.168.99.101:2376
    DOCKER_MACHINE_NAME=default
    DOCKER_TLS_VERIFY=1
    DOCKER_MACHINE=default
    DOCKER_USER=mebooks
    DOCKER_CERT_PATH=/Users/jasondarwin/.docker/machine/machines/default
    DOCKER_EMAIL=jcdarwin@gmail.com

and we should be able to access docker directly

docker info

Install awsebcli

We install the awsebcli using homebrew:

brew install awsebcli

However, there's a problem with the version compatibility check, meaning that awsebcli thinks that docker 1.10.2 is < docker 1.6, and we receive the following message:

"You must install Docker version 1.6.0 to continue. If you are using Mac OS X, ensure you have boot2docker version 1.6.0. Currently, "eb local" does not support Windows."

To rectify this, currently we must edit /usr/local/Cellar/aws-elasticbeanstalk/3.7.3/libexec/lib/python2.7/site-packages/ebcli/containers/compat.py as follows:

def supported_docker_installed():
    """
    Return whether proper Docker version is installed.
    :return: bool
    """

    try:
        #return commands.version() >= SUPPORTED_DOCKER_V
        return True
    # OSError = Not installed
    # CommandError = docker versions less than 1.5 give exit code 1
    # with 'docker --version'.
    except (OSError, CommandError):
        return False

Install Composer

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Use composer to install the dependencies for our php-app

cd php-app
composer install

App environment variables

We need to make certain environment variables available to our PHP scripts, particularly
those to do with connecting to our MySQL container.

To do this, we create a php-app/.env file, with placeholders for the expected
environment variables:

# php-app/.env
# The variables below are replaced during container startup by init.sh

# If we're using a local mysql container, the MYSQL variables are populated
#DB_HOST="${MYSQLDB_PORT_3306_TCP_ADDR}"
#DB_DATABASE="${MYSQLDB_ENV_MYSQL_DATABASE}"
#DB_PASSWORD="${MYSQLDB_ENV_MYSQL_ROOT_PASSWORD}"
#DB_USERNAME="${MYSQLDB_ENV_MYSQL_USERNAME}"

# If we;re using an AWS RDS instance, the RDS  variables are populated
#DB_HOST="${RDS_HOSTNAME}"
#DB_DATABASE="${RDS_DB_NAME}"
#DB_PASSWORD="${RDS_PASSWORD}"
#DB_USERNAME="${RDS_USERNAME}"

We then use our init.sh script to read the environment variables during the initialisation of our php-app container, and replace the placeholders in php-app/.env with the environment variables values:

# Make a copy of our .env file, as we don't want to pollute the original
cp /var/www/html/.env /tmp/

# Update the app configuration to make the service environment
# variables available.
function setEnvironmentVariable() {
    if [ -z "$2" ]; then
        echo "Environment variable '$1' not set."
        return
    fi

    # Check whether variable already exists
    if grep -q "\${$1}" /tmp/.env; then
        # Reset variable
        sed -i "s/\${$1}/$2/g" /tmp/.env
    fi
}

# Grep for variables that look like MySQL (for local deployments)
# or RDS (for remote deployments).
for _curVar in `env | grep 'MYSQL\|RDS' | awk -F = '{print $1}'`;do
    # awk has split them by the equals sign
    # Pass the name and value to our function
    setEnvironmentVariable ${_curVar} ${!_curVar}
done

# Now that /tmp/.env is populated, we can start/restart apache
# and let our PHP scripts access them.
service apache2 restart

Create our Makefile

We use a Makefile to make our builds slightly easier:

include .env_local
BASE_IMAGE=mebooks/apache-php5
APP_IMAGE=mebooks/php-app
APP=php-app
VERSION=`git describe --tags`
CORE_VERSION=HEAD

all: build-base prepare

base: build-base push-base

app: prepare-app build-app push-app

environment: create-environment

#
# Our base image tasks
#
build-base:
    docker build -t $(BASE_IMAGE):$(VERSION) docker/base

push-base:
    docker login --username=$(DOCKER_USER) --email=$(DOCKER_EMAIL) --password=$(DOCKER_PASSWORD)
    docker push $(BASE_IMAGE)

#
# Our app image tasks
#
prepare-app:
    # Update Dockerrun.aws.json with the current image version
    sed -i '' "s~${APP_IMAGE}\:[^\"]*~${APP_IMAGE}\:$(VERSION)~g" Dockerrun.aws.json
    git archive --format tgz HEAD $(APP) > docker/app/$(APP).tgz

build-app:
    docker build -t $(APP_IMAGE):$(VERSION) docker/app

push-app:
    docker login --username=$(DOCKER_USER) --email=$(DOCKER_EMAIL) --password=$(DOCKER_PASSWORD)
    docker push $(APP_IMAGE)

#
# Our Elastic Beanstalk tasks
#
create-environment:
    eb create -v \
        --cfg $(EB_APP) \
        --scale $(EB_SCALE_MIN) \
        --cname $(EB_ENVIRONMENT) \
        $(EB_ENVIRONMENT)

Build the docker images

Commit and tag our changes, e.g.:

    git tag 2.3.0

The use of git describe --tags in the Makefile means that we'll be using the latest git tag to tag our Docker images.
Note that, if you've made commits since your last git tag, we'll end up using a tag value which is a combination of the tag and the last commit hash:

git describe --tags
    2.4.0-9-g8215032

Build our mebooks/apache-php5 base Docker image

    # Create the `mebooks/apache-php5` Docker image
    make base

    # Check that the image was created
    docker images

Edit docker/app/Dockerfile and ensure that our php-app is refering to the same version as that that we just built:

    FROM mebooks/apache-php5:2.3.0

Our mebooks/apache-php5 Docker image should only need updating when we want to update the packages in the distribution, such as when there are security vulnerabilities.

Build our app docker image

Note that our app docker image wil be tagged with the current version of the repo and our Dockerrun.aws.json file will be updated accordingly.

# Create our php-app image and push it to hub.docker.com
make app

# Check that we updated the image version in our `Dockerrun.aws.json`
cat Dockerrun.aws.json | grep 'Name'
    "Name": "mebooks/php-app:2.4.0-8-gb0eef33",

As we've just tagged our Dockerrun.aws.json file with the current version of the repo,
we need to commit changes, otherwise the eb create / eb deploy (which makes use of git archive) will use the previous version of the Dockerrun.aws.json file.

Note that, as eb create / eb deploy uses git archive to create a zipfile of our application for deployment, this means that:

• we can use .gitignore to specify files that shouldn't be under version control
• we can use .gitattributes to specify files that should be under version control but should be deployed in the app bundle.

eb create / eb deploy can also make use of a .ebignore file.

Check that our containers function as expected

# Set our environment variable
VERSION=`git describe --tags` && echo $VERSION

# Start just the PHP container
docker run -tid -p 80:80 \
    --name=php-app \
    mebooks/php-app:${VERSION}

# Start both containers linked
docker run -p 3306:3306 \
    -e MYSQL_USERNAME=root \
    -e MYSQL_ROOT_PASSWORD=password \
    -e MYSQL_DATABASE=my_db \
    -d \
    --name mysqlserver \
    mysql

docker run -tid -p 80:80 \
    --name=php-app \
    --link mysqlserver:mysqldb \
    mebooks/php-app:${VERSION}

We should now be able to see the PHP Info details at the address reported by docker-machine ip, e.g.:

docker-machine ip
    http://192.168.99.101/

If we've started the mysql container, we should also be able to see a simple example of connecting to our MySQL database at http://192.168.99.101/mysql.php

Push our images to hub.docker

Although our Makefile handles the pushing of our containers to hub.docker, we'll cover it here as we need to know about AWS using the associated config file to gain access to pull our images from hub.docker.

Login to our docker account:

# Enter the username, password and email when prompted
docker login

# Alternatively, specify username, email and password
# If any of these parameters are not supplied, you'll be prompted for them
docker login --username=mebooks --email=jcdarwin@gmail.com --password=WHATEVER

The login will create a config file at ~/.docker/config.json.

AWS currently uses an older format of the docker config for authentication to hub.docker,
so we need to change our current ~/.docker/config.json to the required format by removing the auths wrapper:

# ~/.docker/config.json
{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "WHATEVER",
            "email": "jcdarwin@gmail.com"
        }
    }
}

becomes:

# ~/.docker/.dockercfg.json
{
        "https://index.docker.io/v1/": {
            "auth": "WHATEVER",
            "email": "jcdarwin@gmail.com"
        }
}

We now need to push this to a suitable s3 bucket so Elastic Beanstalk can use it to download our images from our private repository.

s3cmd put ~/.docker/.dockercfg.json s3://elasticbeanstalk-ap-southeast-2-<aws_account_id>

Pushing our images to hub.docker is as simple as:

docker push mebooks/apache-php5
docker push mebooks/php-app

Note that the make app task automatically does the docker push mebooks/php-app, while the make base task automatically does the docker push mebooks/apache-php5,

Once pushed, we should be able to see our images on hub.docker:

https://hub.docker.com/r/mebooks/php-app/tags/
https://hub.docker.com/r/mebooks/apache-php5/tags/

Create our ECR respositories

Alternatively, in this section we'll look at using Amazon's Elastic Container Registry (ECR) as a place to store our images instead of using hub.docker.

Authenticate Docker to an Amazon ECR registry with get-login:

aws ecr --profile oregon get-login

docker login -u AWS -p BIGLONGNUMBERAPPEARSHERE -e none https://<aws_account_id>.dkr.ecr.us-west-2.amazonaws.com

Note that https://<aws_account_id>.dkr.ecr.us-west-2.amazonaws.com is the URL for our container registry.

Copy and paste the docker login command into a terminal to authenticate your Docker CLI to the registry. This command provides an authorization token that is valid for the specified registry for 12 hours.

Create our repositories:

aws ecr create-repository --profile oregon --repository-name mebooks/apache-php5

    registryId: <aws_account_id>
    repositoryArn: arn:aws:ecr:us-west-2:<aws_account_id>:repository/mebooks/apache-php5
    repositoryName: mebooks/apache-php5

aws ecr create-repository --profile oregon --repository-name mebooks/php-app

    registryId: <aws_account_id>
    repositoryArn: arn:aws:ecr:us-west-2:<aws_account_id>:repository/mebooks/php-app
    repositoryName: mebooks/php-app

Tag our images and push them

docker tag mebooks/apache-php5:latest <aws_account_id>.dkr.ecr.us-west-2.amazonaws.com/mebooks/apache-php5:latest

docker push <aws_account_id>.dkr.ecr.us-west-2.amazonaws.com/mebooks/apache-php5:latest

docker tag mebooks/php-app:2.4.0-8-gb0eef33 <aws_account_id>.dkr.ecr.us-west-2.amazonaws.com/mebooks/php-app:2.4.0-8-gb0eef33

docker push <aws_account_id>.dkr.ecr.us-west-2.amazonaws.com/mebooks/php-app:2.4.0-8-gb0eef33

Create our Dockerrun.aws.json (multi-container version)

We can use a multi-container Dockerrun.aws.json if we want to use eb local run to spin up both our php-app container and an associated mysql container.

{
    "AWSEBDockerrunVersion": 2,
    "containerDefinitions": [
        {
            "name": "mysql",
            "image": "mysql:5.6",
            "essential": true,
            "portMappings": [
                {
                    "hostPort": 3306,
                    "containerPort": 3306
                }
            ],
            "environment": [
                {
                    "name": "MYSQL_USERNAME",
                    "value": "root"
                },
                {
                    "name": "MYSQL_PASSWORD",
                    "value": "password"
                },
                {
                    "name": "MYSQL_DB_NAME",
                    "value": "my_db"
                }
            ]
        },
        {
            "name": "php-app",
            "image": "mebooks/php-app",
            "essential": true,
            "memory": 128,
            "portMappings": [
                {
                    "hostPort": 80,
                    "containerPort": 80
                }
            ],
            "links": [
                "mysql"
            ]
        }
    ]
}

Note that we specify a (very) weak MYSQL_ROOT_PASSWORD in our Dockerrun.aws.json — you'll want to change this and ideally not have it under version control.

Run our containers locally

Finally, use eb local to create our docker containers locally:

eb local run

In a second terminal:

eb local status
docker ps

Accessing the containers locally

Find the appropriate container id, and start a bash shell on it:

docker ps

$ CONTAINER ID        IMAGE
$ 832af3ff45d8        mebooks/apache-php5:latest
$ fc6a9553583f        mysql:5.6

# Access our PHP container
docker exec -it 832af3ff45d8 bash

Alternatively, we can use eb to find the details, including the human-readable container names:

eb local status

$ Platform: 64bit Amazon Linux 2015.09 v2.0.8 running Multi-container Docker 1.9.1 (Generic)
$ Container name: elasticbeanstalk_mysql_1
$ Container ip: 127.0.0.1
$ Container running: True
$ Exposed host port(s): 3306
$ Full local URL(s): 127.0.0.1:3306

$ Container name: elasticbeanstalk_phpapache_1
$ Container ip: 127.0.0.1
$ Container running: True
$ Exposed host port(s): 80
$ Full local URL(s): 127.0.0.1:80

Access our PHP container:

docker exec -it elasticbeanstalk_phpapache_1 bash

# check our apache config
apachectl configtest

# view our apache config
cat /etc/apache2/sites-enabled/vhost.conf

# Find the ip of our MySQL container
env | grep MYSQL_1_PORT_3306_TCP_ADDR

$ ELASTICBEANSTALK_MYSQL_1_PORT_3306_TCP_ADDR=172.17.0.2
$ MYSQL_1_PORT_3306_TCP_ADDR=172.17.0.2

# Login to mysql
mysql -u root -h 172.17.0.2  -p

Access our MySQL container:

docker exec -it elasticbeanstalk_mysql_1 bash

# Display our databases -- we should see my_db
mysql -u root -p -e "show databases;"

Create our Dockerrun.aws.json (single container version)

Although the multi-container version above is useful for testing locally, in production we'll be using RDS to host MySQL, so we'll use a single container Dockerrun.aws.json to deploy our php-app container, and use an Amazon RDS instance for our database.

{
    "AWSEBDockerrunVersion": 1,
    "Image": {
        "Name": "mebooks/php-app:2.4.0-8-gb0eef33",
        "Update": "true"
    },
    "Authentication": {
        "Bucket": "elasticbeanstalk-ap-southeast-2-<aws_account_id>",
        "Key": ".dockercfg.json"
    },
    "Ports": [
        {
            "ContainerPort": "80"
        }
    ],
    "Logging": "/var/log/apache2"
}

Initialise our Elastic Beanstalk app

Now that we're happy with the running the containers up locally, we need to initialise our .elasticbeanstalk/config.yml so we can deploy our containers to AWS:

    eb init

More info about the eb cli tool is to be found on the Amazon site.

We'll need to customise our configuration, so create a standard config as a starting point:

# This creates `.elasticbeanstalk/local-elasticbeanstalk.env.yml`
eb config

Ensure we have settings as we want, e.g. the MinSize for autoscaling:

  aws:autoscaling:asg:
    Availability Zones: Any
    Cooldown: '360'
    Custom Availability Zones: 'ap-southeast-2'
    MaxSize: '4'
    MinSize: '2'

Create our Elastic Beanstalk application environment

Refer https://github.com/hopsoft/relay/wiki/How-to-Deploy-Docker-apps-to-Elastic-Beanstalk

# Ensure `.env_local` specifies the correct `EB_ENVIRONMENT`:
export EB_ENVIRONMENT=dev-local-elasticbeanstalk

# Create our new environment on Elastic Beanstalk
make environment

make environment effectively runs something like the following, depending on
your environment variable settings in .env_local:

eb create -v \
    --scale 2
    --cname dev-local-elasticbeanstalk \
    dev-local-elasticbeanstalk

We should then see output at our terminal like the following:

    INFO: Creating new application version using project code
    WARNING: You have uncommitted changes.
    INFO: Getting version label from git with git-describe
    Creating application version archive "app-8215-160402_175219".
    INFO: creating zip using git archive HEAD
    INFO: git archive output: Dockerrun.aws.json
    php-app/
    php-app/.env
    php-app/composer.json
    php-app/composer.lock
    php-app/public/
    php-app/public/index.php
    php-app/public/mysql.php
    INFO: Uploading archive to s3 location: local-elasticbeanstalk-php-demo/app-8215-160402_175219.zip
    Uploading local-elasticbeanstalk-php-demo/app-8215-160402_175219.zip to S3. This may take a while.
    Upload Complete.
    INFO: Creating AppVersion app-8215-160402_175219
    INFO: Creating new environment
    Environment details for: dev-local-elasticbeanstalk
      Application name: local-elasticbeanstalk-php-demo
      Region: ap-southeast-2
      Deployed Version: app-8215-160402_175219
      Environment ID: e-myq9pzyjxg
      Platform: 64bit Amazon Linux 2015.09 v2.0.8 running Docker 1.9.1
      Tier: WebServer-Standard
      CNAME: dev-local-elasticbeanstalk.ap-southeast-2.elasticbeanstalk.com
      Updated: 2016-04-02 04:52:24.369000+00:00
    Printing Status:
    INFO: createEnvironment is starting.
    INFO: Using elasticbeanstalk-ap-southeast-2-<aws_account_id> as Amazon S3 storage bucket for environment data.
     -- Events -- (safe to Ctrl+C)

# CTRL-C when prompted, and follow progress:
eb status

If we want to reference an existing config, we can do this during creation:

    eb create -v --cfg local-elasticbeanstalk

Note that eb create will use the settings from .gitattributes to export-ignore files in the zip file that it creates and uploads to s3.
As such, we have to be careful that the Dockerrun.aws.json file is included in the root level of our zip file.

Creating application version archive "app-4bbe-160402_140739".
Uploading local-elasticbeanstalk-php-demo/app-4bbe-160402_140739.zip to S3. This may take a while.

If we wish, we can easily download this zip file and inspect the contents:

s3cmd get s3://elasticbeanstalk-ap-southeast-2-<aws_account_id>/local-elasticbeanstalk-php-demo/app-4bbe-160402_140739.zip

Once created (and even during creation), we will see our envionment in our AWS dashboard:
https://ap-southeast-2.console.aws.amazon.com/elasticbeanstalk/home

RDS

We now need to create our RDS instance.
For this project we'll use:

• RDS MySQL
• T2 Small
• Multi-AZ
• Allocated storage: 5GB
• DB Instance Identifier: mebooks-mysql-dbinstance
• Master Username: root

Using Multi-AZ ensures that we mitigate the chance of failure by having our main RDS instance in one availability zone, and a RDS failover in another availability zone.
Ensure that the security group used for the RDS instance allows connections to and from port 3306, and that the EC2 instances will be also using this security group.

Importantly, we should ensure that our RDS instance is private, but set to use the same VPC as our EC2 instances.

Once setup, we should be able to connect from an EC2 instance in the same group as follows (depending on the actual assigned RDS endpoint):

mysql -h mebooks-mysql-dbinstance.criieggarwwz.ap-southeast-2.rds.amazonaws.com -u root -p

As per this answer, there's currently no easy way to automate the attachment of an RDS database existing outside of an Elastic Beanstalk environment to the environment during creation.
Amazon seem to assume that you'll be wanting to create an RDS instance inside the Elastic Beanstalk environment, which means that your database becomes less independent, and may disappear should anything go wrong with your Elastic Beanstalk environment.

Instead, if you want the RDS instance to exist outside of the environment you can simply provide the connection parameters as environment variables via the EB Console: Configuration -> Web Layer -> Software Configuration:

RDS_HOSTNAME: mebooks-mysql-dbinstance.criieggarwwz.ap-southeast-2.rds.amazonaws.com
RDS_DB_NAME : my_db
RDS_USERNAME: root
RDS_PASSWORD: WHATEVER

These environment variables can then be accessed from inside your PHP app.

This does mean that our application will not be able to connect to our database on the initial deployment during the eb create, as we won't have yet had the chance to set these RDS
environment variables in the EB dashboard.

Note that with this method, as the RDS_PASSWORD will be in plain sight on the AWS dashboard, it's probably wise to change this regularly. When you make changes to your environment variables on the EB dashboard and click apply, Elastic Beanstalk will then re-provision your existing EC2 instances with the new values.

Accessing our application

To see our application in the browser, we can use:

# opens a browser tab with something like:
# http://dev-local-elasticbeanstalk.ap-southeast-2.elasticbeanstalk.com/
eb open

We should see our PHP Info page, and be able to see our database connection details at /mysql.php.

Once our Elastic Beanstalk cluster is running , we can ssh into our load balancer, and then telnet to our instances:

# once sshed into the load balancer, you'll be presented with a choice of the
# EC2 instances if there are more than one.
eb ssh
sudo -s
yum install telnet
telnet mebooks-mysql-dbinstance.criieggarwwz.ap-southeast-2.rds.amazonaws.com

Once we know the public DNS of our ec2 instance, we can also directly ssh in as ec2-user:

ssh -i ~/.ssh/aws-eb  ec2-user@ec2-52-62-4-141.ap-southeast-2.compute.amazonaws.com

# Once logged in, elevate to root to be able to acces docker:
sudo -s

Redeploying

Presuming that we're only updating our custom php-app code, successive deployments should be a matter of the following:

# create the image and push it to hub.docker
make app

As make app tagged our Dockerrun.aws.json file with the current version of the repo, we need to commit the changes, otherwise the eb create / eb deploy (which uses git archive) will use the previously-committed version of the Dockerrun.aws.json file.

git add Dockerrun.aws.json
git commit -m "Updated Docker image tag in Dockerrun.aws.json"

eb deploy -v local-elasticbeanstalk

Terminating

Once we've finished with a particular environment, we can terminate it:

eb terminate local-elasticbeanstalk

Cleaning up

Once we're finished, we can remove our containers locally, either by id or by name

docker rm 832af3ff45d8 fc6a9553583f

If we're finished with our image, we can delete it:

docker rmi mebooks/php-app
docker rmi mebooks/apache-php5

Summary

Hopefuly the above is well-enough detailed to help you get to grips with Elastic Beanstalk.

It's a great mechanism for easily deploying a scalable Docker-based application, and all the better when we can automate the creation and deployment of our environments and applications.

In case using a Makefile as we did here becomes a bit limiting, you may want to look at using something like Ansible to automate the creation and deployment tasks, and there's
a great example of this at https://github.com/hsingh/ansible-elastic-beanstalk.

Elastic Beankstalk is a very handy service, but should you want to create a more enterprise-level cloud application, you might also want to look at something like RedHat's OpenShift Origin.

However, being a developer rather than operations, I found the method outlined above
suited me, as it was more Dev-ops (with a big 'D') rather than dev-Ops (with a big 'O').

Further reading

In putting together the above, I found these posts of help:

• http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_docker-eblocal.html
• http://victorlin.me/posts/2014/11/26/running-docker-with-aws-elastic-beanstalk
• https://github.com/hopsoft/relay/wiki/How-to-Deploy-Docker-apps-to-Elastic-Beanstalk
• http://www.sitepoint.com/docker-and-dockerfiles-made-easy/
• http://www.michaelgallego.fr/blog/2015/07/18/using-elastic-beanstalk-multi-container-with-php/

Image courtesy of Jay Mantri.

Making https fast

Let’s Encrypt is a great initiative allowing anyone to easily generate and install SSL certificates so that traffic can be securely served over https.

As well as gaining the benefits of secure traffic, by using https we're also setting ourselves up to benefit from HTTP/2, which will allow a number of performance benefits, but is only available over https.

However, generating and installing SSL certificates using Let’s Encrypt doesn't inherently make our site faster, and actually adds some overhead in terms of extra negotiation between the client and the server, as well as requiring the client to check with the certificate authorities to determine whether a certificate has been revoked (at least until we configure the server to take over this task using OCSP stapling.)

Two great measures for improving website performance are Varnish and Google's Pagespeed Module for Apache and Nginx.

Below, we'll look at how to generate and install SSL certificates with Let’s Encrypt, and then how to configure our site so that we can still make use of Varnish and the Pagespeed Module to optimise our site performance.

We're assuming here that you've already got a site up and running using Varnish, and Apache/Nginx, serving http traffic on port 80.

Let’s Encrypt

Let’s Encrypt is now in public beta, meaning that it's available for anyone to use, though you'll need to be aware of the rate-limiting to prevent abuse of the service, the most relevant parts of which are:

• Names/Certificate is the limit on how many domain names you can include in a single certificate. This is currently limited to 100 names, or websites, per certificate issued.

• Certificates/Domain you could run into through repeated re-issuance. This limit measures certificates issued for a given combination of Public Suffix + Domain (a "registered domain"). This is limited to 5 certificates per domain per week.

To install and use Let’s Encrypt, we'll do the following (presuming you're running Ubunutu or Debian):

# Create a directory for letsencrypt
mkdir /usr/local/letsencrypt

# Clone letsencrypt from the repo.
# You may want to adjust the release tag
cd /usr/local/letsencrypt
git clone https://github.com/letsencrypt/letsencrypt.git#v0.4.2

# Stop any webservers
service apache2 stop
service nginx stop

# Run letsencrypt to create our certificate.
./letsencrypt-auto certonly --email whoever@gmail.com --agree-tos \
    -d whatever.nz -d www.whatever.nz \
    -d whatever.co.nz -d www.whatever.co.nz

Note that we stop our webservers before running letsencrypt, as it needs to use ports 80 and 443 for communication with the certificate authorities.

We're also using --agree-tos to automatically agree to the terms of service, and --email to provide our email so that letsencrypt can create our account. We actually use Ansible configuration management scripts for provisioning our webservers and so need these scripts to run automatically, but in the interests of simplicity, we're not showing that here.

Letsencrypt can include a number of domains on a given certificate (currently up to a 100), though it can't produce wildcard certificates, and we use the -d option above to specify each domain.

Note also that we're using the certonly function; letsencrypt can automatically update webserver configuration files to use the newly generated certificate, but in our case we're going to use Pound to handle https, and our webservers will therefore only be dealing with http traffic.

More information about running letsencrypt can be found on the letsencrypt site.

Letsencypt certificates are currently valid for 90 days, and in the interests of making life easier for ourselves, we'll set up a cron job to automatically attempt to renew the certificate on a weekly basis. Our bash script, /usr/local/letsencrypt/letsencrypt-auto-renew.sh, is as follows:

#!/bin/bash

# letsencrypt needs access to port 80
monit stop pound

# To simulate a dry-run near the end of the certificate term:
# /usr/local/letsencrypt/letsencrypt-auto renew --dry-run --email mebooks.support@gmail.com --agree-tos
if ! /usr/local/letsencrypt/letsencrypt-auto renew --email mebooks.support@gmail.com --agree-tos > /var/log/le-renew.log 2>&1; then
    echo Automated renewal failed:
    cat /var/log/le-renew.log
    exit 1
fi

# Restart pound
monit start pound

# Cat the privkey and fullchain for pound
cat /etc/letsencrypt/live/whatever.co.nz/privkey.pem /etc/letsencrypt/live/whatever.co.nz/fullchain.pem > /etc/letsencrypt/archive/whatever.co.nz/privkey_fullchain.pem

# Recreate the symlink
unlink /etc/letsencrypt/live/whatever.co.nz/privkey_fullchain.pem
ln -s /etc/letsencrypt/archive/whatever.co.nz/privkey_fullchain.pem /etc/letsencrypt/live/whatever.co.nz/privkey_fullchain.pem

We can ensure that this runs on a weekly frequency by entering a line in our cron file, using crontab -e:

# m h  dom mon dow   command
 30 2  *   *   1     /usr/local/letsencrypt/letsencrypt-auto-renew.sh >> /var/log/le-renew.log

So, we've now got a newly-generated certificate installed, but we actually need to make some use of it.

Varnish

Varnish provides a great http caching layer for websites, and is probably the single most important mechanism for ensuring that your site can serve traffic quickly to a large audience.

However, Varnish only serves traffic via http, and this comment from the maintainer makes it pretty clear it's unlikely it will ever have support for https:

Would I be able to write a better stand-alone SSL proxy process than the many which already exists ?

Probably not, unless I also write my own SSL implementation library, including support for hardware crypto engines and the works.

That is not one of the things I dreamt about doing as a kid and if I dream about it now I call it a nightmare.

So, if we want to use https, we have to use another service in front of Varnish to proxy https traffic as http to and from Varnish.

If you are using Varnish to directly cache traffic on port 80, your /etc/default/varnish would probably have a line that looks like:

DAEMON_OPTS="-a :80 \

However, as we'll now use Pound to receive traffic in front of Varnish, we'll ensure that Varnish is receiving traffic on its default port of 6081:

DAEMON_OPTS="-a :6081 \

Enter Pound

Pound is a great project, and works very nicely in front of Varnish as reverse proxy, accepting http and/or https traffic as configured, and passing it through to Varnish as http.

In order to be able to disable the SSLv3 protocol to cope with the POODLE vulnerability, we'll need to use Pound 2.7f, as outlined here. Currently, the standard Ubuntu repositories only make Pound 2.6 available.

# Add the PPA
sudo add-apt-repository 'deb https://mslinn-ppa.s3.amazonaws.com stable main'

# Update our apt-get cache
sudo apt-get update

# Check that we see: Candidate:2.7f-0ubuntu1
sudo apt-cache policy pound

# Install Pound
sudo apt-get install pound

Once installed, we'll use the following /etc/pound/pound.cfg:

## Minimal sample pound.cfg
##
## see pound(8) for details
######################################################################
## global options:

User            "www-data"
Group           "www-data"
#RootJail       "/chroot/pound"

## Logging: (goes to syslog by default)
##      0       no logging
##      1       normal
##      2       extended
##      3       Apache-style (common log format)
LogLevel        1

## check backend every X secs:
Alive           30

## use hardware-accelleration card supported by openssl(1):
#SSLEngine      "<hw>"

# poundctl control socket
Control "/var/run/pound/poundctl.socket"
######################################################################
## listen, redirect and ... to:

ListenHTTP
    # 0.0.0.0 below should be your public IP address
    Address  0.0.0.0
    Port     80
    # This part makes sure you redirect all HTTP traffic to HTTPS
    Service
        HeadRequire "Host: whatever.co.nz"
        Redirect 301 "https://whatever.co.nz"
    End
End

# As per https://milos.jakovljevic.me/howto-lets-encrypt-ssl-with-varnish-and-pound-on-ubuntu-server/
ListenHTTPS
        HeadRemove "X-Forwarded-Proto"
        AddHeader  "X-Forwarded-Proto: https"
        Address    {{ public_ip }}
        Port       443
        Cert       "/etc/letsencrypt/live/whatever.co.nz/privkey.pem"
        # http://permalink.gmane.org/gmane.comp.web.pound.general/7489
        Disable SSLv2
        Disable SSLv3
        SSLAllowClientRenegotiation 0
        SSLHonorCipherOrder 1
        # We want to get an A on the Qualys SSL Test (https://www.ssllabs.com/ssltest)
        # https://scotthelme.co.uk/a-plus-rating-qualys-ssl-test/
        Ciphers     "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS"
        # Ensure pound doesn't rewrite location headers, as this can cause a redirect loop
        RewriteLocation 0
        Service
                BackEnd
                        Address 127.0.0.1
                        Port    6081
                End
        End
End

# Get pound to do our hostname redirects (whether they come in as HTTP or HTTPS)
Service
        HeadRequire "^Host: www.whatever.co.nz$"
        Redirect 301 "https://whatever.nz"
End

Note the following:

• We're using the ListenHTTP block to listen for http traffic on port 80, and redirect it (permanently) to port 443.
• We use the ListenHTTPS block to listen for https traffic on port 443, and direct it to Varnish on port 6081
• We disable the SSLv2 and SSLv3 protocols using Disable SSLv2 and Disable SSLv3
• We disallow client renegotiation of the SSL protocol using SSLAllowClientRenegotiation, in order to stop attackers trying to demote a secure connection to a less secure connection
• We use SSLHonorCipherOrder to ensure our ciphers are applied in the order that we specify them; this allows us to ensure that the browsers will use the most secure first, if they have support for it
• We specify our allowed ciphers using Ciphers
• We use RewriteLocation to stop Pound rewriting location headers, as this can lead to redirect loops
• We use Pound to do our hostname redirects (whether they come in as HTTP or HTTPS), redirecting www.whatever.co.nz to http://whatever.co.nz.

Note that, in order to avoid the POODLE vulnerability, we're disabling the SSLv3 protocol, and not just the SSLv3 cipher. There appears to be some confusion, with some thinking that disabling the SSLv3 cipher is enough to avoid POODLE, but that's not the case.

Our Ciphers is a list of reasonably modern ciphers, ordered from most-secure to least-secure:

ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS

We don't provide support for ciphers such as RC4, as this is considered too weak. This means people using Internet Explorer 6 won't be able to access our site, but that's not really a problem these days.

We're using Scott Helme's article on Getting an A+ rating on the Qualys SSL Test to ensure that we follow good practice regarding security. The Qualsys SSLTest is a great resource to determine how secure your site is, and using the above ciphers and SSLv2/SSLv3 migitations, we're able to acheive a solid A grade.

As security good practice evolves, you'll want to revisit the Qualsys SSLTest and ensure that you're continuing to provide a secure site.

As we're going to be using Pound to listen for traffic on port 443, we need to ensure that our webserver doesn't bind to this port.

For Apache, our /etc/apache2/ports.conf will look like:

# Varnish serves traffic to Apache on port 8080
Listen 8080

<IfModule ssl_module>
    # We'll park Apache's SSL to listen on 8443
    Listen 8443
</IfModule>

<IfModule mod_gnutls.c>
    # We'll park Apache's SSL to listen on 8443
    Listen 8443
</IfModule>

You'll want to ensure that your Apache config changes are valid before restarting Apache:

apache2ctl configtest

In order to activate Pound, we need to enable it:

# Check that our pound.cfg is valid
pound -c

# Remove the pound default startup state in /etc/default/pound
sed -i '/startup=0/startup=1/' /etc/default/pound

# Start pound 
service pound start

Pagespeed module

We've now got pound enforcing that all traffic is https, and working nicely with Varnish, which continues to cache our site content.

We've not had to make any changes to our Apache or Nginx site vhost configs, as they're still seeing traffic as http.

Google's Pagespeed Module for Apache and Nginx is a great drop-in webserver module for speeding up our site by making a number of on-the-fly optimisations. It's a topic in itself, and it's worth reading through the documentation to understand how it works and how it can benefit you.

sudo dpkg -i mod-pagespeed-*.deb
sudo apt-get -f install

This results in the Pagespeed module being installed, and since we're using Apache, we'll find the Pagespeed configuration at /etc/apache2/mods-enabled/pagespeed.conf.

We'll want to make the following changes in /etc/apache2/mods-enabled/pagespeed.conf:

• Ensure it's on: ModPagespeed on
• Respect X-Forwarded-Proto headers: ModPagespeedRespectXForwardedProto on

As Pagespeed is seeing all traffic coming from Varnish as http, it will normally serve any optimisations accordingly as http. However, this will cause Mixed content warnings in our browser, as http assets are being served on an https site.

Using ModPagespeedRespectXForwardedProto on ensures that Pagespeed checks for the X-Forwarded-Proto: https header added by Pound, and serves any associated optimisations as https.

Summary

We've glossed over a few things above, as it's presumed that you've already installed and are using Varnish and a web-server such as Apache or Nginx to serve traffic on port 80.

However, the above is hopefully easy enough to follow, and will help you to serve your site securely using Let’s Encrypt and Pound, and fast, using Varnish and Google's Pagespeed Module for Apache and Nginx.

More notes about configuring Pound and Varnish can be found at the following:

• Web Server Performance Part II: Varnish and Pound
• Let's Encrypt Certificates and Pound Load Balancer

These are notes about how we setup Dokku on EC2 with Vagrant, Docker and Dokku.

Note: an earlier version of this post mentioned that the maintainers of Dokku worked at Deis, however that's incorrect — previously Deis sponsored the project, but this has now finished, and none of the maintainers work at or have worked at Deis.

Also, it appears that a custom Buildpack is no longer needed for releasing a static site (though use of the plugin mentioned below won't break the deploy)

What is Dokku?

Dokku allows us to spin up our own Platform-as-a-Service (PaaS) and create a Heroku-style environment that's cheap, and that we can easily deploy to simply by performing a git push.

Under the covers, Dokku uses Nginx to serve sites, creating a reverse proxy Nginx config for each app that we deploy. Dokku also installs a command-line tool that allows us to configure and stop / start our applications.

We can deploy apps written using a range of technologies, including Node.js, PHP, Ruby-on-rails, and even static sites, and Dokku supports a variety of mechanisms to determine how to deploy an app, including:

• the presence of a package.json file, letting Dokku know that it's dealing with a node.js app
• Procfiles
• Docker files
• Heroku-style Buildpacks

Dokku versus Dokku-alt

Our approach described below is based on the tutorial by Alex MaCaw at ClearBit, but we'll amend this to use Dokku rather than Dokku-alt.

Dokku-alt arose because people wanted Dokku installed complete with a range of verified plugins, and because the Dokku project wasn't being maintained after the founder, Jeff Lindsay, stepped aside.

However, the situation has now reversed, with Dokku receiving active support from it's new maintainers, and Dokku-alt now a number of versions behind Dokku.

Jeff Lindsay described his experience with stepping aside from Dokku and he left the new maintainers a roadmap for future development which the maintainers have been following.

Recent Dokku features include:

• zero-downtime deployment, with Dokku waiting a configurable amount of time before routing traffic to from your old container to your newly-deployed container
• an increasing range of plugins
• the ablity to specify deploy-time checks (such as text appearing at a given URL) to ensure that
  the deploy worked correctly
• the ability to rename a deployed app

Amazon EC2 instance setup

We presume that you've already setup an AWS account, and have retrieved your AWS_ACCESS_KEY_ID and your AWS_SECRET_ACCESS_KEY.

We need to create our EC2 keypair as aws, and save the aws.pem to ~/.ssh/aws.pem.

Then, we create our EC2 Security Group as production, adding the rules to allow incoming traffic from port 22 (SSH) and port 80 (HTTP).

Next, set environment variables for our AWS_ACCESS_KEY_ID and our AWS_SECRET_ACCESS_KEY:

export AWS_ACCESS_KEY_ID=WHATEVER
export AWS_SECRET_ACCESS_KEY=WHICHEVER

These can be set in a .bash_profile or similar.

Create a new t2.micro instance — in our case we'll use the region ap-southeast-2.
Then, in the AWS dashboard, access the instance, and check the public IP address, which we'll need later to set our DNS:

52.62.179.58

Note that, depending on the apps you'll be deploying, you may need to upgrade to a larger EC2 instance.

Now, we need to determine the AMI instance to use. Use the Amazon EC2 AMI Locator
to determine the correct ami-id — scroll down to the bottom of the locator and use the dropdowns to filter the available instances.

We'll need one that has:

• region: ap-southeast-2
• version: 14.04 LTS
• instance type: hvm:ebs

Originally, when I ran the Vagrantfile below, I received the following message:

InvalidParameterValue => Value () for parameter groupId is invalid

The problem turned out to be that I was specifying an aws.ami id that was not valid for the specified aws.region — using the Amazon EC2 AMI Locator allowed me to find a suitable AMI id.

Add an entry accordingly to our /etc/hosts file — here we presume we'll be using the domain dokku.me, as we'll be using our hosts file to specify our DNS, but you can use a real (i.e. registered) domain if you'd like to make your dokku box accessiable via the public web.

52.62.179.58	dokku.me

Vagrant setup

Install the vagrant plugin for aws:

vagrant plugin install vagrant-aws

We'll retrieve the following Vagrantfile:

curl https://gist.githubusercontent.com/jcdarwin/e1991320f1c4f3d1db2f/raw/d5e2796a3c632ec63e8a503501ead7af5744d6c2/Vagrantfile > Vagrantfile

Our Vagrantfile is as follows:

Vagrant::configure('2') do |config|
	config.vm.define :dokku, autostart: false do |box|
		box.vm.box      = 'trusty'
		box.vm.box_url  = 'https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box'
		box.vm.hostname = 'dokku.me'

		box.vm.provider :aws do |aws, override|
			aws.access_key_id     = ENV['AWS_ACCESS_KEY_ID']
			aws.secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
			aws.keypair_name      = 'aws'

			# As per the Amazon EC2 AMI Locator
			aws.ami               = 'ami-4f32142c'
			aws.region            = 'ap-southeast-2'
			aws.instance_type     = 't2.micro'

			# Customize this to the id of the security group you're using
			aws.security_groups   = 'production'

			# To mount EBS volumes
			aws.block_device_mapping = [
				{
					:DeviceName => "/dev/sdb",
					:VirtualName => "ephemeral0"
				},
				{
					:DeviceName => "/dev/sdc",
					:VirtualName => "ephemeral1"
				}
			]

			override.ssh.username = 'ubuntu'

			# Customize this to your AWS keypair path
			override.ssh.private_key_path = '~/.ssh/aws.pem'
		end

		# To make sure we use EBS for our tmp files
		box.vm.provision "shell" do |s|
			s.privileged = true
			s.inline = %{
				mkdir -m 1777 /mnt/tmp
				echo 'export TMPDIR=/mnt/tmp' > /etc/profile.d/tmpdir.sh
			}
		end

		# To make sure packages are up to date
		box.vm.provision "shell" do |s|
			s.privileged = true
			s.inline = %{
				export DEBIAN_FRONTEND=noninteractive
				apt-get update
				apt-get --yes --force-yes upgrade
			}
		end

		# Install dokku as per http://dokku.viewdocs.io/dokku/getting-started/install/debian/
		box.vm.provision "shell" do |s|
			s.privileged = true
			s.inline = %{
				export DEBIAN_FRONTEND=noninteractive

				echo "install prerequisites"
				sudo apt-get update -qq > /dev/null
				sudo apt-get install -qq -y apt-transport-https

				echo "setup unattended installation"
				echo "dokku dokku/vhost_enable boolean true" | sudo debconf-set-selections
				echo "dokku dokku/hostname string dokku.me" | sudo debconf-set-selections

				echo "install docker"
				sudo apt-get install lxc wget bsdtar curl
				sudo apt-get install linux-image-extra-$(uname -r)
				sudo modprobe aufs
				sudo usermod -aG docker ubuntu
				wget -nv -O - https://get.docker.com/ | sh

				echo "install dokku"
				wget -nv -O - https://packagecloud.io/gpg.key | apt-key add -
				echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ trusty main" | sudo tee /etc/apt/sources.list.d/dokku.list
				sudo apt-get update -qq -y > /dev/null
				sudo apt-get install -qq -y dokku
				sudo dokku plugin:install-dependencies --core
                sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
			}
		end
	end
end

Note that our box_url is a blank Vagrant box to coax Vagrant into working with AWS — we can add our box manually:

vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box

Inspect the metadata:

cat ~/.vagrant.d/boxes/dummy/0/aws/metadata.json

We should see something like:

{
    "provider": "aws"
}

Create our EC2 instance using Vagrant

Start up our VM:

vagrant up dokku --provider=aws

Our Vagrantfile will create the EC2 instance, and run the provisioning script.

Once Vagrant finishes provisioning the box, you should be able to ssh into it using Vagrant:

vagrant ssh dokku

Note that if you experience any problems with the provisioning, you may need to check that Dokku and the core plugins installed correctly:

sudo apt-get install dokku
sudo dokku plugin:install-dependencies --core

While in our box, change /home/dokku/HOSTNAME and /home/dokku/VHOST from the Amazon-generated name (e.g. ip-172-31-3-31.ap-southeast-2.compute.internal) to our domain:

dokku.me

We can now exit from our ssh session.

Complete Dokku setup

We should now be able to finish the Dokku setup using Dokku's web interface at http://dokku.me

• change our hostname from the IP address to our domain: dokku.me
• choose Use virtualhost naming for apps

Setup direct ssh access

We want to be able to ssh into our box without relying on Vagrant.

First, register our normal public key with our box:

cat ~/.ssh/id_rsa.pub | vagrant ssh dokku -- sudo sshcommand acl-add dokku ${USER}

Check the ssh config for our box:

vagrant ssh-config dokku

Host dokku
  HostName ec2-52-62-179-58.ap-southeast-2.compute.amazonaws.com
  User ubuntu
  Port 22
  UserKnownHostsFile /dev/null
  StrictHostKeyChecking no
  PasswordAuthentication no
  IdentityFile /Users/jasondarwin/.ssh/aws.pem
  IdentitiesOnly yes
  LogLevel FATAL

We can use the reported HostName for direct ssh access to our box:

# This will print out the Dokku help menu
ssh dokku@ec2-52-62-179-58.ap-southeast-2.compute.amazonaws.com

# We can run commands over ssh
ssh dokku@ec2-52-62-179-58.ap-southeast-2.compute.amazonaws.com version

Deploy our app

We'll use the heroku node-js-sample app to prove that we can deploy an app to our dokku box:

# Clone the repo
git clone https://github.com/heroku/node-js-sample
cd node-js-sample

# Add our Dokku box as a remote:
git remote add dokku dokku@ec2-52-62-179-58.ap-southeast-2.compute.amazonaws.com:<our app name>

# Push our repo to our box and set off the deploy
git push dokku master

Add an entry to our hosts file for our app:

52.62.179.58	node-js-sample.dokku.me

We should now be able to access our app at http://node-js-sample.dokku.me

dokku config:set --no-restart node-js-sample DOKKU_LETSENCRYPT_EMAIL=<email>
dokku letsencrypt node-js-sample

More notes about application deployments can be found in the Dokku documentation.

Further

• Dokku has support for plugins which allow
  functionality such as database setup and access.
• Note also that web applications, like the sample nodejs app, are expected to be exposed through port 5000 unless an environment variable is specified.
• We can use Florian Heinemann's custom
  buildpack to deploy a static site.
• Note that we can run docker directly on our box, e.g.
  vagrant ssh dokku
  docker run hello-world
• Check the Dokku docs for further information

As the number of servers under our control grows, we want to be able to improve our control over package upgrades.

The problems here are two-fold:

• we want to know which packages are ready to be installed
• we want to have these packages already downloaded so we can install them when we're ready

However, we don't want to fully automate the upgrading of these packages, as:

• there may be packages that want to overwrite existing configuration, so we'll need to figure out what the best couse of action is
• there may be packages that we don't want to install

As a solution, we'll use cron-apt in conjunction with the postfix mail server to inform us of package updates that are ready to apply.

cron-apt

cron-apt allows us to automate apt-get commands. The documentation is a little sparse, though some writeups do exist here and here.

Installing cron-apt:

apt-get install cron-apt

In /etc/cron-apt/config:

# Configuration for cron-apt. For further information about the possible
# configuration settings see /usr/share/doc/cron-apt/README.gz.
MAILTO="mebooks.support@gmail.com"
#Send us an email when upgrades are readt to apply
MAILON="upgrade"

We'll want to make sure that the cron job is set up correctly in /etc/cron.d/cron-apt:

#
# Regular cron jobs for the cron-apt package
#
# Every night at 4 o'clock.
0 4 * * *   root    test -x /usr/sbin/cron-apt && /usr/sbin/cron-apt
# Every hour.
# 0 *   * * *   root    test -x /usr/sbin/cron-apt && /usr/sbin/cron-apt /etc/cron-apt/config2
# Every five minutes.
# */5 * * * *   root    test -x /usr/sbin/cron-apt && /usr/sbin/cron-apt /etc/cron-apt/config2

postfix

Possibly the most difficult part of setting up cron-apt is configuring the mail server to allow cron-apt to send out its emails about packages ready to be upgraded (presuming you don't already have a mail server set up).

In our case, we'll configure postfix to route outbound emails via Mandrill, an SMTP email relaying service.

Our postfix configuration file (as generated by our ansible role) /etc/postfix/main.cf looks like the following:

# Ansible managed: /Users/jasondarwin/workspace/ansible-digitalocean/roles/postfix/templates/main-cf.j2 modified on 2015-04-03 15:37:33 by jasondarwin on hare.lan

smtpd_banner = $myhostname ESMTP $mail_name
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

readme_directory = no

# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_use_tls=yes
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache

# Enable SASL authentication
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_use_tls = yes

# General
myhostname = host1
myorigin = $mydomain
mydestination =
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = loopback-only
relayhost = [smtp.mandrillapp.com]
inet_protocols = ipv4
sender_canonical_maps = hash:/etc/postfix/sender_canonical

Note the following:

1. We use SASL authentication to authenticate with Mandrill, so have a /etc/postfix/sasl_passwd which contains something like:

    [smtp.mandrillapp.com]    jcdarwin@gmail.com:WHATEVERYOURAPIKEYIS
   

This file is compiled as follows:

    /usr/sbin/postmap /etc/postfix/sasl_passwd

2. We specify Mandrill as our relayhost:

    relayhost = [smtp.mandrillapp.com]
   

3. We restrict the protocol used to IPV4, as Mandrill doesn't yet seem to support IPV6:

    inet_protocols = ipv4
   

4. We use sender_canonical_maps to specify the email sender address.

    sender_canonical_maps = hash:/etc/postfix/sender_canonical
   

   and this file contains something like

    root root@mebooks.co.nz
   

   This file is compiled as follows:

    /usr/sbin/postmap /etc/postfix/sender_canonical
   

   If this file didn't exist, cron-apt will send email as root, meanign our From address would look like root@localdomain, and Mandrill will refuse to relay these messages.

Testing postfix

We can use sendmail to test postfix:

sendmail mebooks.support@gmail.com
Here is the message body
CTRL+D

As no From: is specified, postfix should use the address specified for root in /etc/postfix/sender_canonical, and we should be able to see this in our mail log by running cat /var/log/mail.log:

Apr  5 02:17:32 mebooks1 postfix/qmgr[26754]: 95A76142FF1: removed
Apr  5 02:20:06 mebooks1 postfix/master[26750]: terminating on signal 15
Apr  5 02:20:07 mebooks1 postfix/master[26940]: daemon started -- version 2.11.0, configuration /etc/postfix
Apr  5 02:20:21 mebooks1 postfix/pickup[26943]: 2529F142FF1: uid=0 from=<root>
Apr  5 02:20:21 mebooks1 postfix/cleanup[26951]: 2529F142FF1: message-id=<20150405062021.2529F142FF1@host1>
Apr  5 02:20:21 mebooks1 postfix/qmgr[26944]: 2529F142FF1: from=<root@mebooks.co.nz>, size=250, nrcpt=1 (queue active)
Apr  5 02:20:21 mebooks1 postfix/smtp[26953]: 2529F142FF1: to=<mebooks.support@gmail.com>, relay=smtp.mandrillapp.com[52.74.52.47]:25, delay=6.8, delays=6.8/0.04/0.03/0.01, dsn=2.0.0, status=sent (250 2.0.0 Ok: queued as 5B9082A00BD)
Apr  5 02:20:21 mebooks1 postfix/qmgr[26944]: 2529F142FF1: removed

If nothing appears in /var/log/mail.log, have a look in /var/log/mail.err for any messages.

Wrapping up

Presuming that cron-apt and postfix are working correctly, we should receive an email before too long notifying us that there are packages to upgrade.

Upgrading these is simply a matter of running the following on the server:

apt-get dist-upgrade

One of the greatest things about using Node.js is the huge number of modules that you can pull down and use in your project — more than 120,000 according to modulecounts.com.

This often makes it trivial to create a Node application — for example, you can create a web server to start serving a site in less than a minute.

The problem

However, when you start using other people's Node modules throughout your project, you might find yourself running into the problem of using a module which has a dependency that is out of date, and the module maintainer hasn't gotten around to releasing a new version of their package.

For instance, a project I'm working on uses gulp-sass to compile our SASS into CSS. Gulp-sass is essentially a wrapper around node-sass, which in turn is a wrapper around Libsass, a blazingly fast SASS compiler written in C/C++.

LibSass has come on well over the last year or so, and has pretty good coverage of the various SASS features, and is now able to compile most of the SASS directives to CSS.

However, earlier versions of Libsass had less coverage of the SASS directives, meaning that if you were trying something even a little bit esoteric with your SASS directives, you could find yourself gazing at a screen full of errors.

And, it turns out that the most recent version of gulp-sass (1.3.3 as of writing this post) uses a version of node-sass (^2.0.1) which in turn uses an old version of Libsass which unfortunately breaks some of our SASS.

For instance, we make use of SASS maps, which appear in SASS 3.3 and allow us to create and use data-structures which in some way resemble JavaScript objects:

$icon-type: (
    email: #00824a,
    facebook: #3b5998,
    twitter: #55acee,
    googleplus: #dd4b39,
    linkedin: #007bb6,
    whatsapp: #64d448,
    reddit: #ff5700,
);

@each $icon-type, $bgcolor in $icon-type {
    a.icon--#{$icon-type},
    a.icon--before--#{$icon-type}:before {
        @include icon-svg('icons/icon-#{$icon-type}.svg');
    }
    background-color: $bgcolor;
    }
}

A one-off solution

If we use a more recent version of node-sass, which in turn uses a more recent version of libsass, the above will compile fine.

We could hack the gulp-sass package.json, changing:

"node-sass": "^0.9",

to

"node-sass": "^3.0",

and then, in the gulp-sass directory, re-install the package:

npm install

This would be fine for our individual use, but the next time that one of our team members checks out the project and runs npm install in the root directory, they'd end up with the old 0.9 version of node-sass.

The real solution

NPM shrinkwrap offers a nice solution to this problem.
It allows us to override that version of a particular dependency of a particular sub-module.

Essentially, when you run npm install, npm will first look in your root directory to see whether a npm-shrinkwrap.json file exists. If it does, it will use this first to determine package dependencies, and then falling back to the normal process of working through the package.json files.

To create an npm-shrinkwrap.json, all you need to do is

 npm shrinkwrap --dev

The --dev option is needed if the dependencies you're trying to override are in the devDependencies section of the package.json.

So, in our case, where we want to force gulp-sass to use a more-recent version of node-sass, we'd do the following:

1. Hack gulp-sass/package.json to change "node-sass": "^0.9" to "node-sass": "^3.0"

2. Run npm shrinkwrap --dev in our root directory to generate the npm-shrinkwrap.json

3. Since the only package dependency that we're worried about is node-sass for the gulp-sass package, we can remove everything from the main "dependencies" block except for the "gulp-sass" block

4. Commit our changes back to our repo, so that the next team member can checkout the repo and simply run npm install

There's much more detail to be found about shrinkwrap, both on npm and on the Node.js blog

Using ES6 modules today

With the arrival of the latest version of JavaScript, ECMAScript version 6, we have access to some very useful features, such as the ability to properly modularise our JavaScript.

Being able to use JavaScript modules is important, as it means that we can build applications (both for the browser and that run in the backend, e.g. using Node) that have a number of benefits, including:

• being more self-contained, and less likely to cause side-effects in other code
• less reliance on exposing and consuming global variables
• being easier to test, as we can use dependency injection to mock our dependencies
• better architecture of our applications
• better access to code created by other parties

Existing solutions

Because JavaScript has not had native support for modules, a number of solutions have sprung up over the years to provide this, including:

• the use of patterns such as the self-revealing module pattern, known in the wild as an IFFE
• AMD modules, as exemplified by Require.js
• CommonJS modules, as exemplified by Node

All of these solutions are in wide use, and there's plenty of code out there that has been written to use one or more of the above solutions; particularly, there's a wealth of CommonJS modules available on NPM (more than 120,000 at the time this post was written).

The Problem

Ideally, we'd start using and creating ES6 Modules today; however it's going to be some time before all browsers implement the specification, and for those of us who have to support older browser versions such as IE8, we'd really like a solution that we can use now.

Also, although we may create new code using the ES6 modules format, we may also want to take advantage of the other modules formats, particularly CommonJS, so we can build off the efforts of others.

So, in short we want a solution that will let us use all of the major existing module solutions, along with ES6 modules, in the browsers used by our audience today.

The Solution

SystemJS is a project that meets our needs, in that it acts as a polyfill for the ES6 module specification, but also lets us make use of AMD and CommonJS modules as well as our IIFEs.

SystemJS bills itself as a universal dynamic module loader, and is designed as a wrapper around the es6-module-loader, a project which is also maintained by the SystemJS creator, Guy Bedford.

The good news is that we can make use of SystemJS and the es6-module-loader to provide wide support for all major JavaScript module formats, so that we can start developing applications now that allow us to work flexibly with existing code and third party modules.

Usage

The following is one example of how you'd make use of SystemJS, but there are plenty of others ways that it can be used; in our case we only want ES6 modules, but if you want to make use of other ES6 language features now, you'll want to use Traceur or Babel (both of which SystemJS integrates with nicely). More possibilities are outlined in an article written by Guy Bedford, the SystemJS creator, as well as on the SystemJS site itself.

Building our Bundle

For our example app, we want to create a bundle of modules — that is, a single file that can be downloaded by a browser, but which contains all of our custom modules that we expect to use in our application.

To achieve this, we make use of the SystemJS builder as follows (note that the following presumes that you're familiar with using build tools such as Grunt or Gulp):

Builder = require('systemjs-builder');

gulp.task('modules', function(cb) {

    doModules('manifest', './dist/bundle.js')
    .then(function(){
        console.log('Build of modules complete');
        cb();
    })
    .catch(function(err){
        console.error(err);
    });

});

function doModules(manifest, target) {
    return new Builder({
        baseURL: 'assets/js/'
    })
    .build(manifest, target);
}

The above shows a gulp task that uses a manifest specifying the modules to include in the bundle, like follows:

require('module1');
require('module2');

Note that each of the files in the manifest is expected to be found on disk with the .js extension.

Script Loading

In our example app, we want to be able to use window.matchMedia so we can do media queries in JavaScript, however in IE8 and IE9 this means making use of the media.match polyfill.

Once matchMedia support is available, we'll load the enquire.js wrapper for matchMedia.

And, once enquire.js is available, we can then load our app.

To do all of the above, we'll use SystemJS as a script loader, pulling in the required modules in the correct order. For example, our app.js might look like the following:

;
'use strict';

(function () {

    System.config({
        baseURL: 'assets/js/dist/'
    });

    // We need to let System know it can find module1
    // in bundle.js file.
    System.bundles['bundle'] = ['module1'];

    // Test whether we need the media.match polyfill
    // for older browsers before loading enquire.
    if (!window.matchMedia) {
        // Set up our chained dependencies: 
        // module1 <= enquire.min <= media.match.min
        System['import']('media.match.min')
        .then(function(){
            return System['import']('enquire.min');
        }).then(function(m){
            // We need to force enquire 
            // onto the window object for IE8
            window.enquire = m;

            return System['import']('module1');
        });
    } else {
        // Set up our chained dependencies: 
        // module1 <= enquire.min
        System['import']('enquire.min')
        .then(function(){
            return System['import']('module1');
        });
    }

})();

Some important points to note about the above:

• Given we're supporting IE8 which uses ES3, we have to use System['import'] rather than System.import, as import is a reserved word in ES3
• SystemJS uses promises, so the resolved promise will return our loaded module, and in the .then we can load the next module in the chain
• Both the media.match polyfill and enquire.js are globals (aka IFFEs), which SystemJS can load
• As the media.match polyfill and enquire.js are not specified as belonging to a bundle, SystemJS expects to find them in the location specified by baseURL
• For IE8 we need to explicitly force the global onto the window object (hence window.enquire = m;), however this is not needed for other browsers

Importing Modules

Now that our app has been loaded, we can include modules as necessary. For instance, in module1:

;
'use strict';

import module2 from 'module2';

(function () {
    module2.init();
});

In module2.js:

;
var msgText = 'module2 loaded';

var module2  = {

    init: function() {
        function msg() {
            return msgText;
        }

        msg();
    }
};

export default module2;

The ES6 modules specification provides plenty of ways to expose functionality from a given module, though in the above case we take the approach of simply exposing the main object, meaning that our consuming module has access to all methods and variables defined on the object, though in the above example it won't have access to msgText.

Note that the only code we need code in our HTML is the app.js; all other modules are loaded via app.js.

Going Further

If you want to explore an app that demonstrates the above, check out this codepen.

Notes

As some of this technology is still relatively new, there are probably going to be a few wrinkles. In our experience, once we worked things out SystemJS worked well, but we did run across a strange bug in IE8, where at least some of the modules wouldn't load, but then did as soon as the developer tools were opened (and kept loading when the developer tools were closed again).

Also, we got tripped up for a little while with IE8 by a bug that's now been fixed (but not released as of writing this post).

Although it's improved in recent times, one of the painful aspects of web development can be testing that your site works well on mobile devices.

This particularly applies when you're developing on your local laptop with wireless network connection, and want to view the site on a mobile device, without first having to deploy to a staging server.

Ngrok

One tool that takes much of this pain away is ngrok, which is described on the site thusly:

“I want to securely expose a local web server to the internet and capture all traffic for detailed inspection and replay.”

ngrok creates a tunnel from the public internet (http://subdomain.ngrok.com) to a port on your local machine. You can give this URL to anyone to allow them to try out a web site you're developing without doing any deployment.

What this means is that, when we're webserving a site such as http://mebooks.localhost on our laptop, within a couple of minutes we can be visiting a URL such as http://mebooks.ngrok.com in a mobile browser and seeing the same site; as long as the mobile browser has a connection to the internet, it should be able to load our page.

Installation

wget https://api.equinox.io/1/Applications/ap_pJSFC5wQYkAyI0FIVwKYs9h1hW/Updates/Asset/ngrok.zip?os=darwin&arch=amd64&channel=stable

cd ~/workspace && mkdir ngrok && mv ngrok.zip ngrok && cd ngrok

Once installed, usage is as simple as:

# Serve all port 80 traffic via ngrok
./ngrok 80

Once connected, we'll see something like the following:

ngrok                        (Ctrl+C to quit)

Tunnel Status                 online
Version                       1.7/1.6
Forwarding                    http://2ebd2fe0.ngrok.com -> 127.0.0.1:80
Forwarding                    https://2ebd2fe0.ngrok.com -> 127.0.0.1:80
Web Interface                 127.0.0.1:4040
# Conn                        41
Avg Conn Time                 260.80ms


HTTP Requests
-------------

GET /assets/images/141207361_ 200 OK
GET /assets/images/144566138_ 200 OK
GET /assets/images/142808332_ 200 OK
GET /assets/images/83691787_t 200 OK

Ngrok has opened up a tunnel from our local machine to the ngrok site, and we can then visit http://2ebd2fe0.ngrok.com in our mobile device browser to see our locally-served site.

You'll probably need to add the following directive to your vhost conf (presuming you're using apache):

    # This goes, say, below 'ServerName mebooks.localhost'
    ServerAlias 2ebd2fe0.ngrok.com

Configuration

The subdomain assigned by ngrok is not guaranteed to last from one session to the next, so ideally we want to use a custom subdomain such as mebooks.ngrok.com.

We can easily specify a custom subdomain when starting ngrok:

    ./ngrok -subdomain mebooks 80

However, while we don't have to pay to be able to use a custom domain, unless we've paid a donation to ngrok these subdomains are on a first-come basis; if someone else has paid to reserve our subdomain or is currently using ngrok with the specified subdomain, then we won't be able to use it.

Once logged in, we'll find a auth token on our dashboard that allows us to identify ourselves. This auth token only needs to be specified once, as it then gets saved in ~/.ngrok.

Typically, on our local webserver we'll be serving our site using a name-based virtual host, expecting to see our site at http://mebooks.localhost, and having the following in our /etc/private/hosts file:

127.0.0.1    mebooks.localhost

To ensure that our webserver can correctly capture requests from http://mebooks.ngrok.com, we need to ensure that our vhost has the ServerAlias mebooks.ngrok.com set, and our webserver has been restarted.

Note that we can also see a nice page showing our traffic served at http://localhost:4040/http/in

More details about ngrok can be found on the ngrok site, and in this sitepoint article which covers ngrok and similar services.

Many devices these days support local storage, meaning that we can store assets in local storage on the first visit by the user to a given URL, and then on subsequent visits choose to retrieve assets from local storage rather than downloading them again.

Steve Souders has done a quick survey on the use of local storage and, combined with a cookie, this technique of retrieving assets from local storage can be useful in reducing the size and number of assets that are retrieved remotely. Currently, it's being used by Google and Bing amongst others.

An interesting statement in Steve's analysis is the following:

Another surprise from last week’s survey was that the mobile version of Google Search had 68 images in the results HTML document as data: URIs, compared to only 10 for desktop and iPad. Mobile browsers open fewer TCP connections and these connections are typically slower compared to desktop, so reducing the number of HTTP requests is important.

Another way of putting this is that, when it comes to serving pages for mobile devices, Google are prepared to take a hit in terms of the total amount of data served (as a data URI for a given resource is around 30% larger than the original resource) in return for a lower total number of TCP connections. Therefore, it seems we can take this as evidence that reducing the number of TCP connections more than makes up for increasing our overall data payload by 30%.

As an aside, when considering TCP connections, you should think about initially serving a large resource for a given domain followed by smaller resources, rather than the opposite. This reason for this was outlined in Hossein Lotfi's Velocity 2014 presentation, where he pointed out that serving a large resource initially will expand the slow start TCP window quicker than will serving a smaller resource.

As for the reasons for why local storage is of more interest on mobile devices than on desktop, Steve Souders provides the following reasons in another post:

• Mobile latencies are higher and connection speeds are lower, so clientside caching is more important on mobile.

• Mobile disk cache sizes are smaller than desktop sizes, so a better alternative is needed for mobile.
• There are still desktop browsers with significant market share that are missing many HTML5 capabilities, whereas mobile browsers have more support for HTML5.

What size is the browser cache compared to local storage?

Browser cache can be relatively small on mobile devices, and local storage can help ensure that certain resources are available longer on the mobile device than.

Browser cache sizes are really all over the map. On devices that run Android 2.2, we only have browser cache sizes of around 5MB, while on recent iOS versions, we have browser cache sizes of more than 50MB.

This means that, on many of the lower-end devices (and on higher-end devices where the user is actively visiting many sites), content may be quickly ejected from the browser cache.

Contrast this with local storage, where we typically have 5MB available per domain fully under our control, and you'll see that we've got a good chance of ensuring that site resources persist longer in local storage than they do in browser cache.

However, given the chance that a resource may still be in browser cache, it only makes sense to prefer local storage over browser cache if it is at least as fast.

Which is faster, browser cache or local storage?

Peter McLachlan at Mobify did some tests comparing local storage and browser cache across a range of mobile operating systems, and found that local storage is typically faster, sometimes more than twice as much.

It does appear that there are differences between mobile and desktop in terms of the relative speeds of local storage and browser cache and, apparently, on desktop browser cache can be faster than local storage.

Mat Scales did some useful tests to prove this is the case (and you can repeat these on your own device), showing that local storage is often typically slower in loading than the browser cache on desktop (though Safari is the notable exception, being blazingly fast and reading and writing from local storage).

The lesson

So, the lesson here seems to be that using local storage for caching is useful on mobile, but not necessarily so on desktop.

It also appears that local storage retrieval is markedly slower on multi-process browsers, as the OS is retrieving from disk rather than memory, and multi-process browsers currently do this via a blocking call to the main process).

In this case it appears wise to ensure that each retrieval returns as much information as possible; ideally, I'd guess we'd store all of the assets for a given domain in one local storage chunk. Do note that you're typically limited to 5MB of local storage per domain, and that you'll have to handle any problems that may arise if you go over this limit.

Other factors

From the above discussion, the use of local storage for caching appears attractive; however, note that a problem arises if the cookie exists, but local storage has been cleared or compromised. In this case we need to detect the problem, and this is the approach that Google use, clearing the cookie and reloading the entire page in the process, and repopulating local storage.

Note also that the browser cache has other advantages over local storage than simply speed. When we serve a page, we can specify the Last-Modified and Expires cache headers, thus allowing the browser to know when to invalidate the resources in the browser cache.

If we are instead using local storage, we have to either build this functionality into our scripts that control the loading of resources from the local storage, or alternatively restrict ourselves to only storing long-lived resources in local storage.

Peter McLachlan's post also mentioned a few other considerations:

• LocalStorage space is relatively small, 5MB on most browsers, and it can only store string data. This is effectively halved because localStorage stores strings as double-byte characters (UTF-16).

• LocalStorage reads and writes do block the rendering thread. Where possible reads/writes should be done after initial page rendering is complete. You may want to avoid operations that are likely to cause performance problems such as a very large numbers of operations (thousands or tens of thousands of reads or writes), as well as read/write operations larger than 1MB.
• Browsers should do a better job of exposing storage space used by websites taking advantage of the web storage APIs to smartphone users. Be a good neighbour and don't use localStorage recklessly, use it for key resources that are in your critical path.

Basket.js

Addy Osmani (with contributions from Sindre Sorhus, Andrée Hansson and Mat Scales) has created basket.js, which he is calling "a simple (proof-of-concept) script loader that caches scripts with localStorage".

The great thing about this project is that it looks like it gives us all the abilities that we need to manage the loading, caching, retrieval and cache invalidation of scripts into local storage.

Note that if you want to use basket.js to store non-script resources in local storage (such as CSS), you'll need to wrap them in JavaScript, which is not too difficult, though do be aware of the problems of @import statements in your CSS.

As mentioned by Andrew Wakeling:

CSS has the ability to load other resources stylesheets via @import and these calls aren't currently handled by basket.js. (A solution would probably require parsing of the CSS.)

Since the CSS is directly inserted into the DOM as a style element, relative paths are no longer relative to their source path. This is demonstrated by the difference seen in basket.html vs normal.html.

This problem is not exclusive to @import but can occur with any other resource which includes a path (e.g. url). A workaround to this problem is to always use absolute paths.

Persuing the issues for the basket.js project, it looks like they've given thought to making basket.js more fully support CSS other resources, as well as supporting other storage solutions besides local storage, though it appears progress is slow.

Going further

We can incorporate the idea of using local storage for caching resources on mobile into a wider strategy to make our pages load faster on mobile devices.

For instance, the Filament group are using an approach whereby they are shortening the critical path for loading pages.

This involves inlining the CSS needed for critical path rendering and asynchronously loading other CSS and scripts where possible to prevent blocking.

Normally, inlining CSS means that the benefits of caching are lost, as the browser doesn't know to cache the inlined CSS. The Filament group's approach here is to use a cookie:

On the first time a browser visits this site we set a cookie after asynchronously requesting certain files (such as our site’s full CSS file) to specify that now that the files have been requested, and are likely to be cached by the browser. Then, on subsequent visits to our site, our server-side code checks if that cookie is present and if so, it avoids including any inline CSS and instead just references the full CSS externally with an ordinary link element. This seems to make the page load a little more cleanly on return visits. We do the same for our fonts and icons CSS files as well.

They've taken this concept further, creating a library called enhance.js which can be used to apply these enhancements progressively, depdending on whether the browser cuts the mustard.

We can adapt the Filament Group's approach such that, instead of just retrieving resources asynchronously from remote URLs, we instead add a local storage caching layer using something like basket.js.

With the combination of the two approaches, we end up with a resource loading strategy whereby:

• CSS resources on the critical path are inlined, therefore not incurring an extra HTTP request
• scripts that we need before render start (such as HTML5shiv.js) are loaded synchronously
• we asynchronously load those scripts and CSS resources not on the critical path, storing them in local storage. Note that this includes the full CSS, i.e. including the CSS that was inlined in the page
• we set a cookie indicating that these resources are now cached in local storage
• on the first request these asynchronous resources are loaded from remote URLs
• on subsequent requests these asynchronous resources are loaded from local storage
• ideally, we'd avoid serving the inlined CSS more than once, by using server side includes (as the filament group do, with their enhance.js project)

Using the above technique (sans the local storage caching), the Filament Group managed to acheive start render times of around 300ms, as opposed to around 900ms without deferring resources to be loaded asynchronously.

Putting together inlined critical path CSS and asynchronous / lazy loading of non critical assets with the use of local storage for caching seems like a good potential solution for fast rendering on mobile devices on the initial page load, and constantly fast subsequent page reloads.

I'd be interested in hearing from anyone who's given this a go in practice.

Foundation 5 is a great CSS framework, providing lots of useful functionality that makes building modern websites easier.

However, Foundation 5 doesn't provide support for IE8, although we can make up for this with a few polyfills and some well-placed conditional comments.

Internet Explorer 8 lives on

Although the days of IE6 are pretty much past, and IE7 can be similarly disregarded as the audience share for a given site is often below 1%, IE8 is different.

IE10 can be regarded as Microsoft's first evergreen browser. Technically, their adoption of a self-updating browser means that users on Windows 7 using IE9 got upgraded to IE10, however users on Vista using IE9 and users on XP using IE8 didn't.

Thus, users on Windows XP who are determined to use Internet Explorer are left with IE8 as the only option until they either adopt a non-Microsoft browser, install a new operating system, or — more likely — move to a new computer.

Even if Windows XP is now unsupported, its share as of writing this remains at around 25% of the browser market, meaning that there will be a significant number of users visiting your site who will be using IE8 for sometime to come.

Therefore, we need to make sure that any site we make will be usable by these XP users running IE8, and this means that we need to do a little bit of work to support:

• Media queries
• HTML5 elements
• CSS3 decorations, such as rounded corners (border-radius)

Media queries aren't actually that important, as IE8 is only available on desktop systems, and most users will use their browser viewport at its maximum size. However, we do want to try and allow a consistent experience where possible across browsers and operating systems.

The solution we use is detailed below.

Polyfills

Thankfully, through the hard work of others, we can fulfil our requirements of Foundation 5 support for IE8 through the use of a number of JavaScript polyfills.

• the use of NWMatcher to provide CSS3 selectors (for IE6 and IE7)
• the use of selectivizr to provide CSS3 pseudo-classes and attribute selectors (for IE6 and IE7)
• the use of html5shiv to provide HTML5 DOM elements (for IE6–IE8)
• the use of respond.js to provide min/max-width CSS3 Media Queries (for IE6–IE8)
• The use of CSS3 PIE to provide support for CSS3 decoarations (for IE6–IE9)

We also need to ensure that anything less than IE9 uses the legacy jQuery 1.x.x, while anything from IE9 onwards can use jQuery 2.

If we wish to support REMs, then we can use the REM-unit-polyfill, though be aware of the following note:

There is currently a bug in the REM polyfill that seems to stop it working on an element if a property the element includes the !important rule, in the following screenshots I've just removed !important from .button in foundation.css, until the bug can be fixed.

Conditional comments

We wrap the polyfills in IE conditional comments, such that the specified version/s of IE will detect and load them, but other IE versions and other browsers will simply ignore them, e.g.

<!--[if IE 8]>
    <html class="lt-ie9" xml:lang="en">
<![endif]-->

In the case where we want to target a version of IE but also ensure that normal browsers pick up the polyfill, we use a little trick to reveal the contents of the conditional comments to these browsers:

<!--[if gt IE 8]>
    <!-->
    <html xmlns="http://www.w3.org/1999/xhtml">
    <!--
<![endif]-->

In the above code, the <!--> acts to close the HTML comment started on the previous line for normal browsers, while the <!-- reopens the comment. In this setting, these two lines effectively mean nothing to IE, but serve to close off the beginning and ending IE condtional comments to other browsers.

The full boilerplate for our solution is as follows:

<!DOCTYPE html>
<!--[if IE 8]>
    <html class="lt-ie9" xml:lang="en">
<![endif]-->
<!--[if gt IE 8]>
    <!-->
    <html xmlns="http://www.w3.org/1999/xhtml">
    <!--
<![endif]-->

    <head>
        <meta content="IE=Edge" http-equiv="x-ua-compatible" />
        <meta charset="utf-8" />
        <meta content="width=device-width, initial-scale=1.0" name="viewport" />
        <meta content="en" http-equiv="content-language" />

        <title>Our web site</title>

        <!--[if lt IE 8]>
            <script src="//s3.amazonaws.com/nwapi/nwmatcher/nwmatcher-1.2.5-min.js"></script>
            <script src="//html5base.googlecode.com/svn-history/r38/trunk/js/selectivizr-1.0.3b.js"></script>
        <![endif]-->

        <!-- REM-unit-polyfill is not available on a CDN, so serve locally -->
        <!--[if lt IE 9]>
            <link href="css/ie.css" rel="stylesheet" />
            <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.6.2/html5shiv.js"></script>
            <script src="//cdnjs.cloudflare.com/ajax/libs/respond.js/1.1.0/respond.min.js"></script>
            <script src="js/rem.js"></script>
        <![endif]-->
    </head>

    <body>
        <!--[if lt IE 9]>
            <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
            <script src="//cdnjs.cloudflare.com/ajax/libs/css3pie/2.0beta1/PIE_IE678.js"></script>
        <![endif]-->
        <!--[if gte IE 9]>
            <!-->
            <script src="//code.jquery.com/jquery-latest.min.js"></script>
            <script src="javascript/foundation.min.js"></script>
            <script src="javascript/foundation.topbar.js"></script>
            <script src="javascript/foundation.clearing.js"></script>
            <!--
        <![endif]-->

        <!--[if eq IE 9]>
            <script src="//cdnjs.cloudflare.com/ajax/libs/css3pie/2.0beta1/PIE_IE9.js"></script>
        <![endif]-->

        <script src="javascript/app.js"></script>
    </body>

</html>

Before and after

Before these improvements are made, viewing Foundation 5 in IE8 looks like this:

Once we've made the above improvements, we get a much more pleasing experience:

The inspiration for the above was provided by Jame's Cocker's post on the Foundation Forum.

When deploying applications into production, the challenge then becomes keeping on top of any errors that may be thrown during day-to-day operation.

In the bad old days, you might put in some error trapping to log to a disk file (and then remember to check this file regularly) or send yourself an email.

Thankfully, we've largely outgrown this approach, and these days there's a number of services which provide online error tracking, such as Raygun; Paul Irish has a list of similar services.

If you want to install an error tracking service on your own hardware, then Sentry is a pretty good choice, being a Python application that is available in both SAAS and OpenSource versions.

Sentry is the product of David Cramer (an engineer at Dropbox) and Chris Jennings (a designer at Github) and was started while they were at Disqus. In an interview on LeanStack they mention that they consider themselves fortunate enough to have good day jobs such that Sentry can thrive as a OpenSource project:

Yeah, so we open-sourced it because we wanted people to use it. Not because we wanted to create this thing and make money off of it. And it's still the same thing today. A lot of people don't pay for Sentry. I would say 90% of people just host it themselves...But those 90% of people who aren't paying us are directly making Sentry better for the people who are paying us so it works.

The Sentry dashboard, showing a number of different errors

Sentry provides an HTTP API to allow your application to capture and send it information about errors, typically achieved using the officially sanctioned Raven libraries, and Raven provides error collectors for languages such as PHP, Python, Ruby, Node, and client-side JavaScript (a full list can be found in the Sentry docs).

Installation

Although I initially tried to install Sentry using pip and easy_install, I ran into some problems with reported errors not making it onto the dashboard, so ended up installing from source.

The following notes were developed through deploying Sentry on an Ubuntu VPS, but should be broadly similar for any Linux-like environment.

As I'm a fan of Ansible, I include some of the steps below as Ansible scripts; if you're not conversant with Ansible, don't worry as you should be able to figure out the equivalent shell commands from the scripts without too much problem.

Our main control file looks like:

---
# roles/sentry/main.yml
# This Playbook deploys sentry!

# http://cavaencoreparlerdebits.fr/blog/2014/04/install-sentry-to-catch-and-manage-your-errors-softwares
# http://blog.jesse-obrien.ca/post/add-beautiful-and-effective-exception-handling-to-laravel-with-sentry

- hosts: droplets
  user: root
  vars_files:
    - vars/main.yml
  handlers:
   - include: handlers/main.yml

  tasks:
  - include: tasks/sentry_packages.yml
  - include: tasks/sentry_user.yml
  - include: tasks/sentry_env.yml
  - include: tasks/sentry_mysql.yml
  - include: tasks/sentry_install.yml
  - include: tasks/sentry_nginx.yml

We also have some variables that are referenced by the scripts:

# roles/sentry/vars/main.yml
sentry:
  user: sentry
  password: whatever
  hostname: whatever
  listen_addr: 127.0.0.1
  listen_port: 9000
  db: sentry
  db_username: sentry
  db_password: whatever
  url: http://whatever
  env: sentry-env
  email_host: whatever
  email_host_user: whoever@wherever
  email_host_password: whatever
  email_port: whichever
  email_use_tls: True

Install the requisite packages

# roles/sentry/tasks/sentry_packages.yml
# ===============================================================
# packages: install the necessary packages
# ===============================================================

# Add the officially-sanctioned nodejs ppa
- name: add-apt-repository ppa:chris-lea/node.js
  action: template 
    src=files/chris-lea-node_js-wheezy.list
    dest=/etc/apt/sources.list.d/chris-lea-node_js-wheezy.list
    owner=root group=root mode=0644
  tags: packages

- name: update apt cache
  apt: update_cache=yes cache_valid_time=3600
  sudo: yes
  tags: packages

- name: install packages
  apt: pkg={{ item }} state=latest
  sudo: yes
  with_items:
    - nginx
    - python-software-properties
    - python-pip
    - python-dev
    - build-essential
  tags: packages

- name: force install packages (because we're using a ppa)
  apt: pkg={{ item }} state=latest force=yes
  sudo: yes
  with_items:
    - nodejs
  tags: packages

- name: install python packages using pip
  pip: name={{ item }}
  with_items:
    - virtualenv
    - virtualenvwrapper
    - python-memcached
  tags: packages

The above Ansible script can be run using the --tags option:

# Install the packages
ansible-playbook -l droplets roles/sentry/main.yml -i hosts --tags=packages

Here we install a number of python-based packages, as well as Node from the officially-sanctioned PPA. Note that we had to change wheezy to lucid in the PPA definition as it appears the PPA is not yet supporting wheezy:

# roles/sentry/files/chris-lea-node_js-wheezy.list
deb http://ppa.launchpad.net/chris-lea/node.js/ubuntu lucid main
deb-src http://ppa.launchpad.net/chris-lea/node.js/ubuntu lucid main

Create our user

We need to create a user to run Sentry under:

# roles/sentry/tasks/sentry_user.yml
# ===============================================================
# user: create the sentry user
# ===============================================================

- name: Create sentry user
  user: name={{ sentry.user }}
        password={{ sentry.password }}
        createhome=yes
        shell=/bin/bash
        state=present
  tags: user

- name: Create the SSH directory
  file: state=directory path=/home/{{ sentry.user }}/.ssh

- name: Add authorized key for the user
  authorized_key: user={{ sentry.user }} key='{{ item }}'
  with_file:
    - ~/.ssh/id_rsa.pub

- name: Backup sudoers file
  command: cp -f /etc/sudoers /etc/sudoers.bak
  tags: user

- name: Add sentry user to sudoers
  action: lineinfile
        dest=/etc/sudoers
        regexp='{{ sentry.user }} ALL'
        line='{{ sentry.user }} ALL=(ALL) ALL'
        state=present
  tags: user

- name: Check sudoers file syntax
  shell: visudo -q -c -f /etc/sudoers
  register: result
  ignore_errors: True
  tags: user

- name: Rolling back - restoring backed-up sudoers file
  action: cp -f /etc/sudoers.bak /etc/sudoers
  when: result|failed
  tags: user

The above Ansible script can be run using the --tags option:

# Create the sentry user and home directory
ansible-playbook -l droplets roles/sentry/main.yml -i hosts --tags=user

Create our virtual environment

We want to use a python virtual environment to isolate our Sentry python dependencies, and ensure that we can run different versions of python for other applications.

We also install our Sentry conf — normally this is installed using sentry init once Sentry has been installed, however we want to template our Sentry conf for use with Ansible and customise a few of the directives, such as using MySQL rather than the default SQLite. More details about the Sentry configuration can be found on the Sentry site.

The important part of the sentry.conf is the SENTRY_URL_PREFIX, which should be set to your domain:

SENTRY_URL_PREFIX = 'example.com'  # No trailing slash!

# ===============================================================
# env: initialise the sentry environment
# ===============================================================

- name: include virtualenvwrapper in our shell
  lineinfile: >
    destfile=/home/{{ sentry.user }}/.bashrc
    regexp="^source /usr/local/bin/virtualenvwrapper\.sh"
    line="source $HOME/.virtualenvs/{{ sentry.env}}/bin/activate"
    state=present
  remote_user: "{{ sentry.user }}"
  tags: env

- name: create our virtual environment
  shell: >
    executable=/bin/bash
    source `which virtualenvwrapper.sh` && mkvirtualenv {{ sentry.env }}
  register: create_virtualenv
  remote_user: "{{ sentry.user }}"
  environment:
    HOME: /home/{{ sentry.user }}
  tags: env

- debug: var=create_virtualenv.stdout_lines
  tags: env

- name: install the sentry conf
  template: >
    src=templates/sentry.conf.py.j2
    dest=~/sentry.conf.py
    owner="{{ sentry.user }}" group="{{ sentry.user }}" mode=0644
  remote_user: "{{ sentry.user }}"
  environment:
    HOME: /home/{{ sentry.user }}
  tags: env

- name: install python packages inside the virtual env using pip
  pip: name={{ item }} virtualenv={{ sentry.env }}
  with_items:
    - MySQL-python
  tags: env

The above Ansible script can be run using the --tags option:

# Create our virtual environment
ansible-playbook -l droplets roles/sentry/main.yml -i hosts --tags=env

Importantly, the above script will create our virtual environment (in /home/sentry/.virtualenvs/sentry-env) and will add the following line to our .bashrc, which ensures that the virtual environment is loaded when we run Sentry under our sentry user:

source $HOME/.virtualenvs/{{ sentry.env}}/bin/activate

Installing Sentry

Now that we've done the hard work of setting up the environment, the actual install of Sentry is quite easy:

# Clone the sentry project
cd /home/sentry
git clone git://github.com/getsentry/sentry.git sentry

# Make sentry.
# This will be created in /home/sentry/.virtualenvs/sentry-env
cd /home/sentry/sentry/
make

# Create our db and user
ansible-playbook -l droplets roles/sentry/main.yml -i hosts --tags=mysql

# Run the database migrations
sentry --config=/home/sentry/sentry.conf.py upgrade

Here we're using the following Ansible script to setup our MySQL environment as we'd like it, prior to running Sentry's database migrations:

# roles/sentry/tasks/sentry_mysql.yml
#     ===============================================================
# mysql: install sentry database
# ===============================================================

- name: install mysql dependencies
  action: apt pkg={{item}} state=installed
  with_items:
    - mysql-server 
    - mysql-client 
    - libmysqlclient-dev
    - python-mysqldb
  tags: mysql


# 'localhost' needs to be the last item for idempotency, see
# http://ansible.cc/docs/modules.html#mysql-user
- name: determine whether .my.cnf exists
  shell: ls -la ~/.my.cnf
  ignore_errors: True
  register: ls_my_cnf
  tags: mysql

- name: copy .my.cnf file with empty root password credentials
  template: src=.my.cnf.orig.j2 dest=/root/.my.cnf owner=root mode=0600
  when: ls_my_cnf.stdout.find("cannot access") == 1
  tags: mysql

- name: update mysql root password for all root accounts
  mysql_user: name={{ mysql.user }} host={{ item }} password={{ mysql.password }} priv=*.*:ALL,GRANT
  with_items:
    - 127.0.0.1
    - localhost
  tags: mysql

- name: update mysql sentry password for all sentry accounts
  mysql_user: name={{ sentry.db_username }} host={{ item }} password={{ sentry.db_password }} priv={{ sentry.db }}.*:ALL,GRANT
  with_items:
    - localhost
  tags: mysql

- name: copy .my.cnf file with root password credentials
  template: src=.my.cnf.j2 dest=/root/.my.cnf owner=root mode=0600
  tags: mysql

- name: ensure database sentry is present
  mysql_db: name={{ sentry.db }}
        collation=utf8_unicode_ci
        encoding=utf8
        state=present
  tags: mysql

- name: ensure database user for sentry is present and has necessary privileges
  mysql_user: name={{ sentry.db_username }}
        host={{ item }}
        password={{ sentry.db_password }}
        priv={{ sentry.db }}.*:ALL,GRANT
        state=present
  with_items:
    - localhost
  tags: mysql

We then need to create the administrator account:

sentry --config=/home/sentry/sentry.conf.py createsuperuser

And following this, run the repair

sentry --config=/homee/sentry/sentry.conf.py repair --owner=<superusername>

Nginx

We want to reverse-proxy Sentry to the outside world using Nginx:

server {
    listen 80;
   server_name {{ sentry.hostname }};

    access_log /var/log/nginx/{{ sentry.hostname }}.access.log;
    error_log /var/log/nginx/{{ sentry.hostname }}.error.log;

    # keepalive + raven.js is a disaster
    keepalive_timeout 0;

    location / {
        # proxy_pass http://127.0.0.1:9000;
        proxy_pass http://{{ sentry.listen_addr }}:{{ sentry.listen_port }};
        proxy_redirect off;

        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;

        error_page 500 502 503 504 /500.html;
    }
}

The above Ansible script can be run using the --tags option:

# Create our virtual environment
ansible-playbook -l droplets roles/sentry/main.yml -i hosts --tags=env

nginx reload

Supervisor

We'll use Supervisor to look after our Sentry process, and this means creating the following as /etc/supervisor/conf.d/sentry.conf:

[program:sentry-web]
directory=/home/{{ sentry.user }}/.virtualenvs/{{ sentry.env }}/
command=/home/{{ sentry.user }}/.virtualenvs/{{ sentry.env }}/bin/sentry --config=/home/{{ sentry.user }}/sentry.conf.py start
autostart=true
autorestart=true
redirect_stderr=true

[program:sentry-worker]
directory=/home/{{ sentry.user }}/.virtualenvs/{{ sentry.env }}/
command=/home/{{ sentry.user }}/.virtualenvs/{{ sentry.env }}/bin/sentry celery worker -B
autostart=true
autorestart=true
redirect_stderr=true

We need to tell Supervisor about the new configuration file:

sudo supervisorctl restart sentry-web

Now that Sentry's installed, you should be able to visit the Dashboard and login using the superuser credentials you set earlier.

You'll want to obtain the DSN, which can be found at: http://<your domain>/sentry-internal/sentry/keys/

Capturing errors to Sentry

Having Sentry installed is nice, but it's a little bit redundant until we start sending it errors.

The Raven PHP client has some good notes about creating a simple application to post to Sentry.

We'll create a simple PHP script to generate a few errors, and capture them to our Sentry installation using Raven.

<?php 
// sentry-test.php

// Use Composer's autoloader
require('vendor/autoload.php');
Raven_Autoloader::register();
 
$client = new Raven_Client(
    // Importantly, we define below the DSN.
    // This is made up of a <public key> and a <secret>, which can be found at
    // http://<your domain>/sentry-internal/sentry/keys/
    // while <your domain> will be the value defined for SENTRY_URL_PREFIX in sentry.conf.
    'http://<public key>:<secret>@<your domain>/1'
    , array(
        'tags' => array(
            'php_version' => phpversion()
    ),
));
 
echo "Capture a debug message\n";
$client->captureMessage('Test debug message %s', array('foo'), array(
    'level' => Raven_Client::DEBUG,
    'extra' => array('foo' => 'bar')
));

echo "Capture an info message\n";
$client->captureMessage('Test info message %s', array('foo'), array(
    'level' => Raven_Client::INFO,
    'extra' => array('foo' => 'bar')
));

echo "Capture a warning message and obtain the Sentry reference\n";
$event_id = $client->getIdent($client->captureMessage('Test warning message %s', array('foo'), array(
    'level' => Raven_Client::WARNING,
    'extra' => array('foo' => 'bar')
)));
echo "Your reference ID is " . $event_id . "\n";
 
try {
    echo "Capture an exception and obtain the Sentry reference\n";
    throw new Exception('Uh oh!');
}
catch (Exception $e) {
    $event_id = $client->getIdent($client->captureException($e));
    echo "Your reference ID is " . $event_id . "\n";
}
 
// optionally install a default error handler to catch all exceptions
$error_handler = new Raven_ErrorHandler($client);
 
// Register error handler callbacks
set_error_handler(array($error_handler, 'handleError'));
set_exception_handler(array($error_handler, 'handleException'));

We'll also need to install the Raven PHP library, and as we also want to make use of Composer's autoloader, we'll use Composer:

{
    "name": "you/sentry-test",
    "description": "Test an newly-installed sentry installation",
    "require": {
        "raven/raven": "dev-master"
    },
    "license": "whatever",
    "authors": [
        {
            "name": "your name",
            "email": "your email"
        }
    ],
    "minimum-stability": "dev"
}

To install the composer dependencies:

# Install composer if necessary
curl -sS https://getcomposer.org/installer | php

# Install the dependencies for this project
composer install

Running the following should generate some messages and errors, which should appear in quick fashion on your Sentry dashboard:

php sentry-test.php