DEV Community: Andrei Gaspar

Node.js Resiliency Concepts: Recovery and Self-Healing

Andrei Gaspar — Thu, 01 Oct 2020 13:11:21 +0000

In an ideal world where we reached 100% test coverage, our error handling was flawless,
and all our failures were handled gracefully — in a world where all our systems reached perfection,
we wouldn't be having this discussion.

Yet, here we are. Earth, 2020. By the time you read this sentence,
somebody's server failed in production. A moment of silence for the processes we lost.

In this post, I'll go through some concepts and tools which will make your servers more resilient and boost your process management skills.

Node Index.js

Starting with Node.js — especially if you're new to working with servers — you'll probably want
to run your app on the remote production server the very same way you're running it in development.

Install Node.js, clone the repo, give it an npm install, and a node index.js (or npm start) to spin it all up.

I remember this seeming like a bulletproof plan for me starting out. If it works, why fix it, right?

My code would run into errors during development, resulting in crashes,
but I fixed those bugs on the spot — so the code on the server is uncorrupted.
It cannot crash. Once it starts up, that server is there to stay until the heat death of the universe.

Well, as you probably suspect, that was not the case.

I was facing two main problems that didn't cross my mind back then:

What happens if the VM/Host restarts?
Servers crash... That's like, their second most popular attribute. If they weren't serving anything, we would call them crashers.

Wolverine vs T-1000

Recovery can be tackled in many different ways. There are convenient solutions
to restart our server after crashes, and there are more sophisticated approaches
to make it indestructible in production.

Both Wolverine and the T-1000 can take a good beating, but their complexity and recovery rate are very different.

We're looking for distinct qualities based on the environment we're running in.
For development, the goal is convenience. For production, it's usually resilience.

We're going to start with the simplest form of recovery and then slowly work our way up
to elaborate orchestration solutions.

It is up to you how much effort you'd like to invest in your implementation,
but it never hurts having more tools at your disposal, so if this spikes your interest,
fasten your seatbelt, and let's dive in!

Solving Problems as They Arise

You're coding away, developing your amazing server.

After every couple of lines, you switch tabs and nudge it with a node index or npm start.
This cycle of constant switching and nudging becomes crushingly tedious after a while.

Wouldn't it be nice if it would just restart on its own after you changed the code?

This is where lightweight packages like Nodemon
and Node.js Supervisor come into play.
You can install them with one line of code and start using them with the next.

To install Nodemon, simply type the below command in your terminal.

npm install -g nodemon

Once installed, just substitute the node command you've been using
with the new nodemon command that you now have access to.

nodemon index.js

You can install Node.js Supervisor with a similar approach, by typing the command below.

npm install -g supervisor

Similarly, once installed you can just use the supervisor prefix to run your app.

supervisor index.js

Nodemon and Supervisor are both as useful as they are popular, with the main difference
being that Nodemon will require you to make file changes to restart your process,
while Supervisor can restart your process when it crashes.

Your server is on the right track. Development speed quadrupled.

These packages do a great job covering development pain-points
and they are pretty configurable as well. But the difficulties we are facing in development
rarely overlap the ones we're facing in production.

When you deploy to the remote server, it feels like sending your kid to college as an overprotective parent.
You want to know your server is healthy, safe, and eats all its veggies.

You'd like to know what problem it faced when it crashed — if it crashed. You want it to be in good hands.

Well, good news! This is where process managers come into the picture. They can babysit your server in production.

Process Management

When you run your app, a process is created.

While running it in development, you would usually open a terminal window and type a command in there.
A foreground process is created and your app is running.

Now, if you would close that terminal window, your app would close with it.
You'll also notice that the terminal window is blocked.
You cannot enter another command before you close the process with Ctrl + C.

The drawback is that the app is tied to the terminal window,
but you're also able to read all the logs and errors that the process is throwing.
So it's a glass half full.

However, on your production server, you'll want to run in the background,
but then you'll lose the convenience of visibility. Frustration is assured.

Process management is tedious.

Luckily, we have process managers! They are processes that manage other processes for us.
So meta! But ridiculously convenient.

PM2

The most popular process manager for Node.js is called pm2,
and it's so popular for a very good reason. It's great!

It's such a fantastic piece of software that it would take me a separate article to describe its awesomeness
in its entirety, and just how many convenient features it has. Since we're focused on self-healing,
I'll discuss the basics below, but I strongly encourage you to read up on it more in-depth
and check all its amazing features.

Installing pm2 is just as easy as installing the packages we discussed above.
Simply type the following line in your terminal.

npm install -g pm2

Running your app isn't rocket science either. Just type the command below, where index.js is your main server file.

pm2 start index.js

This time, you might notice something different though.
Seemingly, nothing has happened, but if you go on to visit the endpoint to your app,
you'll notice that it's up and running.

Remember when we discussed running the process in the background?
That is exactly what is happening. pm2 started your server as a background process and it is now managing it for you.

As an added convenience, you can also use the --watch flag to make sure pm2 watches your files for changes
and reloads your app to make sure it is always up to date.

To do so, you can use the exact command above, but with the flag appended to the end.

pm2 start index.js --watch

Now, pm2 is watching our files and restarts the process anytime the files change or the process crashes.
Perfect! This is exactly what we're after.

It is doing a great job managing our server behind the scenes, but the lack of visibility is anxiety-inducing.
What if you want to see your server logs?

pm2 has you covered. Their CLI is really powerful! I'll list some commands below to get you started.

List your applications with the command below.

