WordPress Meetup in Londonderry

I’ll be speaking next month at the WordPress Meetup about the using Docker to host a development WP server on your laptop. Here’s the writeup:

Docker for WordPress

Docker enables developers to easily pack, ship, and run any application (including WordPress) as a lightweight, self-sufficient container which can run virtually anywhere.

For WordPress users, this means it’s easy to set up a lightweight development WP server on your laptop/desktop. You can make and test changes before migrating it to your client’s site. Best of all, if you screw things up, you can simply discard the container’s files and start afresh in a couple minutes. And because it’s running on your local computer, no need to worry about hosting, configuring servers, etc.

Rich will show how to install the Docker application on a laptop, then install and start a WordPress Docker container. The result is the familiar new WP install that you can customize to your heart’s (or client’s) content.

The WordPress Meetup is open to all on Tuesday, 8 May. Sign up at https://www.meetup.com/WordPressDevNH/events/249032144/

How to Write Wiki Pages So People Will Read Them

So you’ve just learned something cool on a new subject, and you want to let the world know about your discovery. You go to the project’s wiki, and jot it all down. But how can you help people read what you’ve written?

When I look at pages on a wiki, I use three criteria to determine whether I want to spend the time to read a page. If I’m convinced that the page has the info I’m seeking, I’ll work hard to understand it. But if I can’t tell whether it’s any good, it’s just faster to post a query to the forum. Here are the questions I ask:

  1. Is this page for me? Does it apply to my situation?

    There are a lot of cues to whether a page “is for me”. Obviously the title/heading of the page is important. But when I’m seeking information, I’m not usually an expert in the subject. I need help to understand the topic, and I look for a description that tells what the page is about. I also look for cues to see if it’s up to date. Finally, I love a page that has an introductory section that talks about the kinds of info that I’ll find on the page.

  2. Does the author know more than I do?

    A number of factors influence this judgement. As you’re aware, there’s a huge range of knowledge level of wiki page authors – from expert to the newcomer who’s excited to document his first discovery. As I scan through a page, I’m looking for facts that confirm what I already know (proving the author has some skill), and then things that I don’t (showing they know more.) Finally, it helps to know that the author is aware of the conventions of the wiki – does it look like other wiki pages? If so, I get some comfort that the author is aware of the way other wiki pages work/look.

  3. Can I figure out what to do?

    My final question about whether a page is useful is whether I can use the information. If it’s a tutorial/howto, I want the steps clearly stated – “step 1, step 2, step 3, then you’re done” If it’s a reference page, is the information organized in a comprehensible fashion? Is it really long? Can I pick out what’s important from incidental info?

The challenge I put to every author is to organize the information in a way that presents the most frequently-sought info first, then figure out what to do with the rest. You might move sections around, or move some information onto its own separate page, coalesce it into an existing/similar wiki pages, or even create forum articles (instead of a wiki page) if the subject is rapidly evolving.

DRY Documentation…

DRY – Don’t Repeat Yourself – is it relevant for documentation? I recently saw this comment on a forum…

I’m not sure how useful it is to remove duplication [from the documentation pages]. It’s not code…

IMHO, duplication in documentation is a couple orders of magnitude worse than duplication in code (and duplication in code is bad) because bad documentation has the power to waste more people’s time.

With code, a single (knowledgeable) developer must take the time to read through the duplicated code to look for subtle differences.

But with documentation, every reader – perhaps hundreds of far less knowledgeable people – must mentally diff the two pages looking for common threads/important items/gotcha’s to try to be sure that they will succeed.

For example, these two documentation pages describe [some procedure…], and each describes an substantially different procedure. I often find the differing explanations so difficult to reconcile that I simply give up (or maybe resolve to come back some day), rather than bricking my router/leaving it inoperable/etc.

So, for common tasks, I believe it is always better to have a single well-curated page that correctly and concisely describes the procedure, instead of having multiple people write their own incomplete, or marginally correct procedure.

Getting Started with React!

I’ve been playing with the spate of new Javascript technologies, and ran into a problem. As a beginner in this new ecosystem, I chose one of those big “starter kits” because I wanted to avoid the hassle of configuring all the tooling (see Javascript fatigue).

