Deploy: getting code to real people

Your project works. You have shown it to your friends on your laptop, and it worked. So you put it on a server, send the link around — and it breaks instantly. Same code, same files, same everything. The only thing that changed is where it is running. This moment has a name, and the name is a joke people tell because it happens to everyone: “but it worked on my machine”.

The reason it broke is that your laptop was never just running your code. It was also supplying a hundred things your code quietly depends on: which port to listen on, where the database lives, which API keys to use, which version of the language is installed, which files happen to be sitting in that folder. None of that is in your code, so none of it travelled with your code. The places your code runs are called environments. A typical setup has three: your laptop, where you build things and where it is fine to break stuff; staging, which is a copy of the real setup where the team checks things before users see them; and production, which is the real thing with real people and real money. The same program runs in all three, and the values are different in each.

env:         laptop     staging    production
-----------  ---------  ---------  -----------
PORT         3000       8080       80
API_KEY      test       test       live
LOG_LEVEL    debug      info       warn

Before code can run on a server, it often has to be turned into something the server can run: this is the build. Compiling TypeScript to JavaScript, bundling many files into one, shrinking images, producing a single folder that is ready to start. The distinction matters because these are two different steps with two different failure modes. A build failure happens on your machine, before anything is deployed, and it is cheap: nothing has reached users yet. A run failure happens on the server, with users watching. You want as many failures as possible to be build failures.

src/cart.ts       ---> dist/app.js
package.json      ---> node_modules/

ts ---> js

$ npm start
PORT=80 listening

So the honest version of “it works on my machine” is a checklist, and it is a short one. Is the configuration different here — port, database, keys? Is a dependency missing or a different version? Is the file the code expects actually present on this machine, with the same capitalisation? Does this machine have permission to use the network, the folder, the port? And — the one people forget — does it still work now, at this hour, under this much traffic? None of those questions are about your code being clever. They are about the world your code landed in.

Every deploy is also a small bet. So before you deploy, decide how you will get back. That plan has a name: a rollback. It means going back to the previous version that was known to work, usually with one command, and it should take seconds rather than hours. The point of a rollback is not to fix anything: it is to stop the damage while you work out what went wrong. Note what it requires. You need the previous version to still exist and still work. You need the data to survive the trip backwards, which is the hard part — if the new version already wrote a new kind of record into the database, the old version has to tolerate it. And you need to know it is broken, which means watching what happens right after a deploy rather than assuming.