Bare Minimum Metalwork Stack

By Ev Bogue - July 30th 2015

The why of Metalwork is obvious: get a Metalsmith blog up and running without having to piece together the docs from 15 different sources.

The how is harder. The stack has changed a bit from the olden days of shared hosting and Geocities.

What is the bare minimum stack to run Metalwork?

A stack is the term people with technical skills use to talk shop about what programs they use on a computer. When one dork bumps into another dork on the Internet or at a coffee shop they ask the other dork what their stack is, and then judge them when they say "Mac > Apple > Facebook". In a way it's a way of judging someone who says they have tech skills, and then downgrading them in your mind when you find out they don't have any at all.

There is no one way to describe a tech stack. I find myself starting at the bottom and working up. Everything on the top of the stack depends on things deeper in the stack.

There are local stacks and virtual stacks. I'm using both.

The stack I use to run Metalwork is the following:

Local: Acer 373 > Arch Linux > Node > Koa > Metalsmith

Digital Ocean > Debian > Node > Koa > Metalsmith

This is the bare minimum stack. There's of course all sorts of other things running on my VPS such as Postfix, Procmail, and Spamassassin for me to run email. I send The Mailing and The Client List using Nodemailer, and that's a slightly different stack from Metalwork, but not that different.

Below, the stack in more detail.

Digital Ocean

Digital Ocean is a VPS (virtual private server) company that leases virtual computers with dedicated IP addresses you can use to run programs on. I have a referral code for them, so I'll get a little mone to keep funding my VPS habit if you use them. It is: https://www.digitalocean.com/?refcode=26d8ed49730d

You can create VPSes using a simple interface on Digital Ocean, they'll email you a password, and the next thing you know you can ssh into the VPS using the following command in your terminal

% ssh root@
Password: theonedigitaloceangaveyou

And the next thing you know you'll be logged in as root.

There are a lot of skills involved in running a VPS. If you want to learn more about them, read my opinionated book on how to run a VPS called Operator's Manual.


Debian is a Linux distribution. The latest version is Jessie. It's fairly stable. I'd prefer to use Arch Linux, but Digital Ocean doesn't support Arch Linux which is a shame. But I have Digital Ocean referal credit to use, so I stick with Debian. The good news about Debian is it's fairly innovative, being that they've implemented systemd. And they're also incredibly stable, which is why everyone uses Debian on their VPSes.

I cover basic UNIX skills such as how to pilot a Linux box in Operator's Manual as well.


Node.js is an interface for Chromium's V8 JavaScript engine. It lets you program web servers in JavaScript. Node is a huge innovation over CGI-BINs.

How to install Node.js on Debian is easy, just use the package manager to install Node and the package manager they use with Node right now.

$ sudo apt-get install nodejs npm

Next you'll need to update Node.js to the latest version, which right now is io.js. To do this, install n, which is a decent Node version manager, using npm

$ sudo npm install -g n

And install the latest version of io.js using n

% sudo n io latest

And type

% node -v 

To see what version of Node you're using. It should say 2.4.0 or higher

I'm writing a rolling release book on Node.js, and I think you should buy it if you want to get your skills up in this area.


Koa.js is a generator's based serverside framework for building web applications. Within Metalwork, I only really use it to serve a static website. I love the syntax, so that's why I use it.

var koa = require('koa')

var app = koa();



% npm install koa

I also use Koa static to serve Metalsmith's static files. So that app starts to look more similar to this:

var koa = require('koa'),
    serve = require('koa-static');

var app = koa();

app.use(serve(__dirname + './build'));


Don't forget to npm install it

% npm install koa-static

And that is all I'm using from Koa. There's a lot more. You can basically reimplement any modern web application you've ever used on the Internet using Koa if you back your head up against it enough.

There are a handful of Koa.js tutorials in The Node Book.


Metalsmith is the best static website generator I've been able to find on the Internet. In fact, it's perhaps more interesting to call it a static website framework. Because it's so flexible, you can build all sorts of things with it. The only rule is Metalsmith will probably render them down to static files.

I use Metalsmith together with Koa to bring Metalwork together. This is all of the Metalsmith code in Metalwork, with all of the Koa stripped out. Obviously there are templates and src files as well.

A simple Metalsmith site looks similar to this:

var metalsmtih = require('metalsmith'),
    markdown = require('metalsmith-markdown');

  .build(function(err) {
    if (err) {throw err; }

Here's the full code involved in Metalwork:

var metalsmith  = require('metalsmith'),
    markdown    = require('metalsmith-markdown'),
    templates   = require('metalsmith-templates'),
    collections = require('metalsmith-collections'),
    permalinks  = require('metalsmith-permalinks'),
    beautify    = require('metalsmith-beautify'),
    moment      = require('moment');

      blog: {
        pattern: './blog/*.md',
        sortBy: 'date',
        reverse: 'True'
      pattern: ':collections:title'
    engine: 'jade',
    .build(function(err) {
        if (err) {throw err; }
        console.log('Metalwork has been built');

That's a lot, but it's necessary to get a somewhat basic blog necessary. The good new is Metalsmith/Metalwork is so customizable you can rip out any of the middleware and replace it with anything you want.

This bare minimum stack for Metalwork might seem a bit overwhelming, but at most it's going to run out $5 a month at a VPs providor to keep running. Plus a yearly fee on a domain name, if you want to have a URL people can go to read your blog.

If you want to learn more about VPSes read Operator's Manual and The Node.js Book where I've covered these technologies in more depth. Questions? Hit me at my email.

Is minimalism a dead unicorn? →

← Node project idea - Delicio.us clone