But there was so much boilerplate that it was hard to see what was happening, and hard to steer away from its preconceptions to customize it for my needs. Here’s what I wish someone had told me a few weeks ago:

  1. I found create-react-app – a Facebook-supported tool for creating a basic React application. Although it’s a simple app, create-react-app brings along all the modern Webpack facilities without farbling around with configuration. You can focus on the code that’s important. See: Create Apps with No Configuration and the Guide for create-react-app

  2. In addition to the static pages, my application also needed to get data from a separate (“api”) server. There’s a great post from fullstackreact.com that shows how to create and integrate a server (to handle the API) alongside the Webpack-provided development server that handles the GUI. See: How to get “create-react-app” to work with your API

  3. I found a helpful tutorial from Christophe Coenraets that shows how to integrate Socket.io so that React components can listen for updates from a socket.io connection. See: Real Time Trader Desktop with React, Node.js, and Socket.io

  4. Finally (and too late to save me lots of work…), I found Dan Abramov’s React Makes You Sad flow chart. Regrettably, I took most of the “wrong” turns he depicts. But I am now happily working in a vastly simpler environment using the tools above.

TL;DR Dan Abramov is right (he’s always right 🙂 ) When you’re just getting started with React development, start simple. Follow the steps on the React Makes You Sad page. Maybe use create-react-app for your first prototype. And only add new technologies/packages/etc. when you understand why you need them.

Bufferbloat on Packet Pushers

Back in October, I had the pleasure of chatting with Ethan Banks on the Packet Pushers podcast.

In it, we talked about the definition of bufferbloat, and how it harms the performance of VoIP, gaming, and general internet use. (It’s the reason our children say, “The internet is slow today, Daddy.”) I also described how the CoDel algorithm, and its fq_codel implementation in Linux makes the problem go away.

The most fun was the CoDel demonstration, which occurs near the end of the podcast. The podcast was recorded over Skype. When I turned on many netperf upload and download sessions to fully load my 7mbps/768kbps DSL link, the quality degraded without fq_codel. But it bounced right back when I re-enabled it.

Listen to the podcast – PQ Show 57 – Improve Your Home Internet Performance Using CoDel

Debugging Webpack app’s with WebStorm 2016.1

[Update Sep 2016: I just posted a support request with Webstorm asking for an updated tutorial on this subject. It’s Ticket WEB-23528]

It recently became possible to debug both server-side and client webpack applications with JetBrains’ WebStorm. The instructions came from a ticket WEB-20781, but they’re not in one place, so I figured I would write them out.

My application was built using react-starter-kit 0.5.1 – which is the current build as of mid-March 2016. These steps worked for me with WebStorm 2016.1 on OSX 10.10.5.

Update: WebStorm 2016.1 can automatically create the React Starter Kit 0.5.1 when you choose New Project…

Debugging Server-side Code

  1. Clone the react-starter-kit repo, then npm install as usual.

  2. You’ll need to tell webpack to generate source maps when debugging. Look in webpack.config.js for a line containing devtool (near line 204), and change it to:
    devtool: DEBUG ? 'source-map' : false,

  3. You also have to remove references to “hash” from the output filenames. Look in the same file near line 156 for a line like this, and change it to:
    filename: DEBUG ? '[name].js' : '[name].[hash].js',

  4. Create a new Run/Debug Configuration. Choose Run -> Edit Configuration, then add a “Node.js” item. Give the configuration a name, and if it isn’t already there, enter the path to your Node.js binary.

  5. Enter the path to your react-starter-kit project folder in “Working Directory”.

  6. For the “Javascript file:” enter the server-side code in the “build” directory. For react-starter-kit, it’s “build/server.js”

  7. Save the configuration by clicking OK.

  8. Build all the files by double-clicking “build” in the npm panel, or typing npm build in the command line.

  9. Set some breakpoints in the server-side code.

  10. In WebStorm, choose Debug (Ctl-D) for the configuration you created in 4. above. WebStorm starts debugging your server-side code, and should stop at breakpoints as expected.

Debugging Client-side Code

I haven’t needed to try these steps yet, but I understand this is the procedure:

  1. Follow Steps 1-3 above.

  2. Create a new Run/Debug Configuration. Choose Run -> Edit Configuration, then add a “JavaScript Debug” item. Give the configuration a name.

  3. Enter the URL to your app in the “URL:” field. For react-starter-kit, it’s http://localhost:3000

  4. Save the configuration by clicking OK.

  5. Start the application by clicking start in the npm panel, or typing npm start from the command line.

  6. Set some breakpoints in the client-side code. WebStorm should be debugging your client-side code, and should stop at breakpoints as expected.

Do you have comments/suggestions/improvements to these procedures? Leave a comment…

Hacking with React – A great book

I wanted to learn React, and I have been wandering around the Internet, looking at a zillion “how to get started” tutorials. I’m not sure what made me stop and look hard at Hacking with React, but I’m so glad I did.

Hacking with React provides a great combination:

  • a progression of straightforward, short lessons toward a working example program,
  • an interesting application (not another To-Do app, thank FSM!),
  • a Howto for setting up some of the confusing Node.js tooling (webpack, ESLint),
  • introduction to testing with Jest,
  • advice about best Node/Javascript/coding practices,
  • a decent understanding of how all these tools work together, and of course,
  • a great walkthrough of the concepts behind React.