Command	Description
`pm2 list`	Lists your applications. You'll see a numeric `id` associated with the applications managed by pm2. You can use that id in the commands you'd like to execute.
`pm2 logs <id>`	Checks the logs of your application.
`pm2 stop <id>`	Stops your process. (Just because the process is stopped, it doesn't mean it stopped existing. If you want to completely remove the process, you'll have to use delete)
`pm2 delete <id>`	Deletes the process. (You don't need to stop and delete separately, you can just go straight for delete, which will stop and delete the process for you)

pm2 is insanely configurable and is able to perform Load Balancing and Hot Reload for you.
You can read up on all the bells and whistles in their docs, but our pm2 journey comes to a halt here.

Disappointing, I know. But why? I hear you asking.

Remember how convenient it was to install pm2?
We installed it using the Node.js package manager. Wink... Pistol finger. Wink-wink.

Wait. Are we using Node.js to monitor Node.js?

That sounds a bit like trusting your child to babysit itself. Is that a good idea?
There is no objective answer to that question, but it sure sounds like there
should be some other alternatives to be explored.

So, what next? Well, let's explore.

Systemd

If you're planning to run on a good old Linux VM, I think it might be worth mentioning systemd
before jumping onto the deep end of containers and orchestrators.

Otherwise, if you plan to run on a managed application environment
(e.g. Azure AppService, AWS Lambda, GCP App Engine, Heroku, etc.),
this will not be relevant to your use case, but it might not hurt knowing about it.

So assuming that it's just you, your app, and a Linux VM, let's see what systemd can do for you.

Systemd can start, stop, and restart processes for you, which is exactly what we need.
If your VM restarts, systemd makes sure that your app starts up again.

But first, let's make sure you have access to systemd on your VM.

Below is a list of Linux systems that make use of systemd:

Ubuntu Xenial (or newer)
CentOS 7 / RHEL 7
Debian Jessie (or newer)
Fedora 15 (or newer)

Let's be realistic, you're probably not using a Linux system from before the great flood,
so you'll probably have systemd access.

The second thing that you need is a user with sudo privileges.
I'm going to be referring to this user simply as user but you should substitute it with your own.

Since our user is called user and, for this example, I'm using Ubuntu,
I'll be referring to your home directory as /home/user/ and I'll go with the assumption that
your index.js file is located in your home directory.

The systemd Service File

The systemd file is a useful little file that we can create in the system area that holds the
configuration to our service. It is really simple and straightforward, so let's try to set one up.

The systemd files are all located under the directory listed below.

/lib/systemd/system

Let's create a new file there with the editor of your choice and populate it with some content.
Don't forget to use sudo as a prefix to your command! Everything here is owned by the root user.

Okay, let's start by going into the system directory.

cd /lib/systemd/system

Create a file for your service.

sudo nano myapp.service

And, let's populate it with some content.

# /lib/systemd/system/myapp.service

[Unit]
Description=My awesome server
Documentation=https://awesomeserver.com
After=network.target

[Service]
Environment=NODE_PORT=3000
Environment=NODE_ENV=production
Type=simple
User=user
ExecStart=/usr/bin/node /home/user/index.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

If you glance through the configuration, it's pretty straightforward and self-explanatory, for the most part.

The two settings you might need some hints on are After and Type.

After=network.target means that it should wait for the networking part of the server to be up and running
because we need the port. The simple type just means don't do anything crazy, just start and run.

Running Your App with systemctl

Now that our file has been created, let's tell systemd to pick up the changes from the newly created file.
You'll have to do this each time you make a change to the file.

sudo systemctl daemon-reload

It is as simple as that. Now that it knows about our service,
we should be able to use the systemctl command to start and stop it.
We will be referring to it by the service file name.

sudo systemctl start myapp

If you'd like to stop it, you can substitute the start command with stop.
If you'd like to restart it, type restart instead.

Now, on to the part we care most about.
If you'd like your application to start up automatically when the VM boots, you should execute the command below.

sudo systemctl enable myapp

If you want that behavior to stop, just substitute enable with disable.

It is as simple as that!

So, now we have another system managing our process that is not Node.js itself.
This is great! You can proudly give yourself a high five, or maybe an awkward elbow bump
depending on the pandemic regulations while reading this article.

Our journey does not stop here though. There's still quite a lot of ground left uncovered,
so let's slowly start diving into the world of containers and orchestration.

What are Containers?

To be able to move forward, you need to understand what Containers are and how they work.

There are a lot of container runtime environments out there such as Mesos, CoreOS, LXC, and OpenVz,
but the one name that is truly synonymous with containers is Docker.
It makes up more than 80% of the containers used and when people mention
containers, it's safe to think they are talking about Docker.

So, what do these containers do anyway?

Well, containers contain. They have a very simple and descriptive name in that sense.

Now the question remains, what do they contain?

Containers contain your application and all of its dependencies.
Nothing more and nothing less. It is just your app and everything that your app needs to run.

Think about what your Node.js server needs to execute:

Node.js (duh')
Your index.js file
Probably your npm packages (dependencies)

So, if we were creating a container, we would want to make sure these things are present and contained.

If we would have such a container ready, then it could be spun up via the container engine (e.g. Docker).

Containers vs VMs, and Italian Cuisine

Even if you haven't worked much with Virtual Machines,
I think you have a general idea about how they work.
You've probably seen your friend running a Windows machine with Linux installed on it,
or a macOS with an additional Windows installation, etc.

So the idea there is that you have your Physical Machine and an Operating System on top,
which then contains your app and its dependencies.

Let's imagine we're making pizza.

The Machine is the Table
The OS is the Pizza Dough
And, your app together with its dependencies are the ingredients on top

Now, let's say you'd like to eat 5 types of pizza, what should you do?

The answer is to make 5 different pizzas on the same table. That's the VM's answer.

But here comes Docker and it says: "Hey, that's a lot of waste! You're not going to eat 5 pizzas,
and making the dough is hard work. What about using the same dough?"

You might be thinking, hey that's not a bad idea actually — but I don't want
my friend's disgusting pineapple flavor (sorry, not sorry) spilling over
into my yummy 4 cheese. The ingredients are conflicting!

And here's where Docker's genius comes in:
"Don't worry! We'll contain them. Your 4 cheese part won't even know about the pineapple part."

So Docker's magic is that it's able to use the same underlying Physical Machine
and Operating System to run well-contained applications of many
different "flavors" without them ever conflicting with each other.
And to keep exotic fruit off your pizza.

Alright, let's move on to creating our first Docker Container.

Creating a Docker Container

Creating a Docker container is really easy, but you'll need to have Docker installed on your machine.

You'll be able to install Docker regardless of your Operating System.
It has support for Linux, Mac, and Windows, but I would strongly advise sticking to Linux for production.

Once you have Docker installed, it is time to create the container!

Docker looks for a specific file called Dockerfile and it will use it to create
a recipe for your container that we call a Docker Image.
So before we create a container, we'll have to create that file.

Let's create this file in the same directory we have our index.js file and package.json.

# Dockerfile

# Base image (we need Node)
FROM node:12

# Work directory
WORKDIR /usr/myapp

# Install dependencies
COPY ./package*.json ./

RUN npm install

# Copy app source code
COPY ./ ./

# Set environment variables you need (if you need any)
ENV NODE_ENV='production'
ENV PORT=3000

# Expose the port 3000 on the container so we can access it
EXPOSE 3000

# Specify your start command, divided by commas
CMD [ "node", "index.js" ]

It is smart to use a .dockerignore file in the same directory to ignore files
and directories you might not want to copy. You can think of it as working the same as .gitignore

# .dockerignore

node_modules
npm-debug.log

Now that you have everything set up, it's time to build the Docker Image!

You can think of an image as a recipe for your container.
Or, if you're old enough, you might remember having disks for software installers.
It wasn't the actual software running on it, but it contained the packaged software data.

You can use the command below to create the image. You can use the -t flag to name your image and
find it easier later. Also, make sure you opened up the terminal to the directory where your Dockerfile is located.

docker build -t myapp .

Now, if you list your images, you'll be able to see your image on the list.

docker image ls

If you have your image ready, you're just one command away from having your container up and running.

Let's execute the command below to spin it up.

docker run -p 3000:3000 myapp

You'll be able to see your server starting up with the container and read your logs in the process.
If you'd like to spin it up in the background, use the -d flag before your image name.

Also, if you're running the container in the background, you can print a list of containers using the command below.

docker container ls

So far so good! I think you should have a pretty good idea about how containers work at this point,
so instead of diving into the details, let's move ahead to a topic very closely tied to recovery: Orchestration!

Orchestration

If you don't have an operations background, chances are you're thinking about containers
as some magical sophisticated components. And you would be right in thinking that.
They are magical and complex. But it doesn't help to have that model in our minds, so it's time to change that.

It's best to think about them as the simplest components of our infrastructure, sort of like Lego blocks.

Ideally, you don't even want to be managing these Lego blocks individually
because it's just too fiddly. You'd want another entity that handles them for you,
sort of like the process manager that we discussed earlier.

This is where Orchestrators come into play.

Orchestrators help you manage and schedule your containers and they allow you
to do this across multiple container hosts (VMs) distributed across multiple locations.

The orchestrator feature that interests us the most in this context is Replication!

Replication and High Availability

Restarting our server when it crashes is great, but what happens
during the time our server is restarting? Should our users be waiting for the service
to get back up? How do they know it will be back anyway?

Our goal is to make our service Highly Available, meaning that our
users are able to use our app even if it crashes.

But how can it be used if it's down?

Simple. Make copies of your server and run them simultaneously!

This would be a headache to set up from scratch, but luckily, we have everything
that we need to enable this mechanism.
Once your app is containerized, you can run as many copies of it as you'd like.

These copies are called Replicas.

So let's look into how we would set up something like this using a container orchestration engine.
There are quite a few out there, but the easiest one to get started with is
Docker's orchestration engine, Docker Swarm.

Replication in Swarm

If you have Docker installed on your machine, you're just one command away from using Docker Swarm.

docker swarm init

This command enables Docker Swarm for you and it allows you to form a distributed cluster
by connecting other VMs to the Swarm. For this example, we can just use a single machine.

So, with Docker Swarm enabled, we now have access to the components called services.
They are the bread and butter of a microservice style architecture,
and they make it easy for us to create replicas.

Let's create a service! Remember the image name we used when we built our Docker image?
It's the same image we're going to use here.

docker service create --name myawesomeservice --replicas 3 myapp

The command above will create a service named myawesomeservice and it will use the image
named myapp to create 3 identical containers.

You'll be able to list your services with the command below.

docker service ls

You can see that there's a service with the name you specified.

To be able to see the containers that have been created, you can use the following command:

docker container ls

Now that our server is running replicated, the service will make sure to always
restart the container if it crashes, and it can offer access to the healthy containers throughout the process.

If you'd like to adjust the number of replicas of a service, you can use the command below.

docker service scale <name_of_service>=<number_of_replicas>

For example:

docker service scale myapp=5

You're able to run as many replicas as you'd like, just as simple as that.

Isn't that awesome? Let's look at one last example and see how we would approach replication in Kubernetes.

Replication in Kubernetes

It's hard to skip Kubernetes in a discussion about orchestration.
It's the gold standard when it comes to orchestration, and rightfully so.

I think Kubernetes has a much steeper learning curve than Swarm, so if you're just getting
started with containers I'd suggest picking up Swarm first. That said, it doesn't hurt to have
a general understanding of how this would work in the world of K8S.

If you don't feel like installing minikube
or you don't want to fiddle with cloud providers,
there's an easy option to dabble in Kubernetes for a bit, by using the
Play with Kubernetes online tool.
It gives you a 4-hour session which should be more than enough for small experiments.

To be able to follow this exercise, please make sure that you created
a DockerHub account, and pushed up the docker image to your repo!

We're going to create two components by creating two .yml configuration files:

A Cluster IP Service — this is going to open up a port for us to communicate with our app.
A Deployment — which is sort of like a service in Docker Swarm, with a bit more bells and whistles.

Let's first start with the ClusterIP. Create a cluster-ip.yml file and paste the following content into it.

# cluster-ip.yml

apiVersion: v1
kind: Service
metadata:
  name: cluster-ip-service
spec:
  type: ClusterIP
  selector:
    component: server
  ports:
    - port: 3000
      targetPort: 3000

Let's create a Deployment as well. Within a deployment.yml file, you can paste the following content.

# deployment.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: server-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      component: server
  template:
    metadata:
      labels:
        component: server
    spec:
      containers:
        - name: server
          image: your_docker_user/your_image
          ports:
            - containerPort: 3000

You'll need to make sure that you substituted the your_docker_user/your_image with your
actual user and image name and you have that image hosted on your Docker repo.

Now that we have these two files ready, all we need to do to spin this up is to execute
the command below. Make sure you're executing it in the directory that contains the files.

kubectl apply -f .

You can now check if your server is up and running by listing the deployments and services.

kubectl get deployments

kubectl get services

If everything worked out according to plan,
you should be able to copy-paste the IP and Port from your cluster-ip-service into your
browser's address bar to access your application.

To see the replicas that have been created, you can use the following command:

kubectl get pods

The pods listed should correspond to the number of replicas you specified in your deployment.yml file.

To clean up all the components, you can simply execute:

kubectl delete -f .

And just like that, we learned about Replication within Kubernetes as well.

Conclusion

So, we have an application that recovers and is highly available. Is that all there is to it?

Not at all. In fact, now that your app doesn't "go down", how do you know what issues it might be having?

By looking at the logs? Be honest. If your app is up every time you check the endpoint,
you'll probably check the logs about two times per year.
There's more interesting stuff to look at on social media.

So, to make sure your app is improving, you'll have to start thinking about monitoring,
error handling, and error propagation. You'll have to make sure that you're aware of issues
as they arise, and you're able to fix them even if they don't keep your server down.

That's a topic for another time though, I hope you enjoyed this article
and it was able to shed some light on some of the approaches you could use
to enable recovery for your Node.js application.

P.S. If you liked this post, subscribe to our new JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you'd love an all-in-one APM for Node.js or you're already familiar with AppSignal, go and check out AppSignal for Node.js.

Node.js Resiliency Concepts: The Circuit Breaker

Andrei Gaspar — Wed, 29 Jul 2020 13:53:14 +0000

In 2009 Node.js opened up a door for front-end developers to dip their toes into the world of servers
without having to leave the comfort of their language.

It's almost effortless to get started with Node.
You can basically copy-paste an entire HTTP server into existence and then install an ODM and you've got your CRUD app ready to roll!

However, if we've learned anything from the amazing Spider-Man,
it's that with great power, comes great responsibility.

So, in this article, we're going to discuss how you can wield your Node-given powers responsibly,
and design servers that don't just work, but are also resilient and adaptive to failures.

👋 AppSignal now supports Node.js as well. In the coming weeks, we’ll be adding a whole array of integrations i.e. support more things out-of-the-box. We already have support for Next.js, PostgreSQL, and Express. Learn more about AppSignal for Node.js.

Resiliency and Chill

One of the biggest names in the industry when it comes to server resiliency design is Netflix.
They are extremely dedicated to designing robust systems that will serve us all seasons
of Grey's Anatomy any minute of the day!

But what is this "resiliency" anyway?

Well, resiliency is just a fancy word for the ability of your system to recover from failures
and continue operating.

If the power goes out and it continues to work, your system is resilient.
If there is an equipment failure and the system keeps on going, it is even more resilient.
If you hit it with a baseball bat and the system is still up... you get the idea.

However, in our case, we're more interested in providing API resiliency.
So, let's see how we would identify a resilient API.
What are some of the core principles of a resilient API?

Well, let's learn from the pros. Let's see what Netflix has to say about it.

Netflix defines the principles of resiliency as follows:

A failure in a service dependency should not break the user experience.
The API should automatically take corrective action when one of its service dependencies fails.
The API should be able to show us what's happening right now, in addition to what was happening 15-30 minutes ago, yesterday, last week, etc.

They are also responsible for fault tolerance libraries and sophisticated tools
for dealing with latency and fault tolerance in distributed systems.

To deal with the problem of fault tolerance, most of these solutions use
a popular software design pattern called circuit-breaker,
which is the exact pattern that we're going to be discussing in detail in the upcoming sections.

The Circuit Breaker Pattern

The Circuit Breaker in software design is named after it's equivalent in electrical engineering,
where it serves as a switch designed to stop the flow of the current in an electric circuit.
It is used as a safety measure to protect the circuit from overload or short circuit.

Circuit breakers come in all shapes and sizes, there are some that reset automatically,
some that need to be reset manually, but they all essentially do the same thing — open the circuit
if there's trouble.

The Circuit Breaker was popularized by Miachel Nygard with his book Release It!,
where he describes this pattern along with other useful information about architecting
resilient and performant software.

So if the electrical circuit breaker manages the flow of current, what does it's software equivalent do?

The circuit breaker manages the flow of requests to an upstream resource.

Let's think of the upstream resource as a remote server for the time being,
but it is certainly not limited to being that. Circuit breakers can also be used
locally to protect one part of your system from failure from another part.

The circuit breaker monitors for failures, and when the failures reach a certain threshold,
it trips and none of the successive calls will be forwarded to the upstream resource.

Why Would We Bother Using a Circuit Breaker?

With the rising popularity of microservices, it is common for apps to make remote calls
to other apps running on different processes across a network.
It is often the case that the system is spread out across multiple machines as well.

Some of these services act as dependencies for others,
and it is not unusual to have multiple dependencies upstream.

Even if we forget about microservices altogether,
think about how common it is for applications to make remote calls.
It is almost unavoidable that it will have integrations and will rely on upstream resources.

Another popular case is an API gateway, where a service's primary purpose is to proxy requests upstream.
In this case, the health of the application is very closely tied to the health of the upstream resource.

So, we have all these cases where requests are being passed upstream, but why use a circuit breaker?
And why don't we just let the request fail at its own pace?

Preserve Resources

Wasteful calls pile up on the upstream resource which might be already struggling
with serving previous requests, further escalating the problem.

Wasteful calls can also be a big problem for the service making those calls.

Resources such as threads might be consumed while waiting for the upstream resource to respond,
which can lead to resource exhaustion.

This can in turn lead to the service being unable to handle other requests.

So, wasteful calls can bring down services,
and the failure can cascade to other services throughout the application.

Fail Fast

Imagine you're throwing a party on a Saturday evening.
You're making preparations, sending invitations to all your friends.

Would you prefer them to respond instantly, or would you prefer them to respond the day after the party?

I know, I'd go with option one.

We want responses fast so that we can adapt to them even if it means not getting what we asked for.

This concept in systems design is called failing fast.

Fail Proactively

When upstream resources give us lemons, we make lemonade.

You might not be able to prevent upstream failures, but you can always manage them proactively,
and make the most out of what you got.

Here are some common solutions to improve the failure:

Fallbacks - in certain cases, you might be able to fall back to another service.
Defaults - in certain cases, the integrity of the data is not crucially important, and defaults serve a good enough purpose until the upstream resource recovers.
Cache - you can serve cached requests until the upstream resource recovers.

Avoid Polluting the Logs

Your monitoring solution is one of the most important components of your system.
Without it, you're completely blind to what happens inside the dark realm of containers and Linux servers.

Metrics and logs are your eyes and ears.
And the better the quality of logs, the better you're able to understand what happens with your system.

If requests keep failing and you don't have a system in place that handles the situation gracefully,
it will end up pumping ungodly amounts of pollution into your logs.

Circuit Breaker States

The circuit breaker has 3 main states which give us a clue about the
health of the upstream resource or endpoint that we're targeting.

Closed - the closed state means that the circuit is closed and everything is running smoothly. Just like in the case of an electrical circuit.
Open - this state means that there is currently no connection upstream. In the case of an electrical circuit, if it is open, electricity cannot make its way through it.
Half Open - the half open state means it has experienced difficulties reaching the upstream resource, but it's now testing the waters with new requests to see if it can stabilize. If it does, it goes to the closed state, if requests fail, it opens the circuit again.

Even though these are the conventional names of circuit breaker states,
I prefer not to use them because I find them deceptive and can be misleading for developers.

When people see Open they're intuitively associating it with OK,
and Closed sounds a lot like something went wrong.

What I prefer to use instead are colors e.g. Red, Yellow, Green or
descriptive names like Failing, Stabilizing, OK.

So, for this demonstration, we're going to use colors to describe states,
but remember, this is just personal preference!

Creating Your Own Circuit Breaker

There are plenty of libraries out there that we could use to implement our circuit breaker,
but that would beat the purpose of the article since our goal is to understand how
the circuit breaker pattern is implemented.

So let's reinvent the wheel to learn how the wheel works.

What we are going to code:

The simplest Express.js server to act as our upstream resource and simulate succeeding and failing requests.
A configurable Circuit Breaker class that uses the Axios library to make requests, and has basic logging capability.
A few lines of code where we make use of our Circuit Breaker.

We are going to use TypeScript to implement these features.

So, let's dive in!

The first thing we want to do is to navigate to an empty directory of our choice,
which will be our work directory, and execute the npm init command.

npm init -y

Once we have the package.json file, it's time to install our main dependencies.

npm install --save express axios

Since we're using TypeScript, we'll also need some dev dependencies, so let's install those as well.

npm install --save-dev typescript @types/express @types/axios

Next, we're going to need a tsconfig.json file to hold our TypeScript configuration.
You can use the one below.

{
  "compilerOptions": {
    "outDir": "./build",
    "lib": [ "es5", "es6" ],
    "module": "commonjs",
    "target": "es6",
    "sourceMap": true
  },
  "exclude": [
    "node_modules"
  ]
}

Great, now our work directory should contain a node_modules directory
and three files: package.json, package-lock.json, and tsconfig.json.

It is time to copy-paste a basic Express server into existence.

Create a file called index.ts and paste the following lines of code into it.

// index.ts

import {Request, Response} from "express";

const express = require("express");
const app = express();

const port = 3000;


app.get( '/', (req: Request, res: Response) => {

    if ( Math.random() > 0.5 ) {
        res.status( 200 ).send( "Success!" );
    } else {
        res.status( 400 ).send( "Failed!" );
    }

});

app.listen( port, () => console.log( `Listening at http://localhost:${ port }` ) );

The above code snippet summons a simple express server that will be listening to GET requests on
localhost:3000, and randomly failing with status 400 or responding with status 200.
We'll be able to use this endpoint to test our Circuit Breaker.

Before we go further with the implementation, let's add a couple of convenience scripts to
our package.json file so that we can build and start the server using npm commands.

In the scripts section of your package.json, copy and paste the following:

...
  "scripts": {
    "build": "tsc",
    "start-server": "npm run build && node build/index.js"
  },
 ...

This will allow you to start your server with a simple npm command.

npm run start-server

Once the command is executed, the server should print "Listening at.. localhost:3000" to the console.

So far so good! Let's move on to the meat of the article, which is the Circuit Breaker itself!

Let's create a circuit-breaker directory, which will contain all the assets related to the Circuit Breaker.

mkdir circuit-breaker

Now, let's navigate into this directory and start thinking about the components
that we'll need to make the circuit breaker a reality.

First, we talked about states, so let's create a file called BreakerStates.ts to define our states.

We're going to use an enum and color codes for the states, to make it a bit more developer-friendly.

In the BreakerStates.ts file let's declare an enum like so:

// circuit-breaker/BreakerStates.ts

export enum BreakerState {
    GREEN = "GREEN",
    RED = "RED",
    YELLOW = "YELLOW"
}

Great, now that we have the states, what else do we need?

We'll need some configuration options for our Circuit Breaker
that will answer the following questions for us:

How many failures do we allow before moving to RED state? Let's call this our failureThreshold
How many successes do we need before moving to GREEN state? Let's call this our successThreshold
Once we are in RED state, how much time should we wait before we allow a request to pass through? We'll call this our timeout.

So, immediately, we can see that we'll need a public class named BreakerOptions
that can hold these properties. We could also opt for an interface trick here, but let's stick
to the conventional class-based approach.

Let's create a file called BreakerOptions.ts and define our public class.

// circuit-breaker/BreakerOptions.ts

export class BreakerOptions { constructor(
    public failureThreshold: number,
    public successThreshold: number,
    public timeout: number
){}}

Once we have the States and Options defined, we can start planning the CircuitBreaker
class implementation. Since the circuit breaker will be making requests,
and we're using Axios as our HTTP library, we'll have Axios as our dependency for this class.

Let's think about the properties that we'll have in the class.

request - the request property will contain details about the request that we are going to attempt. Since we integrated with Axios, it would be smart to have this as the Axios request configuration. We can use the AxiosRequestConfig type for that.
state - this property can hold our circuit breaker state. We have a BreakerState type created for this.
failureCount - we will need something to count the number of failures with, let's use this property for that purpose.
successCount - same as failureCount, but for tracking successes.
nextAttempt - we will need a property to store a timestamp for the next time when we try a request when we're in the RED state.

Let's not forget about the BreakerOptions we defined!
We'll need to store those inside the class as well.
It would also be smart to make them optional and have default values defined for them within the class.

failureThreshold - lets us know when to switch to RED state.
successThreshold - lets us know when to switch to GREEN state.
timeout - lets us know how much to wait before the next attempt (in milliseconds).

That is a handful of properties to be defined.
So let's set all this up before we move to the logic implementation.

Let's create a file called CircuitBreaker.ts where we'll define our CircuitBreaker class.

// circuit-breaker/CircuitBreaker.ts

import { BreakerOptions } from "./BreakerOptions";
import { BreakerState } from "./BreakerStates";
import { AxiosRequestConfig } from "axios";

const axios = require("axios");


class CircuitBreaker {
    private request: AxiosRequestConfig;
    private state: BreakerState;

    private failureCount: number;
    private successCount: number;

    private nextAttempt: number;

    // Options
    private failureThreshold: number;
    private successThreshold: number;
    private timeout: number;


    constructor(request: AxiosRequestConfig, options?: BreakerOptions) {

        this.request        = request;
        this.state          = BreakerState.GREEN;

        this.failureCount   = 0;
        this.successCount   = 0;
        this.nextAttempt    = Date.now();

        if ( options ) {
            this.failureThreshold   = options.failureThreshold;
            this.successThreshold   = options.successThreshold;
            this.timeout            = options.timeout;
        } else {
            // Define defaults
            this.failureThreshold   = 3;
            this.successThreshold   = 2;
            this.timeout            = 3500;
        }
    }

}

Now it's time to think about the methods that we'll need.
Let's plan them out and then we can start implementing them one by one.

log - we'll need a method to log the current state of the Circuit Breaker. We'll be able to use this same method to integrate with our monitoring system as well.
exec - the execute method will be a public API through which we'll be able to trigger the request attempt. We'll need to make this into an asynchronous function because we'll be waiting for a server response.
success - this method will handle the successful executions and return the upstream response.
failure - this method will handle the failed attempts and return the upstream response.

So let's start at the beginning and define our log method as such:

// circuit-breaker/CircuitBreaker.ts

   private log(result: string): void {

        console.table({
            Result: result,
            Timestamp: Date.now(),
            Successes: this.successCount,
            Failures: this.failureCount,
            State: this.state
        });
    }

All it's responsible for is taking the result and displaying it in a nice tabular format,
including other details about the current state of our Circuit Breaker.

Let's move on to the success method and define some logic. Here's what it should do for us.

Return the successful response.
Reset the failure count.
Log the status so that we're aware of what happened.
If in YELLOW state, increment the success count — and if the success count is larger than the threshold defined, reset and move to GREEN state.

Sounds easy enough, let's write the code!

// circuit-breaker/CircuitBreaker.ts

    private success(res: any): any {

        this.failureCount = 0;

        if ( this.state === BreakerState.YELLOW ) {
            this.successCount++;

            if ( this.successCount > this.successThreshold ) {
                this.successCount = 0;
                this.state = BreakerState.GREEN;
            }
        }

        this.log( "Success" );

        return res;

    }

Great, we have success down — we'll do the same for failure. Here's the gist of it.

Return the response.
Increment the failure count.
Log the status so that we're aware of the failure.
If the failure count exceeds the threshold, move to RED state, and define when our next attempt should take place.

Here's the code:

// circuit-breaker/CircuitBreaker.ts

    private failure(res: any): any {

        this.failureCount++;

        if ( this.failureCount >= this.failureThreshold ) {
            this.state = BreakerState.RED;

            this.nextAttempt = Date.now() + this.timeout;
        }

        this.log( "Failure" );

        return res;
    }

And finally, the most important method to define, the exec method!
This stands at the core of our mechanism. Let's see what it should do for us.

Most importantly, if the state is RED and the next attempt is scheduled sometime in the future, throw an Error and abort. We do not allow the request to go upstream.
If the state is RED but the timeout period expired, we want to switch state to YELLOW and allow the request to pass.
If the state is NOT RED we try to make the request, and based on whether the request succeeded or failed, we call the appropriate handler method.

Simple enough, right? Let's see how the implementation looks.

// circuit-breaker/CircuitBreaker.ts

    public async exec(): Promise<void> {

        if ( this.state === BreakerState.RED ) {

            if ( this.nextAttempt <= Date.now() ) {
                this.state = BreakerState.YELLOW;
            } else {
                throw new Error( "Circuit suspended. You shall not pass." );
            }
        }

        try {
            const response = await axios( this.request );

            if ( response.status === 200 ) {
                return this.success( response.data );
            } else {
                return this.failure( response.data );
            }
        } catch ( err ) {
            return this.failure( err.message );
        }
    }

So, now that we have our CircuitBreaker class all set up,
it's time to see how we can use it to perform requests.

Before anything else though, here's the complete implementation of the class,
you can review it to see if it matches yours!

// circuit-breaker/CircuitBreaker.ts

import { BreakerOptions } from "./BreakerOptions";
import { BreakerState } from "./BreakerStates";
import { AxiosRequestConfig } from "axios";

const axios = require("axios");



export class CircuitBreaker {
    private request: AxiosRequestConfig;
    private state: BreakerState;

    private failureCount: number;
    private successCount: number;

    private nextAttempt: number;

    // Options
    private failureThreshold: number;
    private successThreshold: number;
    private timeout: number;



    constructor(request: AxiosRequestConfig, options?: BreakerOptions) {

        this.request        = request;
        this.state          = BreakerState.GREEN;

        this.failureCount   = 0;
        this.successCount   = 0;
        this.nextAttempt    = Date.now();

        if ( options ) {
            this.failureThreshold   = options.failureThreshold;
            this.successThreshold   = options.successThreshold;
            this.timeout            = options.timeout;
        } else {
            // Define defaults
            this.failureThreshold   = 3;
            this.successThreshold   = 2;
            this.timeout            = 3500;
        }
    }



    private log(result: string): void {

        console.table({
            Result: result,
            Timestamp: Date.now(),
            Successes: this.successCount,
            Failures: this.failureCount,
            State: this.state
        });
    }



    public async exec(): Promise<void> {

        if ( this.state === BreakerState.RED ) {

            if ( this.nextAttempt <= Date.now() ) {
                this.state = BreakerState.YELLOW;
            } else {
                throw new Error( "Circuit suspended. You shall not pass." );
            }
        }

        try {
            const response = await axios( this.request );

            if ( response.status === 200 ) {
                return this.success( response.data );
            } else {
                return this.failure( response.data );
            }
        } catch ( err ) {
            return this.failure( err.message );
        }
    }



    private success(res: any): any {

        this.failureCount = 0;

        if ( this.state === BreakerState.YELLOW ) {
            this.successCount++;

            if ( this.successCount > this.successThreshold ) {
                this.successCount = 0;
                this.state = BreakerState.GREEN;
            }
        }

        this.log( "Success" );

        return res;

    }



    private failure(res: any): any {

        this.failureCount++;

        if ( this.failureCount >= this.failureThreshold ) {
            this.state = BreakerState.RED;

            this.nextAttempt = Date.now() + this.timeout;
        }

        this.log( "Failure" );

        return res;
    }

}

Looking good? Great!

Alongside our index.ts file, we can create a test.ts file as well, that will contain a
couple of lines of code for testing our masterpiece.

// test.ts
import { CircuitBreaker } from "./circuit-breaker/CircuitBreaker";



const circuitBreaker = new CircuitBreaker({
    method: "get",
    url: "http://localhost:3000"
});


setInterval(() => {
    circuitBreaker
        .exec()
        .then( console.log )
        .catch( console.error )
}, 1000 );

In the code above, we imported the CircuitBreaker,
created an instance of it and started calling the exec() method at an interval of 1 second.

Let's add one more script to our package.json file to be able to run this test conveniently.

The scripts section should look like this, updated with the test-breaker script:

...
  "scripts": {
    "build": "tsc",
    "start-server": "npm run build && node build/index.js",
    "test-breaker": "npm run build && node build/test.js"
  },
  ...

Now, let's make sure the server is running!

npm run start-server

And in a separate terminal window, let's run the circuit breaker test as well.

npm run test-breaker

Once executed, here's an example of the log stream that you should be seeing in your terminal.

Success!
┌───────────┬───────────────┐
│  (index)  │    Values     │
├───────────┼───────────────┤
│  Result   │   'Failure'   │
│ Timestamp │ 1592222319902 │
│ Successes │       0       │
│ Failures  │       1       │
│   State   │    'GREEN'    │
└───────────┴───────────────┘
Request failed with status code 400
┌───────────┬───────────────┐
│  (index)  │    Values     │
├───────────┼───────────────┤
│  Result   │   'Failure'   │
│ Timestamp │ 1592222320906 │
│ Successes │       0       │
│ Failures  │       2       │
│   State   │    'GREEN'    │
└───────────┴───────────────┘
..............
┌───────────┬───────────────┐
│  (index)  │    Values     │
├───────────┼───────────────┤
│  Result   │   'Failure'   │
│ Timestamp │ 1592222321904 │
│ Successes │       0       │
│ Failures  │       3       │
│   State   │     'RED'     │
└───────────┴───────────────┘
...............
┌───────────┬───────────────┐
│  (index)  │    Values     │
├───────────┼───────────────┤
│  Result   │   'Failure'   │
│ Timestamp │ 1592222331941 │
│ Successes │       2       │
│ Failures  │       1       │
│   State   │   'YELLOW'    │
└───────────┴───────────────┘
...............

From this point forward, you can have as much fun with it as you like.

You can start and stop the server while the circuit breaker is running to notice what happens,
and you can also create different breakers with different BreakerOptions like so:

// test.ts

import { CircuitBreaker } from "./circuit-breaker/CircuitBreaker";
import { BreakerOptions } from "./circuit-breaker/BreakerOptions";



const breaker1 = new CircuitBreaker({
    method: "get",
    url: "http://localhost:3000"
}, new BreakerOptions( 3, 5, 5000 ) );


const breaker2 = new CircuitBreaker({
    method: "get",
    url: "http://localhost:3000"
}, new BreakerOptions( 6, 7, 1000 ) );


setInterval(() => {
    breaker1
        .exec()
        .then( console.log )
        .catch( console.error )
}, 500 );

setInterval(() => {
    breaker2
        .exec()
        .then( console.log )
        .catch( console.error )
}, 1500 );

Implementation Granularity

Once you have it up and running, the design choices are in your hands.
You can choose to make a circuit breaker responsible for an entire upstream service or just target individual endpoints depending on your needs.

Feel free to use different HTTP integrations, experiment with extending the
breaker options and define multiple endpoints in your server to test with.

Here are additional feature ideas to consider:

Create an API for the breaker so that it can be reset or tripped by the operations staff.
Implement an event system around the Circuit Breaker so you can subscribe different parts of your application to it.
Integrate the breaker with your favorite monitoring solution.
Implement a Queue to automatically retry failed requests. (Warning: don't use this for requests downstream waiting for a response.)
Implement Caching to serve failed requests from the cache.

Parting Words

This sums up our overview of the Circuit Breaker pattern!
I hope this article helped you grasp a few resiliency principles
and it sparked your imagination to try extending this boilerplate with some creative solutions.

We reinvented the wheel to understand how it works,
but custom solutions are not always the best choice.
You have to analyze complexity and keep maintenance overhead in sight.

Once you're comfortable with the basics, I would suggest you check out a few npm packages
which are designed specifically for this purpose.
There are a couple of candidates out there like opossum, hystrixJS, and brakes.

It all depends on your requirements and I trust you to make the right decisions
in your journey to improve system resiliency!

P.S. If you liked this post, subscribe to our new JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you'd love an all-in-one APM for Node or you're already familiar with AppSignal, go and check out AppSignal for Node.js.

Daydreaming about APIs and imagining web services — our guest author Andrei is a solutions architect by day and the co-founder of Boardme by night. When he's not typing frantically in a terminal, he's exploring nature, pretends to draw, and supplies bystanders with unsolicited gym advice.

Emojis as Website URLs 🤔

Andrei Gaspar — Fri, 18 Oct 2019 10:04:15 +0000

So here's a completely useless, yet mildly interesting idea I was fiddling with not that long ago — can you use emojis as URLs in a website? Maybe the more important question would be: should you? However, since I care more about the technical implications, I'm going to let someone else figure out the answer to that.

So, is there a solution?

Long story short, yes. I figured out a pretty straight forward solution for handing this, and it involves encoding emojis into URIs, and mapping them to routes on the server.

Why encode them? — you might ask

The answer is simple: because that's what the browser does when it executes the HTTP Request. So if you're using an emoji in your website URL, the browser encodes it into a URI and that's the route your server is called on.

Here's how you encode an emoji

encodeURI('😊') // Result is "%F0%9F%98%8A"

Armed with this knowledge and with a burning desire for mischief, I started putting together a solution that offers emoji support for the basic routes of a website (think contact, pricing, terms, privacy, etc.)

This is how emoji-express 🚂 was born 🎉🎉🎉

Emoji express is an open source npm package, designed to be working with the popular express framework for NodeJS, so I though the name was fitting.

Initially it could do two things:

Add emoji support to a website with 2 lines of code
Let the user specify a custom string of emojis, that will redirect to a specific route in their website

Some examples would be:

/contact route

https://boardme.app/📮

/pricing route

https://boardme.app/💳

Then I received a request on twitter for a really interesting problem

Translating emojis from URLs automatically

To be able to solve this, you'd have to have the name of every single valid emoji, and all those names would have to be formatted to be URI compliant.

So for example:

https://example.com/🦇🚶‍♂️

would be translated to: https://example.com/batman-walking

https://example.com/🔥-in-the-🕳️

would be translated to: https://example.com/fire-in-the-hole

It seemed like a straight forward enough problem if I can get my hands on the data; so I started looking for emoji datasets online, and sure enough I found the complete emojipedia dataset, that contained the emojis and their names.

A couple nodejs scripts later, I had an array of all the emojis, with their names normalized, and their associated URIs

[
...
{
        "emoji": "🐢",
        "name": "turtle",
        "URI": "%F0%9F%90%A2"
    },
    {
        "emoji": "🦎",
        "name": "lizard",
        "URI": "%F0%9F%A6%8E"
    },
    {
        "emoji": "🐍",
        "name": "snake",
        "URI": "%F0%9F%90%8D"
    },
...
]

One last problem to solve - emoji modifiers

I thought - OK problem solved, I'll just need to run a find-and-replace on the route, basically finding the URI and replacing it with the emoji name.

NOPE.

Turns out, there are URIs that share the same base, but they are decorated with emoji modifiers to express the type of the emoji. (e.g. male/female, color, size etc.)

So, how do we make sure we are replacing the right URI? The answer is simple yet again: a decorated URI should be technically longer in size than a non-decorated URI

We are going to sort the emojis based on the length of their URI, before initiating the find-and-replace 💡

const emojisSorted = emojis.sort( (a, b) => ( a.URI.length < b.URI.length ) ? 1 : -1 );

That is all it took! emoji-express now has automatic emoji translate support for routes 🎉

Granted, there isn't much use for it, but it was a fun pet project to pick up. Feel free to take it for a ride!

Terraform with DigitalOcean on Windows

Andrei Gaspar — Fri, 18 Oct 2019 09:06:18 +0000

Terraform is a great tool for automating infrastructure management. You can think of it as infrastructure as code. Well, more like infrastructure as configuration — but you get the idea — you have some configs that spin up servers for you, and configure them the way you want.

Terraform works with a long list of service providers (e.g. AWS, Azure, GCP etc.) and it can be tailored to work with your in-house solutions as well. In this article we're going to go through a simple example of spinning up a droplet on DigitalOcean.

If you don't have a DigitalOcean account yet, sign up using this link — you'll get $50 in credits, I'll get $25; fair deal.

Alright, that's enough of an introduction. Let's get started.

DigitalOcean API token and SSH key

We'll need to generate a token and set up an SSH key before we get started using Terraform, so let's get that out of the way.

Once we're done here, we will have 4 important things that we'll need:

API token
Path to the private key we generated on your system
Path to the public key we generated on your system
SSH fingerprint of your key

Go to the API menu item, and click Generate New Token. Once this screen appears give it a name and press the Generate Token button.

Once your token has been generated, copy it and stash it in a safe place. Your token should look something like this:

72a134d5f2203f5dd58252998bf4823813541b8ac48be03b93e866a2e02072ea

~~We got the first important thing~~ ✔️

On to the SSH key.

Create an SSH key without a passphrase by typing this command in your terminal

ssh-keygen -t ecdsa

Give it a name when prompted, and specify the directory where you'd like it to be generated.

When it prompts for passphrase hit ENTER twice (no passphrase provided).

You should see something like this in the terminal

Generating public/private ecdsa key pair.
Enter file in which to save the key (C:\some\path\on\your_system): KEY_NAME
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in KEY_NAME.
Your public key has been saved in KEY_NAME.pub.
The key fingerprint is:
SHA256:sIo7STxwxv2ltjAZ1hCVbUyE3G5sKWs3LA9lTZo3Nb9 andrei@DESKTOP-D8GRA4B
The key's randomart image is:
+---[ECDSA 256]---+
|   . BB+         |
|    o.= . o      |
|   . +.O . o     |
|  . = #o= . .    |
|   = X.=S+   .   |
|    O.B +   E    |
|   o.B = .       |
|    o.. .        |
|    oo           |
+----[SHA256]-----+

Save the paths for your private and public key to a text file, we're going to need them.

~~We got the second and third important things.~~ ✔️

Great, now that we have our SSH keys, copy the content of the public key (yourkey.pub) you just generated, and head straight back to DigitalOcean.

Find the Security menu item to set up your SSH key, press Add SSH Key, paste the content of your public key in the input and give it a name.

Once you added the SSH key, it should appear under the list of SSH keys in a table showing it's name and it's fingerprint. We need that fingerprint, copy it and stash it somewhere safe.

It should look something like this:

~~The last important thing is stashed. Awesome stuff.~~ ✔️

Now let's set up Terraform.

Install Terraform

Download the package from here.

You'll download a zip file, which you'll unzip, and it should contain a file named terraform.exe

Copy or move that terraform.exe file in a place you want to keep it e.g.

C:\Users\YOUR_USER\TF

Now grab the path of the directory where you moved it, and append it to your Path environment variable — which you can find by simply typing environment in the windows start search box.

Click on Edit the system environment variables.

Append the directory path to the Path variable.

To test if it worked, restart your command prompt and type this command (it should return the version of Terraform).

terraform -v

Awesome. Terraform should be locked and loaded.

Create a Terraform Project

Now that we got these things out of the way, we can move on to working with Terraform. Let's start by making a project directory somewhere, and adding two files into it. We'll name one variables.tf and the other one droplet.tf.

The variables.tf file is where all those values that we stashed are going to come into play. You can paste the code below into it, and substitute the placeholders assigned to the default keys with your values.

variable "token" {
    type = "string"
    description = "DigitalOcean API Token"
    default = "YOUR_TOKEN_HERE"
}
variable "public_key" {
    type = "string"
    description = "The Path to Your Public Key"
    default = "PATH_TO_TOUR_PUBLIC_KEY_HERE"
}
variable "private_key" {
    type = "string"
    description = "The Path to Your Private Key"
    default = "PATH_TO_YOUR_PRIVATE_KEY_HERE"
}
variable "ssh_fingerprint" {
    type = "string"
    description = "SSH Key fingerprint"
    default = "YOUR_SSH_FINGERPRINT_HERE"
}

provider "digitalocean" {
    token = "${ var.token }"
}

As you can see we set up DigitalOcean as the provider. You can check the related documentation using this link.

In the droplet.tf file you can paste the code below.

resource "digitalocean_droplet" "tfdroplet" {
    image = "ubuntu-18-04-x64"
    name = "tfdroplet"
    region = "lon1"
    size = "512mb"
    private_networking = true

    ssh_keys = [
        "${var.ssh_fingerprint}"
    ]

    connection {
        user = "root"
        type = "ssh"
        private_key = "${file(var.private_key)}"
        timeout = "2m"
        host = "${self.ipv4_address}"
    }

    provisioner "remote-exec" {
        inline = [
            "export PATH=$PATH:/usr/bin",
            "sudo apt-get update",
            "sudo apt-get -y install nginx"
        ]
    }
}

With the code above we're creating a small DigitalOcean droplet, and configuring it. It is going to run the Ubuntu 18.04 version, it's located in London, and it has a size of 512mb.

After the droplet is created, we're also running an update command and install Nginx to it, to demonstrate how you would go about doing something like this.

Launch 🚀

Alright let's spin up this bad boy. This will be no more than 3 commands.
To install the dependencies needed, let's launch a terminal in your project directory and type:

terraform init

(you can think of this like an npm install, if you're familiar with node)

After terraform has been initialized, we can now run:

terraform plan

This command is going to make an execution plan for you to preview, you should see something like this in your terminal:

Refreshing Terraform state in-memory prior to plan...
The refreshed state will be used to calculate this plan, but will not be
persisted to local or remote state storage.

digitalocean_droplet.tfdroplet: Refreshing state... 

------------------------------------------------------------------------

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:
...
...
...
Plan: 1 to add, 0 to change, 0 to destroy.

Lastly, we can run the apply command to create our droplet and configure it.

terraform apply

This might take a few seconds to complete, but after the installation finishes you'll be able to see your new droplet listed on your DigitalOcean account.

If you want to SSH into it from Putty or your terminal, don't forget to use your private key that we created.

That's about it. I hope you enjoyed this brief look into Terraform and you'll be excited to learn more.