At the end of the forty-some tasks (which take a while to complete if you actually do the work of understanding each lesson) you have a working React application, and a pretty good understanding of the basics of starting and building a React/Node application

The book is free to read, but you should buy this book to reward this excellent work. For $10, you’ll learn a lot.

Cmder for Windows – Alternative to PuTTY

For some unfathomable (to me) reason, Windows doesn’t seem to ship with a SSH program out of the box. I’ve used the venerable Putty in the past, but it makes you do a lot of work for a simple SSH session.

I recently ran across an open-source replacement called Cmder for Windows. Based on ConEmu, it bills itself as a “portable console emulator for Windows”. I find it a great replacement for PuTTY, Console, and Powershell. Cmder has a huge number of benefits:

  1. Cmder allows you to create a ssh session simply by typing ssh user@host — I’m immediately in love
  2. Cmder is easy on the eyes, with attractive fonts, default Monokai color scheme, and resizable windows
  3. If you get the “full” version, you get bash emulation with a Unix-y environment, including ls, grep, and even git
  4. Cmder will run off a USB stick
  5. … and it’s free (MIT License)

screen shot of Cmder window

Check it out at http://cmder.net

Bufferbloat and the Ski Shop

Bufferbloat is undesirable latency caused by a router buffering too much data. It makes your kids say, “The Internet is slow today, Daddy”. It’s caused by routers and other network equipment buffering (accepting for delivery) more data than can be delivered in a timely way. Bufferbloat causes much of the poor performance and human pain experienced using today’s Internet.

Update: I found a way better analogy for explaining Bufferbloat. I write about it in my post Best Bufferbloat Analogy – Ever

First a story…

Imagine a ski shop with one employee. That employee handles everything: small purchases, renting skis, installing new bindings, making repairs, etc. He also handles customers in first-come, first-served order, and accepts all the jobs, even if there’s already a big backlog. Imagine, too, that he never stops working with a customer until their purchase is complete. He never goes out of order, never pauses a job in the middle, not even to sell a Chapstick.

That’s dumb, you say. No store would do that. Their customers – if they had any left – would get really terrible service, and would never know when they’re going to be served. And you would be right.

The Ski-Shop Router

Unfortunately, a lot of network routers (both home and commercial) work just like that fictitious ski shop. And they give terrible service. These routers have a single first-in, first-out queue for packets. All traffic is queued, regardless of whether it’s a big or small packet, whether there has been a lot of traffic from a particular source, or whether things are getting backed up.

Since the router has no global knowledge of what’s happening, it cannot inform a big sender to slow down, or throttle a particular stream of traffic by discarding some data (in the ski shop analogy, sending away a customer who has another long repair job). The dumb router simply accepts the data, buffers it up, and expects to send it sooner or later. To make matters worse, in networking (but not in ski shops), if delays get long enough, computers can resend the data, thinking that the original packet must have been lost. These retransmissions further increase bloat and delay, because there are now two copies of the same data buffered up, waiting to be sent…

This is the genesis of the name “bufferbloat” – the router’s memory gets bloated with buffers of packets. When the router doggedly determines to send that data, it blocks newer sessions from even starting, and the entire network gets slow.

What’s the solution?

The members of the CeroWrt team have been working for the last three years to solve the problem of bufferbloat. We’ve largely succeeded: the CeroWrt firmware works really well. CeroWrt users no longer see problems with “the internet being slow” even when uploading and downloading files, watching videos, etc. We have pushed those changes into the Linux Kernel, and also into OpenWrt mainline, and now its Barrier Breaker release contains the Smart Queue Management (SQM) fixes.

SQM introduces a new queueing discipline called fq_codel (see http://tools.ietf.org/html/draft-nichols-tsvwg-codel-02 and http://tools.ietf.org/html/draft-hoeiland-joergensen-aqm-fq-codel-00 for details) that can detect which flows (streams of data between two endpoints) are using more than their share of the bottleneck link (usually, the connection to the ISP).

SQM divides the traffic into multiple queues, one per flow, and sends packets from each queue in round-robin order. (The algorithm is somewhat more involved, so read the full description for details.) fq_codel also measures the time that each packet has been queued (its sojourn time). If packets for a flow have been in the queue for “too long”, then fq_codel either marks them for ECN (Explicit Congestion Notification), or discards a certain percentage of them, preventing the flow from using more than its fair share of bandwidth on the bottleneck.

Wait a minute – discarding packets? Doesn’t that make things worse?

It does slow the rate for the affected flow, but that is exactly what should happen. If a sender has sent so many packets that they’re building up in the router’s memory, then the router must offer back pressure for that flow by dropping/marking some of its packets.

In the meantime, all the other flows (in their own queues) have their packets sent promptly, since they’re not building up and their sojourn time stays low. This automatically keeps everything responsive: short packets, and those from low-volume flows automatically get sent first. The big senders, whose packets are dropped/marked, will re-send the data, but at a slower rate, bringing the entire system back into balance.

What about Quality of Service (QoS)? Doesn’t that help?

Yes, it helps a bit. If you configure your router for QoS, the router will use that information to prioritize certain packets. Good QoS settings can help certain traffic types by sending it first, ahead of the bulk traffic that’s buffered up. But there are several problems with QoS:

  • It doesn’t solve the problem of overbuffering. The QoS rules allow certain packets to go to the head of the queue. But the buffers from large flows are still there, and will have to be sent at some point. And those buffers will stand in the way of any newly arrived traffic that hasn’t been prioritized.
  • As a corollary, there’s no throttling of the big senders: they don’t get early feedback that they are using more than their fair share of the capacity. If the queue/delay gets large enough, the sender could even retransmit the data, making the overall situation worse.
  • It’s annoying to configure QoS. You have to understand how to configure the router and manually make the changes. This is something that only a network geek could come to enjoy. It’s also a maintenance hassle: if you hear about a new application, it may not work well until you adjust the QoS rules to take it into account.
  • Finally, QoS doesn’t help for the download direction. It can improve traffic being sent from your local (home) network toward the Internet. But if the equipment at the far end at your DSL or cable provider is bloated (and very often it is), then QoS in your router won’t make things any better.

The fq_codel and other algorithms in CeroWrt handle all this automatically. The only configuration parameters are what kind of link you have (DSL, Cable, etc.) and the speeds of those links. You don’t have to adjust QoS settings or make other adjustments.

Is my network affected by Bufferbloat?

Quite possibly – here’s one symptom: If the network works well when no one else is using it (early morning, or late at night after everyone else is asleep), but gets slow when others are on the net, then you are suffering from Bufferbloat. Another symptom is if your voice, video chat, or gaming degrade when others are using the network.

Here’s a more scientific test. The DSLReports Speed Test http://dslreports.com/speedtest runs a latency measurement during the download and upload speed tests. (Most speed test sites only measure a few pings when the line is idle.) If the latency gets high on this test, then your router is probably bloated. You can also check out the Quick Test for Bufferbloat on the CeroWrt site for additional information.

What can I do about this?

Three years of network research have paid off: the networks work great at our houses. Our algorithms have been adopted and implemented in the Linux kernel, other operating systems, and an increasing set of commercial network equipment. Our changes have been pushed in to the OpenWRT project. We are making the code available at no charge, and are encouraging all vendors to embrace it.

Regrettably, nearly every piece of equipment with a network connection – home router, ISP headend and DSLAM, phone, personal computer, laptop, tablet, even big commercial routers and switches – needs to have some form of SQM installed. We now have the technology, and it’s simple, but it needs to be deployed.

TL;DR – What you can do about Bufferbloat at your home

  • Consider installing the stable OpenWrt Barrier Breaker firmware on your router. The luci-app-sqm and sqm-scripts packages include the enhancements that we’ve tested and then pushed into the OpenWrt mainline source code. Use the Supported Devices page to find your router, then read the SQM/fq_codel HOWTO. If you don’t want to do all that…
  • Call your router vendor’s support line. With the information from the DSLReports Speed Test in hand, you can mention that the ping times get really high when up/downloading files, and that it really hurts your network performance. Ask if they’re working on the problem, and when they’re going to release a firmware update that solves it. Leave a comment here with their response – I’d love to hear.

An earlier draft of this note appeared in the Bloat and Codel mailing lists. See https://lists.bufferbloat.net/pipermail/codel/2014-February/000802.html Latest update 3May2015

New CeroWrt Router scripts

I posted a set of scripts that people can use to test, configure and debug their CeroWrt router installations. CeroWrt router firmware is a test bed for learning about and eliminating bufferbloat.

The scripts are available on Github at https://github.com/richb-hanover/CeroWrtScripts. They include:

  • betterspeedtest.sh – a script that emulates the famous (but limited) speedtest.net. This script is better because it measures ping latency during the download and upload, and tells you how bad (or not) the bloat is in your network/router.

  • netperfrunner.sh – a script that emulates the RRUL test suite. It runs on the CeroWrt router (or your laptop) to measure the latency under heavy load.

  • config-cerowrt.sh and tunnelbroker.sh – two scripts for configuring a CeroWrt router to a consistent state after flashing new firmware.

  • cerostats.sh – a script that collects a number of configuration and operational stats that is useful for debugging.