DEV Community: Bruno Paulino

Ask away, like you career depends on it

Bruno Paulino — Mon, 23 Oct 2023 20:57:18 +0000

It has been a while since I wanted to write this but I've been putting this on the side, until this week when a more junior engineer at my current job approached me with some questions around a work-related topic. I noticed that he was a bit afraid of asking, perhaps concerned that he would come across as unprepared or stupid. Turns out, his question was really interesting and sparked a great conversation with surprisingly new learnings for him and myself.

This really motivated me to write this piece because I have once been like this and was constantly ashamed of asking questions, fearing to sound stupid or dumb, which eventually led me to lose a few opportunities.

But there was a point where I stopped worrying about this and the result of it was really surprising: It changed my life and career in several ways I could never imagine and today I want to share a few situations where I simply asked, already expecting the worst outcome, but it turned out to work much better than I could ever believe.

Getting the chance to study without losing my job

Before going to university and becoming a full-time software engineer, I was a police officer. This was a particularly challenging job because I was part of a military force in my home state, which as you can probably guess, it's a job
that involves a lot of rules, discipline and hierarchy. You don't simply go around asking people, you need to follow the chain of command and crossing this line can have consequences.

After a while, I figured this job wasn't really what I wanted to do, so I went to university. There was one little challenge: The classes had many conflicts with my work schedule, so I would have to figure out how I could work and study at the same time.

I was a little worried that it would be troubling to find a work schedule that could support my studies, so I was already thinking that I would have to give up university given that I couldn't afford to lose my job. Either way, I simply
went to my boss and asked if he could support me in figuring this out. Surprisingly, he was quite happy that I was going to university and went out of his way to help me out. He figured out a way to change my work schedule where I could work a few nights and weekends and I wouldn't have to miss classes much.

It all worked out and I managed to study just fine. I missed one class here and there, but I wasn't expecting to attend at all. That was a huge win already.

Everything was going well until nearing the end of my studies, where I managed to get a scholarship with all expenses paid to go to the US.

Getting the chance to study abroad without losing my job

I was starting to feel defeated. There was no way for me to go, spend almost 2 years in the US without losing my job. I thought "That is it, I am gonna lose this opportunity. I cannot afford to support my family without my job".

Although I knew the chances of keeping my job while away were really slim, I had to ask my boss again. I thought "What have I got to lose? I did not have this opportunity in the first place. Worst case, I graduate here and eventually get another job".

So I went and talked to my boss. Surprisingly, he was one of the happiest guys around when he heard the news. He was very honest and told me he had no clue whether I could go and keep my job, but he would do everything on his power to help me out. He asked me for a few days so he could figure something out.

A week had gone by. It was a weekend evening when he called me and said "Hey Bruno, I've figured something out. Let's try it next week". After talking to him I was really surprised, I had no idea what that could be, but I was willing to try anything.

Next week, once I was back to the office, he explained to me that there was some sort of particular law which allowed the police chief to authorize any particular officer to go anywhere and take a course that could benefit the police.

I HAD NO CLUE THIS EVEN EXISTED! Neither did my boss, until he talked to his colleagues about my situation and a good friend of his, who turns out was a really good lawyer, explained it to him. Long-story short, we went through all the paperwork internally and eventually I got the approval to go, enjoy my
hard-earned scholarship in the US while I kept my job, including part of my salary.

The following picture is me and a couple of friends making a Brazilian BBQ in one of many sunny days in Florida:

Everything was going well until I was nearing the end of my studies in the US. I was given the opportunity to find an internship and stay for another 3 months. If I couldn't find it, I would have to head back to my country in 2 weeks.

Getting the chance to work abroad and bring along 10 other colleagues

And the time to find an internship came. I was looking for jobs everywhere in the little town I was based in (Melbourne, Florida).

If you are not familiar with this area in Florida, you have probably heard about the "Space Coast", which is this area in the USA where rockets go around, where NASA is based at, together with many companies working with aerospace tech.

This was super exciting to me during my whole time there, but when it came to find an internship, I quickly found that many of these companies have contracts with the American Department of Defense and, due to security reasons, if you are not an American citizen, they won't even consider you as a suitable candidate. This is even written in the job ad as a requirement.

So my search for an internship immediately became quite difficult. My American friends were getting job interviews left and right, while I was only getting rejections. I thought "That is it, I'm going back to Brazil without some international experience. But that is fine, I got really far, this is already good enough".

I was once again at the state of feeling defeated. I felt I've not tried hard enough to get an internship. So I started reaching out to other foreign colleagues that got internships in the past. Until one of them gave me a hint about a jet research lab that took him in the past summer. I looked it up and to my surprise, this was a Brazilian company (Embraer), with a research facility in the same town I was based at.

Looking at their website and LinkedIn page, I couldn't find any available opportunity. So I started checking the folks that work there. I managed to find one of the HR department heads on LinkedIn. I couldn't contact her directly given that we were not connected on the platform, so I just tried to guess her work email address.

I simply tried:

Subject: Looking for an Internship Opportunity
to: firstname.lastname@embraer.com

{Email body left out for brevity}

I sent her an email. I didn't receive any error delivery message, so I assumed it worked and her email existed. This already felt like a small win. But even then, my chances of getting a reply were really slim. Worse yet, even if I get a
reply, what are the chances of getting an actual internship opportunity? Very likely zero. But it was worth asking it anyways.

Three days later, a unexpected surprise

Three days have gone by since I sent her that email. Around that time, I've already mostly given up my internship search and was already preparing to travel back home. Then suddenly, I had this one unread message in my inbox. The message looked something like the following:

Re: Looking for an Internship Opportunity

Hi Bruno, Thank you for reaching out. I'm really glad you wrote me regarding that. I am trying to contact someone at Florida Tech for a couple of weeks now, but I couldn't get a hold of anyone from the administration.

We actually have 10 available spots for the Summer Internship Program at Embraer and we are looking for students like you. Could you send me your resume and if you have more colleagues looking for internship opportunities in IT, please let me know.

After reading this email, I couldn't believe it... I not only found a potential opportunity for me, but somehow I could also help ten other colleagues?

I am pretty sure that you, the reader, might be thinking that this is some sort of joke and to be honest, I couldn't believe it myself when I read this email.

Fast-forward 2 weeks later, I managed to get one of the spots for that internship program, and believe it or not, I also managed to bring along 10 other friends that were in a similar situation. All of them got hired.

This internship was one of the coolest experiences in my professional career and I could not have been happier about its outcome. I made many friends from several different countries, I learned a sh*t ton of new stuff and I even got paid for it.

Here is a picture of me, a few of my colleagues that joined me after that lucky email I sent, and one of our great managers, getting the chance to experience the Embraer Legacy aircraft, the same aircraft which the queen of England used to fly around back then:

What can you learn from this?

I think there was a good lesson I learned from these experiences. I had several opportunities during my life that I could have completely missed out if I didn't ask for help back then. And in other situations, where I had no clue whether something could work, by simply asking around, I could carve out the opportunity I needed, like that internship.

In retrospect, I feel quite lucky. I was at the right place, at the right time and thankfully had the right people by my side. Things could have turned out much differently, but by the simple fact that I asked around, I managed to increase the likelihood of these lucky moments to come to reality.

So if you are ever wondering whether you should ask, just go, ask. You should, of course, do your homework, research around what you are looking for and try to help yourself first. If you are reaching out to a mentor, a friend or your boss, try to offer a few ideas on how this person can help you with right away.

But even then, if you are clueless, ask anyways. The worst outcome is likely that things will remain the way they are. And in case things don't work out, you at least tried and can already think about other plans.

Most people have good intentions and are very likely able to help you. Sometimes you hit a jerk here and there, but you know, they are not the common place. They are also missing the opportunity to be part of your story, so don't hold questions to yourself.

Distributed locks in Node.js

Bruno Paulino — Wed, 26 Jul 2023 05:04:15 +0000

Often times, you need to build a feature that requires coordinated access to a certain resource. A common use-case is around queues where jobs can be enqueued to be processed in the background.

These jobs can either be:

Picked up by a fleet of workers and processed in parallel. The order they start and finish doesn't matter.
Picked up and processed serially. The order they are processed matters.

The first case is generally simple enough. You generally don't have to concern yourself with race conditions. Jobs can be processed successfully (or failed and retried) in any order they come in.

But what happens when you must guarantee that their processing order be respected? If you have a single server and a single worker thread, then it's simple. Jobs will be processed serially and their ordering will be respected.

And what happens when you have a fleet of workers deployed across different servers? You will need to "elect" one of your workers to be the one processing these jobs. Better yet, you must make sure that if that worker dies or gets removed from your servers pool, another healthy worker must pick-up the jobs and continue processing them in some sort of handover fashion. This is where a distributed lock algorithm is handy.

Here is our demo running where we simulate two servers competing to acquire the lock and how the lock handover works when a server goes down:

If you are a savvy Node.js engineer and just want to see the code, here is the Github repo ready for you. Feel free to leave a Github star so folks can find this distributed lock template more easily.

Locks on a single node

A lock is a common mechanism that helps the programmer to restrict access (mutual exclusion) to certain resources, allowing you to control which thread can read or write to shared data.

In a single-thread, event-loop based runtime like Node.js, you generally don't need locks, but in multi-threaded environments like in Rust, you usually need to use the primitives for atomic operations provided by the standard library like std::sync::Mutex, which guarantees that a given code path is only accessed by one thread at a time.

Primitives like this are super useful, but our use-case goes beyond one single server. Remember that we are crossing the boundaries of a server here and we must make sure that other workers do not process our jobs in case one worker is already processing them.

We need to extend the concept of a lock and make it distributed, where other servers can also see who is holding the lock and act accordingly.

Making our lock distributed with Redis

Given that we must share the lock state across servers, we need some sort of distributed data sharing mechanism that can synchronize this data across our fleet of workers. We could somehow connect our workers and send messages among them, but that would be quite complex to pull it off. Another alternative is to use a shared data store like a database that can make the lock state instantly available across our servers. Redis fits perfectly for that purpose.

Redis is a fantastic technology. If you are not familiar with it, Redis is an in-memory database. It is incredibly fast and can act as a shared cache across your cluster of servers.

Redis provides APIs for atomic operations, which will support us in guaranteeing that only a single worker can acquire a lock at any given time. We will see that in action soon, but this blogpost largely follows the pattern suggested by Redis itself in its patterns manual here called Redlock for cases where we have a single instance of Redis.

To facilitate the understanding on how the distributed lock works, have a look in the following diagram. We have a pool of four workers which are Node.js servers responsible for processing our hypothetical serial queue. These four servers will concurrently try to acquire the lock by setting a key-value pair in Redis. The first server that manages to do it, "wins" and will hold the lock. With the lock at hand, this server should be able to start processing jobs.

Then, in case this server needs to be shutdown (e.g. during a deployment), the lock should be released, giving the chance to one of the other servers to acquire it and continue to process the background jobs.

Fail-safe with expiring keys

So far, our example has been focusing on releasing the lock when a server needs to shutdown. But what happens during a hardware failure? What if your app panics and crashes out of nowhere? This situation could lead you to a deadlock where no other server from your server pool will be able to acquire the lock to keep processing jobs.

Redis provides a very useful feature where whenever you set a key-value pair, you can also define how long this value can last on its memory. Redis will clean it up automatically after the given time passes.

We will be seeing how to set a key with an expiry time very soon, but here is how it will look like at a high-level:

Renewing the lock from time to time

Given that our lock, represented by the entry we store in Redis, expires automatically after a certain time, we must make sure that our worker that holds the lock can renew the lock from time to time to make sure that it's still the one holding the lock.

To perform that, Redis also provides an API to specifically change the expiry time of a given key. The EXPIRE command will help us to accomplish that.

But enough theory, let's dip into the code and see that in action.

Kicking off with a Demo

We start by demonstrating this implementation in action so you get a feeling of how it works and then we will have a look at the code, step-by-step.

To kickstart this project, I've used Remix with the Express adapter so I can
have a super quick project already setup with TypeScript. The code is available here, so just clone it, npm install to kick things off.

But before running our Node.js app, we need Redis available as a dependency so our app can connect to it. The simplest way to install Redis is to use Docker. Our project already comes with a handy docker-compose file that bootstraps Redis for you.

So make sure that Docker is running and just execute the following:

docker-compose up -d

This is going to run Redis in the background, which will be a perfect fit for our app. Now, copy the .env.example file and rename it to .env. This should be enough for starting our app:

npm run dev

If you watch your server logs, you should see a few logs showing that:

Your node tried to acquire the lock
The lock was successfully acquired
It's doing some (simulated) work like processing background jobs

Trying to acquire lock { workerId: '01H63B5EAKQZTCDAT8AAVQ9WAG' }
Lock acquired. Starting work { workerId: '01H63B5EAKQZTCDAT8AAVQ9WAG' }
Doing some heavy work... { workerId: '01H63B5EAKQZTCDAT8AAVQ9WAG' }

Now, open a new terminal window and fire up a new process from our Node.js app on a different port with the following command:

PORT=3001 npm run dev

This simulates having another server of your app running and trying to acquire the lock. You will only see that your new process will keep trying to acquire the lock every 5 seconds. You will see logs like the following:

Trying to acquire lock { workerId: '01H63B9M322QAP09D6EJ19SGWC' }

Now, shutdown your app on your first terminal window, the one holding the lock. Have a look at the second terminal window now. It should pick up the lock and start processing the background jobs.

Trying to acquire lock { workerId: '01H63B9M322QAP09D6EJ19SGWC' }
Lock acquired. Starting work { workerId: '01H63B9M322QAP09D6EJ19SGWC' }
Doing some heavy work... { workerId: '01H63B9M322QAP09D6EJ19SGWC' }

This is what we want to accomplish. We want to make sure that our background jobs are never left behind. When a worker goes down, another worker picks it up and continue processing.

Notice that we always log the worker ID, so it's easy to identify which worker
node has the lock and which ones are just waiting and trying to acquire it.
The Node ID is a fundamental part of this lock implementation given that we
use it to identify which node is actively holding the lock. The Node ID is
automatically assigned during server startup time.

Managing our lock state using a state machine

You are probably asking yourself:

How does each node know how and when to acquire the lock or wait to try
acquiring it again?

This is where state machines come in. They help us to model our state transitions in a very elegant way.

I personally enjoy using xstate, a finite state machine library that helps us to model how our state looks like and the transition between them, including failure modes.

The folks from Stately, the maintainers of xstate, even provide a Web UI for modeling and visualizing our state machine. Here is how it looks like:

You can also play with this interactive demo here. On this UI, you can simulate all the state transitions and visually see how the state machine works.

Kicking off our state machine during server startup

The main goal of this state machine is to coordinate the following:

Once our server starts up, we must signal to the state machine that it's time to attempt to acquire the lock:
- If the lock is acquired successfully, our worker can start processing the background jobs. In the meantime, our worker also needs to renew the lock to make sure that it can continue processing background jobs.
- In case it can't acquire it, either because of another worker that has already acquired it or because Redis is unavailable, our worker needs to sit on an idle state for a few seconds and then later on attempt to acquire the lock again.

Don't worry if you are not familiar with state machines. The xstate introductory article does a fantastic job in introducing you the concept and guides you through creating your first state chart, but let's walk through the code to see how the entire process works and I will be referencing our demo project with links here so it's easy for the reader to track it back to the code.

Once we start listening to HTTP requests, here we can start our worker with a call to startLockWorker:

httpServer.listen(process.env.PORT, () => {
  console.log("Express server started at port " + process.env.PORT);
  startLockWorker();
});

Now let's head to the worker implementation of startLockWorker here:

export function startLockWorker() {
  service.start();
  service.send("TRY_ACQUIRE_LOCK");
}

We have an instance of a service. While you can read more about them here, Services wrap our state machines and allow us to observe how the state moves
forward in time, allowing us to hook up callbacks to it and monitor how our state changes over time.

We first start our service so it listens to events and we immediately send it a TRY_ACQUIRE_LOCK. This event will kick-off our state machine, which internally will trigger its internal services to try to acquire the lock. We will have a
look at our actual state machine code soon.

If you look at where we create this service instance, you will see the following call:

const service = interpret(
  createLockMachine({
    workerId,
    acquireLock: acquireWorkerLock,
    releaseLock: releaseWorkerLock,
    renewLock: renewWorkerLock,
    startWork: consumeResource,
    stopWork: stopConsumingResource,
  })
);

This is effectively where we create an instance of our state machine when calling createLockMachine. This call takes an object with several parameters:

workerId: Gives us context on which worker this state machine belongs to. If you are familiar with React state management, context in xstate is similar to React state. When transitioning between xstate "states", you usually modify its context.
acquireLock: An async callback that tries to acquire the lock. It resolves when the lock is acquired successfully or rejects the promise by throwing an error when it fails.
releaseLock: An async callback that tries to release the lock. It resolves when the lock is released successfully or rejects the promise by throwing an error when it fails.
renewLock: An async callback that tries to renew the lock when the worker holds it. It resolves when the lock is renewed successfully or rejects the promise by throwing an error when it fails.
startWork: An async callback that starts doing the actual background job processing.
stopWork: An async callback that stops any background job processing. This is important for cases where a worker doesn't manage to renew the lock so it needs to stop and wait.

These callbacks are our services interface which allow us to make our state machine reusable. We can reuse the same state machine to manage different distributed locks across our application by just creating different instances of it and passing the service callbacks that do the actual business logic.

Now let's have a look at our state machine:

export function createLockMachine({
  workerId,
  acquireLock,
  renewLock,
  releaseLock,
  startWork,
  stopWork,
}: CreateMachineArgs) {
  return createMachine(
    {
      predictableActionArguments: true,
      id: "lock-worker",
      context: {
        workerId,
      },
      schema: {
        services: {} as Services,
        events: {} as Event,
      },
      initial: "idle",
      on: {
        STOP: "cleanup",
      },
      states: {
        idle: {
          on: {
            TRY_ACQUIRE_LOCK: "acquiring_lock",
          },
        },

        cleanup: {
          invoke: {
            src: "stopWork",
            onDone: {
              target: "releasing_lock",
            },
            onError: {
              target: "releasing_lock",
            },
          },
        },

        acquiring_lock: {
          invoke: {
            src: "acquireLock",
            onDone: {
              target: "working",
            },
            onError: {
              target: "waiting_to_acquire_lock",
            },
          },
        },

        working: {
          invoke: {
            src: "startWork",
          },
          after: {
            "5000": {
              target: "renew_lock",
            },
          },
        },

        renew_lock: {
          invoke: {
            src: "renewLock",
            onDone: {
              target: "working",
            },
            onError: {
              target: "pause_work",
            },
          },
        },

        pause_work: {
          invoke: {
            src: "stopWork",
            onDone: {
              target: "waiting_to_acquire_lock",
            },
            onError: {
              target: "waiting_to_acquire_lock",
            },
          },
        },

        releasing_lock: {
          invoke: {
            src: "releaseLock",
            onDone: {
              target: "idle",
            },
            onError: {
              target: "idle",
            },
          },
        },

        waiting_to_acquire_lock: {
          after: {
            "5000": {
              target: "acquiring_lock",
            },
          },
        },
      },
    },
    {
      services: {
        acquireLock: (context, _event) => {
          console.log("Trying to acquire lock", { workerId: context.workerId });
          return acquireLock();
        },
        renewLock: (context, _event) => {
          console.log("Renewing lock", { workerId: context.workerId });
          return renewLock();
        },
        releaseLock: (context, _event) => {
          console.log("Releasing lock", { workerId: context.workerId });
          return releaseLock();
        },
        startWork: (context, _event) => {
          console.log("Lock acquired. Starting work", {
            workerId: context.workerId,
          });
          return startWork();
        },
        stopWork: (context, _event) => {
          console.log("Stop work", { workerId: context.workerId });
          return stopWork();
        },
      },
    }
  );
}

Ok, don't be overwhelmed. This is how xstate lets us declare our state machine. It's mostly a JavaScript object with a specific structure.

The main thing you want to watch out for is how our machine transition from one state to another. Let's have a look at what happens when our machine enters the acquiring_lock state:

acquiring_lock: {
  invoke: {
    src: "acquireLock",
    onDone: {
      target: "working",
    },
    onError: {
      target: "waiting_to_acquire_lock",
    },
  },
},

When it enters this state, it invokes the source (src) service called acquireLock. In our case, service calls are async functions that when resolved successfully will use the onDone transition and will move to the target state, which in this case is working.

If the promise returned by this callback rejects, it will enter the onError block and will transition to the waiting_to_acquire_lock state.

Let's have a look at the working state here:

working: {
  invoke: {
    src: "startWork",
  },
  after: {
    "5000": {
      target: "renew_lock",
    },
  },
},

First, notice that it does not have any target states in the invoke clause. This is by design given that when our worker is performing background job processing, we want it to remain that way for as long as it can. But it does have a src service called startWork. This is our service callback that allows our worker to effectively start processing the background jobs.

Also notice that we have an after block. This is how xstate lets us declare state transitions that will trigger automatically after a given period of time. In this case, whenever our state machine is on the working state, after 5
seconds, it will transition to the renew_lock state.

Let's head to the renew_lock state here:

renew_lock: {
  invoke: {
    src: "renewLock",
    onDone: {
      target: "working",
    },
    onError: {
      target: "pause_work",
    },
  },
},

This state is interesting. It will invoke a service called renewLock and in case it succeeds, it will transition back to the working state, which will give a chance to our worker to keep chugging along with our background jobs. For the cases where it fails, our target state is pause_work which in turn also has a src service that notifies our worker to stop any background processing.

After this tour, you might be wondering how these string identifiers are turned into function calls? Let's have a look at our services section in our state machine:

{
  services: {
    acquireLock: (context, _event) => {
      console.log("Trying to acquire lock", { workerId: context.workerId });
      return acquireLock();
    },
    renewLock: (context, _event) => {
      console.log("Renewing lock", { workerId: context.workerId });
      return renewLock();
    },
    releaseLock: (context, _event) => {
      console.log("Releasing lock", { workerId: context.workerId });
      return releaseLock();
    },
    startWork: (context, _event) => {
      console.log("Lock acquired. Starting work", {
        workerId: context.workerId,
      });
      return startWork();
    },
    stopWork: (context, _event) => {
      console.log("Stop work", { workerId: context.workerId });
      return stopWork();
    },
  },
}

This is the second argument to the createMachine call. Notice that the key names here all match with the src we've seen before. This is where we connect the callbacks we've given to our lock machine function signature and our state
machine. This is the abstraction that allows us to make our state machine flexible and reusable across our app.

Redis expiring keys in action

We've gone through our state machine and saw how the lock callbacks are being called, but how are we making sure that Redis is operating the way we expect? Let's have a look at how we set and update the expiry time of our keys using ioredis.

Let's head to our acquireLock function here:

export async function acquireLock(
  lockKey: string,
  lockValue: string,
  expireAfterInSeconds: number
): Promise<boolean> {
  const result = await redis.call(
    "set",
    lockKey,
    lockValue,
    "NX",
    "EX",
    expireAfterInSeconds
  );

  return result === "OK";
}

Here we are using native redis commands to set our key. The secret sauce is within the NX and EX arguments:

NX: set if Not eXists. Returns 'OK' on successful cases, null otherwise
EX: set with expiration time. The key will be removed after the elapsed time (given in seconds)

This is a fundamental part of this implementation. Redis allows us to have keys that automatically expire and get deleted from its memory, which guarantees that we won't face lock contention. This covers the eventual case where a server crashes and don't get the chance to release the lock, which would cause a major issue for all our other workers that would be forever waiting to acquire the lock.

Renewing the lock by extending the expiry time

Whenever our worker holds the lock, it attempts to renew the lock from time to time. This is also covered by a Redis API. let's have a look at our renewLock function here.

export async function renewLock(
  lockKey: string,
  lockValue: string,
  expireAfterInSeconds: number
): Promise<boolean> {
  const result = await redis.get(lockKey);

  // Lock is available, we can attempt to acquire it again.
  if (result === null) {
    return acquireLock(lockKey, lockValue, expireAfterInSeconds);
  } else if (result === lockValue) {
    // Lock is still held by this worker
    // we can safely renew it by extending its expiry time
    await redis.expire(lockKey, expireAfterInSeconds);
    return true;
  } else {
    throw new Error(
      "Lock held by another node. Can neither renew or acquire it"
    );
  }
}

Here we use the ioredis API for expiring keys. This API allows to either eliminate keys from Redis immediately if we set the expiry time to zero or to extend the expiry time of an existing key for the given seconds.

This is exactly what we do here. Whenever our worker holds the lock, we just extend the expiry time. Notice how the workerId plays a major role here. We use it as the lockValue. This way we make sure that only the worker holding the lock can safely renew it.

Where to go from here

I acknowledge that I mostly glanced over most of the concepts here, but the important thing is that you now have all the building blocks to build a distributed lock in Node.js, including a demo project (available here) that you can use as a reference.

Though, one step further on this demo is to increase the availability of our Redis instance. Right now, we deal with only a single instance of Redis, but what happens if Redis goes down? To improve this implementation, you should look
into having a Redis cluster with multiple master nodes. That is where you would actually implement the Redlock algorithm on its full capacity.

Modern Webapps with React, Phoenix, Elixir and TypeScript

Bruno Paulino — Fri, 21 Jan 2022 14:22:00 +0000

I've started working on a side project this year and the tech stack I have chosen was the Elixir lang due to its functional design and fault tolerance (Thanks to the Erlang VM) so the Phoenix framework was a natural choice for me.

While Phoenix provides a very interesting programming model called LiveView, I wanted to stick with the frontend stack I'm most familiar with which is React. Besides using it heavily in my day job, I also really appreciate the ecosystem around it.

If you are a savvy Elixir engineer and just want to see the code,
here is the Github repo ready for you. Feel free to leave a Github star so folks can find this template more easily.

I wanted to come up with a solid Phoenix project where I can get all the benefits from Elixir and Phoenix itself, but also be flexible enough by not coupling my React frontend with Phoenix. My requirements were:

Be able to use Hot Module Replacement during frontend development.
Run the React frontend in a separate process from the Phoenix app
During development, changes on the React frontend do not trigger the elixir compiler
During development, changes on the Phoenix app do not trigger frontend recompilation
CORS. I don't want to think about it. It's a no-brainer if we bundle all our apps together under the same domain.
In production, serve the React frontend under the /app/* path from Phoenix
In production, all other routes should be server-rendered, so we can still benefit from serve-side rendering for specific cases like better SEO and dynamic landing pages with a smart caching strategy via Cloudflare using stale-while-revalidate headers.

With the clear requirements defined above, I managed to make them all work by combining Phoenix and Vite. So let's get our hands dirty, write some code and make this project work!

This guide assumes that you are already familiar with Elixir, Phoenix and a frontend framework like React, so we skip a few basic concepts and jump straight in. Although, I will be linking some important resources to guide you in case you are just starting with this stack.

Creating our Phoenix project

First of, make sure you have the following dependencies installed:

Elixir: installation guide here
Phoenix: installation guide here
NodeJS 16 or above: installation guide here using NVM
PostgreSQL: Download here

Now let's head to our terminal and create our Phoenix app:

mix phx.new phoenix_react

Once your project is react, cd into it and fire up the Phoenix server:

cd phoenix_react
# Make sure the Postgres database is available for Ecto
mix ecto.create
# Start the dev server
mix phx.server

Now you should be able to access your Phoenix app at localhost:4000 and see a page like the following:

Awesome! We have got our Phoenix app up and running. Let's bootstrap our React app in an independent directory.

Creating our React with TypeScript project

For our React frontend, I've chosen Vite to handle all the tooling for me. It has got all the sane defaults I need for a TypeScript project with React, plus it uses ESBuild which gives us blazing fast feedback during development.

To kick things off, leave the Phoenix server running and open up a new terminal window. Still within the Phoenix directory in your terminal, let's use the Vite CLI to create our React project:

npm init vite@latest frontend -- --template react-ts

This should create our React project under the frontend directory. Let's install all dependencies and start our Vite dev server:

cd frontend
npm install
npm run dev

Now head to your browser at localhost:3000, you should see our React app up and running!

Adding routes to our React app

There is a major difference between Phoenix routes and React routes:

Phoenix routes are mapped to a request to the server, which results in a new template rendering which results in the whole browser to reload.
React routes are client-side only, which means that navigating from /app/settings to /app/profile in our React app doesn't mean a new request to the server. It might just mount a new component instantly which might not need server data at all.

So the strategy here is to leverage React Router on our React app for any route that is under /app and whenever the client makes the first request to our app, let's say they are visiting example.com/app for the first time, Phoenix will handle this initial request and serve the initial HTML together with our React app payload, so the React app can be mounted and take care of the routing from there.

To make sure that client-side route changes are working, let's add a very basic routing component so we can test if our react app is working. Let's start by installing React Router in our React app. Stop the dev server and execute the following:

npm install react-router-dom@6

Now open up your favorite text editor and edit our React app file at phoenix_react/frontend/src/App.tsx with the following components:

import { useEffect } from 'react';
import { BrowserRouter, Link, Routes, Route } from 'react-router-dom';

const style = {display: 'flex', gap: '8px', padding: '8px'}

function App() {

  /**
   * During development we can still access the base path at `/`
   * And this hook will make sure that we land on the base `/app`
   * path which will mount our App as usual.
   * In production, Phoenix makes sure that the `/app` route is
   * always mounted within the first request.
   * */
  useEffect(() => {
    if (window.location.pathname === '/') {
      window.location.replace('/app');
    }
  }, []);

  return (
    <BrowserRouter basename="app">
      <nav style={style}>
        <Link to="/">Home</Link>
        <Link to="/settings">Settings Page</Link><br/>
      </nav>
      <Routes>
        <Route path="/" element={<HomePage/>}/>
        <Route path="settings" element={<SettingsPage/>}/>
      </Routes>
    </BrowserRouter>
  );
}

function SettingsPage() {
  return(
    <div>
      <h1>Settings Page</h1>
      <ul>
        <li>My profile</li>
        <li>Music</li>
        <li>About</li>
      </ul>
    </div>
  );
}

function HomePage() {
  const style = {padding: '8px'}
  return(
    <div style={style}>
      <h1>React TS Home</h1>
      <p>Welcome to the homepage</p>
    </div>
  );
}

export default App;

Now you should be able to visit localhost:3000/app and see a screen similar to the following:

Try to click around the Home and Settings Page links at the top. Notice that it transitions between pages instantly. If you check your Phoenix console, you notice that no requests have been fired to your backend. So far so good.

Also notice that we now access our React app via the /app route. This is important and plays a major role when we bundle our application for production and serve it from Phoenix. We are using a small hook to check whether our app was mounted to the / path and redirect to the base path. This is only relevant for development. In production, Phoenix will make sure that the user is always in the /app when using our React app.

Serving our React frontend from Phoenix

So far, Phoenix has no clue about our React app. We need to come up with a way to tell Phoenix how to serve our React app once it's bundled and ready to be served as a SPA. For that to work, we can do the following:

Build our React app for production with Vite
Copy our production build to the priv/static folder so we can use Plug.Static to serve our static assets
Make Phoenix aware about the /app route so our generated index.html from vite can be statically served, which will trigger our React resources to be loaded.

Creating a custom mix task to do the job

To manage point 1 and 2 from the previous section, we can create a custom mix task that can execute all the TypeScript bundling via NPM and coping files around to make our React app ready to be served by Phoenix.

Our custom mix task will make sure that:

All of our frontend dependencies are installed
build our frontend for production distribution
Move the production files to priv/static/webapp

The /priv/static/webapp path will be picked up by Phoenix later on, but make sure that you add it to your .gitignore file. We don't want to commit our frontend production bundles.

Let's go ahead and create lib/mix/tasks/webapp.ex with the following Elixir code:

defmodule Mix.Tasks.Webapp do
  @moduledoc """
    React frontend compilation and bundling for production.
  """
  use Mix.Task
  require Logger
  # Path for the frontend static assets that are being served
  # from our Phoenix router when accessing /app/* for the first time
  @public_path "./priv/static/webapp"

  @shortdoc "Compile and bundle React frontend for production"
  def run(_) do
    Logger.info("📦 - Installing NPM packages")
    System.cmd("npm", ["install", "--quiet"], cd: "./frontend")

    Logger.info("⚙️  - Compiling React frontend")
    System.cmd("npm", ["run", "build"], cd: "./frontend")

    Logger.info("🚛 - Moving dist folder to Phoenix at #{@public_path}")
    # First clean up any stale files from previous builds if any
    System.cmd("rm", ["-rf", @public_path])
    System.cmd("cp", ["-R", "./frontend/dist", @public_path])

    Logger.info("⚛️  - React frontend ready.")
  end
end

Using the System module, we can interact directly with our host system, so we can issue shell commands when invoking our custom mix task.

Let's try it out. Stop your Phoenix server and execute the following command:

mix webapp

# You should see an outout similar to the following:
15:48:13.605 [info]  📦 - Installing NPM packages
15:48:15.034 [info]  ⚙️  - Compiling React frontend
15:48:19.611 [info]  🚛 - Moving dist folder to ./priv/static/webapp
15:48:19.618 [info]  ⚛️  - React frontend ready.

Our frontend is ready to be served by Phoenix now. But there is one little change we have to make to our Vite configuration so our Frontend static assets can be delivered.

Making the webapp base path discoverable

By default, Phoenix serves static content from the priv/static directory using the base route /. For instance, if we have a JPG file at priv/static/assets/picture.jpg, Phoenix will make this resource available at /assets/picture.jpg to the public.

We want that to happen, but for our web app, static resources will be under the /webapp/ path. Luckily, this is extremely simple.

Vite base path for production

Since we want to serve our Web app from priv/static/webapp, we have to make sure that during our production build, Vite should append the /webapp/ base path to all our resources. This is paramount for our app to work.

Vite provides a specific configuration entry for that. Let's go ahead and edit our frontend/vite.config.ts file with the following:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  // using the `webapp` base path for production builds
  // So we can leverage Phoenix static assets plug to deliver
  // our React app directly from our final Elixir app,
  // Serving all files from the `priv/static/webapp` folder.
  // NOTE: Remember to move the frontend build files to the
  // `priv` folder during the application build process in CI
  // @ts-ignore
  base: process.env.NODE_ENV === 'production' ? '/webapp/' : '/',
})

Now execute our custom mix task again from within our Phoenix project:

mix webapp

Once this is done, take a look at the priv/static/webapp/index.html contents. We should see an HTML similar to the following:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/webapp/assets/favicon.17e50649.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
    <script type="module" crossorigin src="/webapp/assets/index.fb986a90.js"></script>
    <link rel="modulepreload" href="/webapp/assets/vendor.6b432119.js">
    <link rel="stylesheet" href="/webapp/assets/index.458f9883.css">
  </head>
  <body>
    <div id="root"></div>

  </body>
</html>

Notice that all URLs there have the /webapp/ base path prepended. That is very neat. Our Frontend is ready to be served by Phoenix.

Serving static assets via Plug

Phoenix is still unaware of our webapp static folder. We must add that to our endpoint configuration so our Plug.Static can serve it. Head to lib/phoenix_react_web/endpoint.ex at line 23. Add the webapp to the string list:

plug Plug.Static,
    at: "/",
    from: :phoenix_react,
    gzip: false,
    only: ~w(assets fonts images webapp favicon.ico robots.txt)

With that tiny change, Phoenix is now able to serve the static assets generated by Vite.

Serving the initial HTML page via Phoenix

We now have a fully functional frontend and our Phoenix backend is able to deliver its static assets like JavaScript and CSS files. But to make it really feel native to our
platform, we must be able to visit example.com/app or any other route under /app and our React app must be able to mount all its components based on the given route.

For that to work, we must deliver the initial index.html that was generated by Vite whenever someone visits /app/*. We need a custom Phoenix controller. Let's build that now.

Create a new controller at lib/phoenix_react_web/controllers/webapp_controller.ex with the following module:

defmodule PhoenixReactWeb.WebappController do
  use PhoenixReactWeb, :controller

  def index(conn, _params) do
    conn
    |> send_resp(200, render_react_app())
  end

  # Serve the index.html file as-is and let React
  # take care of the rendering and client-side rounting.
  #
  # Potential improvement: Cache the file contents here
  # in an ETS table so we don't read from the disk for every request.
  defp render_react_app() do
    Application.app_dir(:phoenix_react, "priv/static/webapp/index.html")
    |> File.read!()
  end
end

We now have a controller that can serve our index.html file, but we need to configure a route that will hit this newly created index function. Let's add the following scope to our Phoenix router:

scope "/app", PhoenixReactWeb do
  get "/", WebappController, :index
  get "/*path", WebappController, :index
end

Awesome! Let's try this out. Make sure that your Vite dev server is stopped and start your Phoenix server with mix phx.server and go to localhost:4000/app. You should see the exact same result that we had when our Vite dev server was running!

Try to click through the header links. It should be all client-side routing. The ultimate test is to type in the url localhost:4000/app/settings, hit enter and see what happens.

Notice that the /app/settings page will be displayed as we expected. Behind the scenes, Phoenix kept delivering the index.html file and the React Router made sure that the right components were mounted. Sweet! Our Phoenix and React apps are ready to roll!

API requests and CORS

If you have been developing frontend apps that talk to an external API, I'm quite confident that you have faced a bunch of CORS issues. For those that are not familiar with, whenever you open up an app at myapp.com and that same app needs to call an API at myapi.com the browser prevents that by default.

Actually, the browser will issue an OPTIONS request to check if myapi.com allows requests coming from myapp.com to be answered. This is a very interesting security mechanism and I'm glad it's there. If you want to learn more about it, Jake Archibald wrote an awesome blogpost about it with all the information you need to know.

Skipping the whole CORS trouble

Whenever we are developing an app that it's all hosted under the same domain, things are way easier and simpler. If our myapp.com makes a request to myapp.com/api/users the browser won't even think about checking that because it knows that myapp.com is under the same domain, so it's pretty sure that you allow requests to come and go from your own domain.

During development, we are running our Phoenix app at port 4000 and our React app at port 3000, we need to find a way for requests made by our React app to localhost:3000/api/users to be captured by some sort of proxy and forwarded to our Phoenix backend at port 4000.

Luckily, Vite saves the day again by providing us with the server proxy configuration. Head over to the frontend/vite.config.ts and add the server entry to your config:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  // Forward all requests made by our React frontend to `localhost:3000/api`
  // to our Phoenix backend running at `localhost:4000`.
  // This is only necessary during development.
  // In production, our Phoenix and React apps are served from the same
  // domain and port, which makes this configuration unecessary.
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:4000',
        secure: false,
        ws: true,
      },
    }
  },
  // using the `webapp` base path for production builds
  // So we can leverage Phoenix static assets plug to deliver
  // our React app directly from our final Elixir app,
  // Serving all files from the `priv/static/webapp` folder.
  // NOTE: Remember to move the frontend build files to the
  // `priv` folder during the application build process in CI
  // @ts-ignore
  base: process.env.NODE_ENV === 'production' ? '/webapp/' : '/',
})

From now on, if you are making requests with axios for instance, you can safely make a request in your React component like this:

import {useState, useEffect} from 'react';
import axios from 'axios';

export function RequestComponent() {

  const [todos, setTodos] = useState([]);

  useEffect(() => {
    axios.get('/api/todos').then(response => {
      const { todos } = response.data;
      setTodos(todos)
    });
  }, []);

  return(
    <div>
      { 
        todos.map(t => <span key={t.id}>{t.content}</span>) 
      }
    </div>
  )

}

The request to /api/todos should be forwarded to your Phoenix backend and as long as you have a route and a controller to respond to that, API requests will be served just fine.

Authentication via http-only Cookies will also just work without any extra setup since everything is under the same domain. (localhost during development and myapp.com in production)

Creating an Elixir Release

We have got everything setup now and the cherry on top is to generate the Elixir release with our production Phoenix app.

The major advantage of an Elixir Release is that it creates a single package including the Erlang VM, Elixir and all of your code and dependencies. The generated package can be placed into any machine without any preconfigured dependency. It works similarly like Go binaries that you just download and execute.

But before we generate our release, since we are testing the build locally, we need to change the port configuration since our runtime configuration is binding to 443 by default. Let's quickly change that at config/runtime.exs:

config :phoenix_react, PhoenixReactWeb.Endpoint,
  # here use the `port` variable so we can control that with environment variables
  url: [host: host, port: port],
  # Enable the web server
  server: true,
  http: [
    ip: {0, 0, 0, 0, 0, 0, 0, 0},
    port: port
  ],
  secret_key_base: secret_key_base

With that out of the way, execute the following commands to generate the release:

# Generate a secret for our Phoenix app
mix phx.gen.secret
# It will output a very long string. Something like this:
B41pUFgfTJeEUpt+6TwSkbrxlAb9uibgIemaYbm1Oq+XdZ3Q96LcaW9sarbGfMhy

# Now export this secret as a environment variable:
export SECRET_KEY_BASE=B41pUFgfTJeEUpt+6TwSkbrxlAb9uibgIemaYbm1Oq+XdZ3Q96LcaW9sarbGfMhy

# Export the database URL
# Probably very different in production for you.
# I'm just using the local postgreSQL dev instance for this demo
export DATABASE_URL=ecto://postgres:postgres@localhost/phoenix_react_dev

# Get production dependencies
mix deps.get --only prod

# Compile the project for production
MIX_ENV=prod mix compile

# Generate static assets in case you
# are using Phoenix default assets pipelines
# For serve-side rendered pages
MIX_ENV=prod mix assets.deploy

# Generate our React frontend using
# our custom mix task
mix webapp

# Genereate the convenience scripts to assist
# Phoenix applicaiton deployments like running ecto migrations
mix phx.gen.release

# Now we are ready to generate the Elixir Release
MIX_ENV=prod mix release

We now have our production release ready. Let's fire it up with the following command:

PHX_HOST=localhost _build/prod/rel/phoenix_react/bin/phoenix_react start

# You should an output similar to the following
19:52:53.813 [info] Running PhoenixReactWeb.Endpoint with cowboy 2.9.0 at :::4000 (http)
19:52:53.814 [info] Access PhoenixReactWeb.Endpoint at http://localhost:4000

Great! Now our Phoenix app is running in production mode. Now head to your browser and open localhost:4000/app. You should see our React app being rendered!

We have finally succeeded with our Phoenix + React + TypeScript setup. It provides us with a great developer experience while simplifying our production builds by bundling our Phoenix app together with our React app.

Wrapping up

While that might have been a tiny bit complex to setup, I believe it is still worth it to keep your SPA decoupled from your backend. Here is a list with a few bonus point of this setup:

A single repo to work with which simplifies development, specially with a bigger team
Simpler CI/CD pipelines on the same repository
Free to swap out Vite in the future in case we decide to go with a different build tool
In the extreme case of changing our backend from Phoenix to something else, our React frontend is still fully independent and can basically be copy-pasted into a new setup.

I personally believe that the development and deployment of our applications should be simple and while having React as a dependency does increase complexity into our app, the trade-off of building web apps with it pays off in my case. Although, if you have simple CRUD apps, sticking with vanilla Phoenix templates and LiveView might be more than enough.

You can find the repo with all the changes we made on this post here.

How to use Redis Cluster for caching

Bruno Paulino — Thu, 02 Sep 2021 10:29:57 +0000

In this post, we will explore how we can use Redis as a cache layer for our application and as we explore it further, we will see how a Redis Cluster can provide us more scalability and reliability.

TLDR: If you are already familiar with Redis and it's just looking for a way to spin-up a fully configured Redis Cluster using Docker, here is the Github repo. Just clone this repo, go to your terminal, run docker-compose up and you should be good to go.

What is Redis?

Redis is a key-value store. In rough terms, it works just like a database, but it keeps its data in memory, which means that reads and writes are orders of magnitude faster compared to relational databases like PostgreSQL. It is important to mention that Redis does not replace a relational database. It has its own use-cases and we will explore some of them in this post.

For more information about Redis, have a look at their website here. There you find good documentation and how to install it on your machine. However, we will be building a demo during this post and we will use an interesting setup using Docker and docker-compose that will spin up and configure the entire Redis cluster for you. The only thing you need available is Docker.

Using Redis for caching

Whenever we need fast access to some sort of data, we need to think about ways of keeping this data as close to the application layer as possible. If the amount of data is small enough, It's generally a good idea to keep this data in the local memory so we have instant access. But when we talk about web applications, specially the ones that are stateless and can potentially run in multiple servers, we can't guarantee that the data we need will be present as well as making sure that other servers in your cluster have fast access to this same data.

That is where databases are handy. We can write this data to a central place and other servers can fetch this data whenever they need. The issue with some databases is that if you really need blazing fast access, some of them won't be able to deliver that at bullet speed. Redis is generally the go-to database whenever you need fast and reliable access to specific bits of data. It also provides us with ways to set expiration policies on that data so they are deleted automatically when they expire.

Redis is usually a good choice for storing:

User sessions
Authentication tokens
Rate-limit counters

Redis is by no means limited to the use-cases above, but they fit well when you need fast data access, most often on every request coming through your servers.

What is the point of using a cluster?

It is usually common to start with a single server instance, perhaps connected to a database server which can take you a long way. But once you need to scale you application across different countries and sometimes different continents, it probably means that your application needs to be available 24h a day, 7 days a week. And robustness and reliability needs to be embedded in your application.

You need to start to think about what happens when one of your database servers go down, either because of an issue in the network or because of a faulty hardware. If you have only a single instance you will be dead in the water. If you have backups, it's going to take sometime until you can spin up a new instance, configure it all up to your standards, restore the backup and put it back in business.

If your application is mission critical, you cannot afford to be offline for a few hours. Some applications cannot even be offline for a few minutes in the entire year. This is where a Cluster with replicas can save your skin when a problem like that happens.

A Redis Cluster makes sure that your data is automatically shared across multiple Redis instances, which will give you a higher level of reliability and availability. In case one of those instances experience any kind of failure, the other nodes can still serve content normally for your application.

Spinning up a Redis cluster

I've recently migrated a large web application from using a single Redis instance to a cluster with multiple shards, including multiple replicas. While we are using AWS infrastructure that provides us the entire cluster configuration, I couldn't simply trust that everything would work in production. I had to make sure that we could support a Redis cluster during development, so I've created a setup that spawns several Redis containers and connect with each other automatically to form a cluster.

To connect to Redis from your application, you will need a library that can perform that for you (Otherwise you have to reinvent the wheel). While I've been using IORedis for a nodeJS application in this demo, if you have been using a different language, you will have to look for different connectors like Lettuce for Java or perhaps go-redis for Go.

The entire setup is ready for you in this Github repository here, so you don't have to worry about creating anything from scratch. You can clone it and give it a spin while we will be walking through the files from this repo along the rest of this blogpost.

Creating a Dockerfile

While we will be using the standard Redis image available from Dockerhub to spin up several Redis containers, we still need a way to connect them. That is where we will be building a special container that can issue commands to Redis in a way that it can form a cluster.

at redis/Dockerfile we have the following content:

FROM redis:latest

COPY ./entrypoint.sh /entrypoint.sh
RUN chmod 755 /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

We will be using this Dockerfile to build our custom Docker image based on Redis. The secret sauce here is actually in at redis/entrypoint.sh. Let's have a look at this script:

#!/bin/sh

# Using the redis-cli tool available as default in the Redis base image
# we need to create the cluster so they can coordinate with each other
# which key slots they need to hold per shard

# wait a little so we give some time for the Redis containers
# to spin up and be available on the network
sleep 5
# redis-cli doesn't support hostnames, we must match the
# container IP addresses from our docker-compose configuration.
# `--cluster-replicas 1` Will make sure that every master 
# node will have its replica node.
echo "yes" | redis-cli --cluster create \
  173.18.0.2:6379 \
  173.18.0.3:6379 \
  173.18.0.4:6379 \
  173.18.0.5:6379 \
  173.18.0.6:6379 \
  173.18.0.7:6379 \
  --cluster-replicas 1

echo "🚀 Redis cluster ready."

Here we are using the redis-cli to issue commands. This command is creating a cluster and pointing to the specific Redis instances that will be reachable when we start this script. we are using hard-coded IP addresses here that will be provided by our docker-compose.yml file later on.

This cluster is composed by 3 shards. Each shard has a master node that is responsible for all the writes, but also a Replica node that holds a copy of the data. A Redis Cluster shard can have up to 500 replicas (at least in AWS). A Replica node has the power to take over and become the Master node if the current Master becomes unavailable.

Now notice that inside of our redis folder we also have a file called redis.conf. This file will be copied to each Redis container later on so they can instruct the Redis instance to work as part of a cluster. Let's have a look at its contents:

# Custom config file to enable cluster mode
# on all Redis instances started via Docker
port 6379
cluster-enabled yes
# The cluster file is created and managed by Redis
# We just need to declare it here
cluster-config-file nodes.conf
cluster-node-timeout 5000
appendonly yes

There is not much going on there. The important part is cluster-enabled yes which enables our Redis instance to act as part of the cluster. We now need a way to spin up several Redis containers and make sure that they talk to each other. At the root folder of our project we have the docker-compose.yml. Let's have a look:

volumes:
  redis_1_data: {}
  redis_2_data: {}
  redis_3_data: {}
  redis_4_data: {}
  redis_5_data: {}
  redis_6_data: {}
  # This volume is specific for the demo Express application
  # built in this repo. You probably won't need that on your own setup.
  node_modules: {}

services:

  app:
    container_name: express_app
    image: express_app
    build:
      context: .
    environment:
      PORT: 4000
      NODE_ENV: production
      REDIS_CLUSTER_URLS: 'redis_1:6379,redis_2:6379,redis_3:6379,redis_4:6379,redis_5:6379,redis_6:6379'
    volumes:
      - .:/app
      - node_modules:/app/node_modules
    command: [ "npm", "run", "dev" ]
    depends_on:
      - redis_1
      - redis_2
      - redis_3
      - redis_4
      - redis_5
      - redis_6
      - cluster_initiator
    ports:
      - "4000:4000"
    stdin_open: true
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.10

  # Here we have six Redis containers with Cluster mode enabled,
  # three of them will work as master nodes and each one of
  # will have a replica, so in case of failures, the replica becomes the master.
  # They are configured by the `cluster_initiator` container.
  redis_1:
    image: 'redis:latest'
    container_name: redis_1
    ports:
      - "6379"
    volumes:
      - redis_1_data:/data
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf
    command: [ "redis-server", "/usr/local/etc/redis/redis.conf" ]
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.2

  redis_2:
    image: 'redis:latest'
    container_name: redis_2
    ports:
      - "6379"
    volumes:
      - redis_2_data:/data
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf
    command: [ "redis-server", "/usr/local/etc/redis/redis.conf" ]
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.3

  redis_3:
    image: 'redis:latest'
    container_name: redis_3
    ports:
      - "6379"
    volumes:
      - redis_3_data:/data
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf
    command: [ "redis-server", "/usr/local/etc/redis/redis.conf" ]
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.4

  redis_4:
    image: 'redis:latest'
    container_name: redis_4
    ports:
      - "6379"
    volumes:
      - redis_4_data:/data
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf
    command: [ "redis-server", "/usr/local/etc/redis/redis.conf" ]
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.5

  redis_5:
    image: 'redis:latest'
    container_name: redis_5
    ports:
      - "6379"
    volumes:
      - redis_5_data:/data
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf
    command: [ "redis-server", "/usr/local/etc/redis/redis.conf" ]
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.6

  redis_6:
    image: 'redis:latest'
    container_name: redis_6
    ports:
      - "6379"
    volumes:
      - redis_6_data:/data
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf
    command: [ "redis-server", "/usr/local/etc/redis/redis.conf" ]
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.7

  # Ephemeral container to create the Redis cluster connections.
  # Once the setup is done, this container shuts down
  # and the cluster can be used by the service app container
  cluster_initiator:
    container_name: cluster_initiator
    build:
      context: redis
      dockerfile: Dockerfile
    tty: true
    depends_on:
      - redis_1
      - redis_2
      - redis_3
      - redis_4
      - redis_5
      - redis_6
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.8

  # Web UI to browse through our Redis data across all nodes
  redis_commander:
    image: rediscommander/redis-commander:latest
    container_name: redis_web
    environment:
      REDIS_HOSTS: "local:redis_1:6379,local:redis_2:6379,local:redis_3:6379"
    ports:
      - "5000:8081"
    depends_on:
      - redis_1
      - redis_2
      - redis_3
      - redis_4
      - redis_5
      - redis_6
      - cluster_initiator
    networks:
      redis_cluster_net:
        ipv4_address: 173.18.0.9

# Rename the default network so we can easily identify it
# Across all containers
networks:
  redis_cluster_net:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 173.18.0.0/16

This is a long one, but here is what this docker-compose.yml does:

Creates a container with our Express application (just for the sake of this demo)
Creates several instances of Redis
- Configure their IP addresses to match the ones used in our entrypoint.sh script
- Copy the redis.conf file so they can act as a cluster
Creates a cluster initiator container that is only necessary for executing our entrypoint.sh script and make the cluster connection
Creates a container with the Redis Commander UI which is a nice Web UI for browsing what is stored in our Redis Cluster

Now that we went through this, let's try this out. Go to your terminal and execute:

docker-compose up

Once everything is ready, you should be able to open your browser and visit localhost:4000. There you have a demo web application I've built where you can enter a key/value pair and save it to Redis and also search for a specific key you have entered before so it can fetch it from Redis and show you the contents on the screen.

If you are wondering how the connection is setup on the JavaScript side, let's have a look at our src/service/redisClient.js file.

const Redis = require('ioredis')

/**
 * Get an existing Redis client instance. Build one if necessary
 * @return {Cluster|null} redis client
 * */
function buildRedisClient() {

  try {
    // cluster URLs should be passed in with the following format:
    // REDIS_CLUSTER_URLS=10.0.0.1:6379,10.0.0.2:6379,10.0.0.3:6379
    const nodes = process.env.REDIS_CLUSTER_URLS.split(',').map(url => {
      const [host, port] = url.split(':')
      return { host, port }
    })

    const client = new Redis.Cluster(nodes, {
      redisOptions: {
        enableAutoPipelining: true,
      },
    })

    client.on('error', error => {
      console.error('Redis Error', error)
    })

    // Redis emits this error when an something 
    // occurs when connecting to a node when using Redis in Cluster mode
    client.on('node error', (error, node) => {
      console.error(`Redis error in node ${node}`, error)
    })

    return client
  } catch (error) {
    console.error('Could not create a Redis cluster client', error)

    return null
  }
}

module.exports = buildRedisClient

This part is very simple. It reads the cluster URLs from the environment and creates an instance of Redis.Cluster using the RedisIO library. From there on we can start issue commands like redis.set, redis.get or redis.exists across our application. Here is how we do that in the demo Express app within this repo:

const buildRedisClient = require('./service/redisClient')
const redis = buildRedisClient()

// Have a look at src/index.js for a complete implementation
app.post('/save-data', async (request, response) => {
  const { key, value } = request.body
  await redis.set(key, value)
  return response.status(201).render('home/index', {
    layout: 'default',
    dataSaved: true,
  })
})

app.post('/search', async (request, response) => {
  const { key } = request.body
  const value = await redis.get(key)
  return response.status(200).render('home/index', {
    layout: 'default',
    value,
  })
})

If you would like to explore the data stored in the cluster, go to localhost:5000 and browse through the Redis Commander UI. There you should be able see all the Master nodes and explore all keys and values.

You will notice that some keys are stored in one Master node and other keys are stored in other nodes. This is the data distribution done by Redis, which provides you load balancing across the cluster.

I hope this Docker setup can help your development workflow the same way it did for me and my team recently. Feel free to DM me via Twitter if you have any questions.

Retrying API Calls with Exponential Backoff in Javascript

Bruno Paulino — Mon, 01 Mar 2021 22:30:28 +0000

Have you ever implemented an integration with a third-party service where you have to call their API endpoints several times a day? Depending on the number of times you call this API, some of those calls will inevitably fail.

One solution to mitigate this problem is to implement a retry algorithm. Here is a sequence diagram showing how this algorithm could look like:

Notice that once our API call fails, our app immediately tries to call it again. That could be extremely fast and there is nothing wrong with that, but that isn't very effective. Why?

Being polite with Exponential Backoff

Lets assume the restaurants API we were trying to call on the chart above is having some trouble. Maybe it's overloaded or is completely down. Retrying to call it immediately after a failed attempt will do no good. It will actually make the situation worse: The restaurants API will be hammered harder and won't have time to recover.

To countermeasure that, we can wait a little before retries. We can actually do better than that. What if on every failed attempt, we exponentially increase the waiting time for the next attempt? Bingo, This is what Exponential Backoff is.

Our app tries to call the Restaurants API.

The API call fails.

Our app waits for 200 millisecods before calling it again.

Our app retries to call the Restaurants API again.

The API call fails again.

Our app waits for 400 millisecods before calling it again.

Our app retries to call the Restaurants API again.

The API call completes successfully.

Here is how the diagram would look like when we implement Exponential Backoff:

How can we do that in Javascript?

The implementation of the algorithm above is actually quite straightforward in Javascript. The implementation below works in Node.js and also in modern browsers, with zero dependencies.

/**
 * Wait for the given milliseconds
 * @param {number} milliseconds The given time to wait
 * @returns {Promise} A fulfiled promise after the given time has passed
 */
function waitFor(milliseconds) {
  return new Promise((resolve) => setTimeout(resolve, milliseconds));
}

/**
 * Execute a promise and retry with exponential backoff
 * based on the maximum retry attempts it can perform
 * @param {Promise} promise promise to be executed
 * @param {function} onRetry callback executed on every retry
 * @param {number} maxRetries The maximum number of retries to be attempted
 * @returns {Promise} The result of the given promise passed in
 */
function retry(promise, onRetry, maxRetries) {
  // Notice that we declare an inner function here
  // so we can encapsulate the retries and don't expose
  // it to the caller. This is also a recursive function
  async function retryWithBackoff(retries) {
    try {
      // Make sure we don't wait on the first attempt
      if (retries > 0) {
        // Here is where the magic happens.
        // on every retry, we exponentially increase the time to wait.
        // Here is how it looks for a `maxRetries` = 4
        // (2 ** 1) * 100 = 200 ms
        // (2 ** 2) * 100 = 400 ms
        // (2 ** 3) * 100 = 800 ms
        const timeToWait = 2 ** retries * 100;
        console.log(`waiting for ${timeToWait}ms...`);
        await waitFor(timeToWait);
      }
      return await promise();
    } catch (e) {
      // only retry if we didn't reach the limit
      // otherwise, let the caller handle the error
      if (retries < maxRetries) {
        onRetry();
        return retryWithBackoff(retries + 1);
      } else {
        console.warn('Max retries reached. Bubbling the error up')
        throw e;
      }
    }
  }

  return retryWithBackoff(0);
}

And here is how you can quickly test this implementation:

/** Fake an API Call that fails for the first 3 attempts
 * and resolves on its fourth attempt.
 */
function generateFailableAPICall() {
  let counter = 0;
  return function () {
    if (counter < 3) {
      counter++;
      return Promise.reject(new Error("Simulated error"));
    } else {
      return Promise.resolve({ status: "ok" });
    }
  };
}

/*** Testing our Retry with Exponential Backoff */
async function test() {
  const apiCall = generateFailableAPICall();
  const result = await retry(
    apiCall,
    () => {
      console.log("onRetry called...");
    },
    4
  );

  console.log("result: ", result);
}

test();

If you want to try this out, here is a Codesanbox link where you can play with it.

How to Create Bulletproof Tickets

Bruno Paulino — Tue, 08 Dec 2020 15:38:14 +0000

It's Monday morning, you just had your first coffee in front of the computer and you open your project management app to start planning your week with your team. You start reading your backlog of tasks and then you see a ticket with the title:

[BUG] Button doesn't respond

You open the ticket and for your astonishment, the description is empty, there are no screenshots, no urls, nada. You can only see that this ticket was created by Joe. You immediately start to think "Ho dear Joe, what did you see? on which page did you see this button? Which button specifically doesn't respond? Was it happening constantly, was it intermittent, was it you who found this issue? Can you reproduce?" So many questions you want to ask Joe, but so little time.

If you have never had a similar situation like I mentioned before while working on a project with multiple people, you can consider yourself the luckiest person on the planet. The truth is, you have to put a good deal of thought and time into creating a great ticket. Reporting a bug or defining a requirement well is a kind of art.

Whenever you are in a position of reporting something in written form, in this case creating a ticket, you have to put yourself in the shoes of the other person that will read and work on it.

Why is creating good tickets so important?

At first sight, it seems like a time consuming task, and to be completely honest, it does take time to create a good ticket. But what we often miss is the time we save by avoiding roundtrips of questions that could have been answered during the ticket creation in the first place. Here are some reasons why creating a meaningful ticket is important:

It saves time: People don't have to run around to gather the information that is already there.
More understanding: A well written ticket helps to give more understanding about the problem that might be hard to track down.
Solid solutions: The more you understand the problem, the better and more reliable the solution will be. And the understanding usually starts by reading the ticket.
Less frustration: Once the context is well detailed and understood, the people that will work on the problem will have less ambiguous questions to ask which will reduce the cognitive load while reasoning about a solution.

You might be thinking "Okay Bruno, but how the heck do I know whether a ticket is good or not?". I'm Glad you asked and this is a super valid question by the way. After dealing with hundreds of tickets along the years, I have got an interesting method that I want to share with you in the next section.

The Method

There is zero scientific evidence to back me up here, but what I noticed was that I could use some small principles to have a well defined method to create good tickets. So based on what we have seen up until this point, here are the steps we can take to create good tickets:

Set the stage: Explain the context and the impact the problem has.
How to reproduce: If the ticket is related to a bug, here you provide detailed information on how to recreate the problem in a consistent way.
Offer Solutions: If you are able to, offer potential solutions for the problem you just found.

In the following sections, I will construct a fictional ticket (but based on real world examples of web projects) so you can have a decent example on how you could apply those steps.

Set the stage

Let's imagine you have just found a bug on the website from the company you work with. Now you need to report the problem and hopefully someone will fix it as quickly as possible. How do you start explaining the problem to someone that you might not even know?

To start things off, you need to give as much information as possible about the context of the bug. And what do I mean by context? Here the important thing is to explain in detail what you expect in a normal case and what the bug introduces. But don't be too verbose on it otherwise you leave a lot of room for ambiguity. Here is an example:

With the introduction of the new product versions, we changed the URLs our customers see on our public website. This causes several problems with external tools that rely on the previous URLs (e.g. Marketing Campaigns).

The basic premises of existing product URLs are:

The customer must have a stable URL for any published product

It should never change for the same product in the eyes of the customer

With an immutable URL none of our marketing campaigns running on our Ad platforms would stop working.

In the example above, we have given a good overview of the problem and also a good reason for the problem to be solved. This is a good starting point for a discussion about the ticket and also helps to prioritize it during planning.

How to Reproduce

Now that we have set up a good context by explaining the problem in detail and why it is important to fix it, it's time to write down the steps to reproduce it. In software development, debugging can be a challenging task and the more clues you have, the easier it gets to find and fix the problem.
One part of the puzzle is to consistently reproduce the problem in a safe environment so it can be monitored, tracked down and fixed. For that to happen, you usually have to define a set of steps that lead to the problem you found. Here is an example following our fictional problem above:

To reproduce the problem, please follow the steps below:

Open an existing product in the admin interface

Open the product preview and write down the current URL

Go back to the admin interface and update the product reference for a new version of the same product

save the changes

Open the product preview again on the website

Compare the new URL with the previous URL you saved

The comparison will result in an URL mismatch.

With the clear steps mentioned above, anyone who gets assigned to work on this ticket will quickly manage to verify the problem and test it as many times as they need.

Sometimes you won't be able to have a consistent way of reproducing the problem and that is fine too, but try to find as many reproducible steps as possible. This will save a good chunk of time for the development team which leads to a faster bug-fix being deployed.

Offer Solutions

The cherry on top, if you have more understanding of the systems you are reporting the bug, is to offer potential solutions for the problem you just found. Developers like challenges, but nobody has infinite time and at the end of the day, we have to produce value for the business, so the quicker a problem can be solved, the better.

in some cases, you might even know exactly what the problem is and how to fix it, so don't spare words into giving a more detailed and technical suggestion at this stage. Here is how I would suggest a solution for our fictional URL problem we have been creating:

It looks like this problem happens at the e-commerce platform level. Since this is a third-party application which we don't have access to the source code, we have to fix this problem on another layer of our system.

A potential solution could be to set rules on our reverse proxy so we keep accepting requests from old URLs and map them to the new ones.
In the meantime, I will also report this problem to our e-commerce provider.

It is clear that in the example above, the author has a deeper understanding of what is happening in the internal systems and that is a big advantage. But if you don't have this level of insight, you can still provide good feedback on how to solve the problem. Any potential solution should be considered, especially if that is coming from someone that understands the problem.

Wrapping up

I have been following those principles for a long time and it actually became quite natural for me while creating a ticket, but I understand that it takes time to build up this understanding.

Sometimes your ticket will still leave room for questions and clarifications, and that is fine too. As long as your ticket was well prepared, even those follow-up questions will be more meaningful and complete, leading to less frustration and a more fluid communication path with your team.

I believe by now you have the superpowers to create bulletproof tickets 🦸🏼‍♀️. Here is the complete ticket we created during this blogpost:

Subject

Product URL breaks after updating product version reference.

Problem

With the introduction of the new Product versions, we changed the URLs our customers see on our public website. This causes several problems with external tools that rely on the previous URLs (e.g. Marketing Campaigns).

The basic premises of existing product URLs are:

The customer must have a stable URL for any published product

It should never change for the same product in the eyes of the customer

With an immutable URL none of our marketing campaigns running on our Ad platforms would stop working.

How to Reproduce

To reproduce the problem, please follow the steps below:

Open an existing product in the admin interface

Open the product preview and write down the current URL

Go back to the admin interface and update the product reference for a new model

Save the changes

Open the product preview on the website

Compare the new URL with the previous URL you saved

The comparison will result in an URL mismatch.

Potential Solution

It looks like this problem happens at the e-commerce platform level. Since this is a third-party application which we don't have access to the source code, we have to fix this problem on another layer of our system.

A potential solution could be to set rules on our reverse proxy so we keep accepting requests from old URLs and map them to the new ones.
In the meantime, I will also report this problem to our e-commerce provider.

DevOps and its impact on Developer Productivity

Bruno Paulino — Sun, 22 Nov 2020 00:12:47 +0000

I have recently finished reading Accelerate: building and Scaling High Performing Technology Organizations to get a more in-depth view into the DevOps landscape and its influence in developer productivity. The book is based on solid research conducted by Dr. Nicole Forsgren, Jez Humble and Gene Kim. The book is an eye-opener for the importance of software delivery performance and the value it brings to any organization that takes it seriously.

This book made me reflect on my experience with DevOps, my own productivity and the productivity of my team. I don’t want to quote every topic mentioned in the book here, but I absolutely recommend you to give it a read. My focus is actually to explore how it relates to my journey adopting DevOps along my career and the benefits it brings.

Shipping code to production and developer confidence

When I started my career, I worked at a company where the deployment process was done by a magician developer that held all the powers. Nobody was allowed to deploy code unless this wizard could cast his spells. The second problem we had was that all engineers knew how to run the application on their local machines but once the rubber hits the road, nobody had a clue about setting up dependencies and building the application for production.

That was a terrible workflow to work with and once during a lucky day, I had no choice but to perform a production deployment by myself. I was feeling scared just thinking about what could go wrong. Having this deployment workflow was a huge blow on the confidence of the engineers in my team, including myself, where not only nobody wanted to be responsible for it, but also not a single person wanted to get involved with it.

Over the years, I started to learn about DevOps and incrementally adopted it wherever I go so I could avoid the bad experience I had in the past. Since then, I have been reaping the benefits of it over and over again. The productivity gain was immense.

Starting with Continuous Integration

To start things off, you want to make your deployment process as predictable and as reproducible as possible. Which means that you have to make sure the work done by a developer can be built, tested and deployed to a safe environment, only then it can be shipped to production. This is called Continuous Integration (CI). Once you define and validate your integration steps for your application stack, be it Java, Node.js or even mobile apps, you must reproduce those steps in code using version control, better yet if you can make this a part of your application repository. As an example, those steps could look like this:

Code is committed by an engineer in a feature branch
A build of the application is triggered. This build is technically production-grade, which means that it has minimal or no difference between development and production, mainly configuration differences (e.g. a sandbox payment gateway where fake payments can be issued), preferably configured via environment variables
A suite of automated tests will be executed on this build
Once all tests pass, the code can be reviewed and merged to the production branch (commonly known as main)

The steps above can be performed by any developer in the team. Once you have a continuous integration pipeline in place, the engineers don’t even have to think about it much since they can be triggered automatically by a continuous integration service like Github Actions or Gitlab CI.

Once you have this process in place, you will have robustness built-in on your development workflow, which will inevitably lead to more confidence with your code, ultimately leading to more productivity.

Nail it down with Continuous Deployment

What if I told you that once code is reviewed and merged to your production branch, this code could be automatically released to production with minimal or no impact to your users? Yes, that is possible. This is called Continuous Deployment (CD). The same thought process applied to continuous integration can be transferred to your deployment workflow, where automated pipelines will make sure your code is pushed to your servers clusters.

Here you can apply the same constraints as before: You want to make sure that every deployment is predictable and reproducible. Any failed steps should leave traces (logs, error messages/code) for further inspection and debug. Here is an example on how it could work for a backend application deployed in a multi-node architecture.

Code is merged into the production branch (Build and tests were previously executed, so the confidence level here is already very high)
Traffic is diverted to specific nodes in your cluster, inactive nodes are updated with the new version of your build. This step is done incrementally for every node, which will result in a zero downtime deployment (or blue/green deployment)
Notification is sent yo your team about a new version deployed. Could be as simple as an email or more sophisticated integrations with your internal chat of choice. (e.g. Slack, Matterost)

Once again, all the steps mentioned above can be executed automatically, with zero manual intervention. Of course, you won’t probably have the full confidence to do it right away, which is totally understandable. But you can start with small steps by automating the process in code and triggering them manually in the beginning. Once the confidence is high enough, this step can be performed automatically for every new code merged.

Once you enable anyone in your team to perform a deployment with confidence, the productivity of your peers will be noticeably better. As a result, you will be delivering value to your customers much faster, most probably much faster than other companies that don’t adopt such practices, which will give an edge on the competition.

Where to go from here

If you are reading about CI and CD for the first time, fear not, you can absolutely do this and adopt such practices. Start with very small actions, I like to call it "start with baby steps". Do you build and test your application manually? Start by automating the build steps in a simple script. Have no automated test suite? Start adding automated tests to critical paths on your app. Those steps will slowly build robustness and resilience into your codebase.

Once you are confident enough with your first scripts, make it executable from a remote service like Github Actions. That is a good start to enable your team to execute the same steps without being concerned with having the right machine or dependency installed.

Wrapping up

DevOps is a very broad topic and we only have covered a very shallow surface here, so there is much more to learn and explore. If you are an engineer and you let the "Ops team handle it", I ask you to look at it differently. You don’t have to become a DevOps specialist, but if you manage to include DevOps on your tool belt, you and your team will be much better off.

There is also a very interesting chapter in the book where specific actions can be taken by managers so software delivery is treated as a "first-class citizen" across your organization. Some actions that I find very interesting and I have personally seen it working:

Use failure as a learning opportunity to improve
Create budgets for continuous learning and training
Space to explore new ideas and share it with others
Let your team use their tool of choice (in other words, don’t force them to write Java if they are high-skilled and productive with JavaScript)

Creating custom React hooks to handle components external events

Bruno Paulino — Sun, 20 Sep 2020 21:16:04 +0000

On a side project this weekend, I had the classic case for a modal implementation. In most of the applications you have to deal with daily, you come to a place where you have to confirm some action or review some changes before pushing the "I am 100% sure about this" button.

This is the perfect case for a modal, a small view that partially covers the screen and presents you with a few options. Most of the time, there will be a button to close the modal away by clicking on the "close" button on the top-right corner. But an even better way to let the user dismiss the modal is to let them click outside of the view in focus, without forcing them to hit the often too small "x" on top.

Here is the live implementation of our modal component we will build during this post. Try it out on our Codesandbox.

For cases like this, you must probably want to watch for clicks or taps outside the main view, in this case, the modal, so you can take the correct action of closing it. But how could you do that in React? one way would be to implement a global click handler in the component, something like this:

import React, { useRef, useEffect } from "react";

export default function Modal({onClose, ...props}) {
  const modalRef = useRef(null);

  useEffect(() => {

    const handleClick = (event) => {
      if (modalRef.current && !modalRef.current.contains(event.target)) {
        // Here you can close your modal.
        // how to close it, that is up to you
        // (e.g. removing components, changing routes)
        // in this case, I am calling a `onClose` function
        // passed down as a prop.
        console.log('Click happened outside. you can close now.')
        onClose()
      }
    }

    // Pointer events are more device agnostic
    // which are able to handle clicks on Desktops and Taps on mobile devices
    // See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/pointerdown_event
    document.addEventListener("pointerdown", handleClick)
    // Once our component unmount or update, we must remove the event listener
    return () => document.removeEventListener("pointerdown", handleClick)

    // Use the modalRef as dependency for the useEffect hook
    // so whenever this reference changes, the listener will update
  }, [modalRef])

  return (
    <div ref={modalRef} className="my-modal">
      <div className="modal-header">
        Super important Action
      </div>
      <div className="modal-body">
        This is an important message. read it carefully.
      </div>
      <div className="modal-footer">
        <button>Cancel</button>
        <button>Ok</button>
      </div>
    </div>
  );
}

But this implementation leaves a lot of room for duplication isn't? If we need to handle a similar case on a different component, we will be doomed to repeat the same click away logic. We can do better than that by leveraging the power of custom React hooks.

Sharing logic with Custom React hooks

In my opinion, hooks are one of the most beautiful features in React. You can compose your components in such a way that gives your application superpowers. React itself leverages the power of hooks with useState, useEffect and a bunch of others.

But we are not limited to the hooks React offers, we can create our own hooks, enabling us to share logic in a very functional way across our app. Lets extract that click away logic from our previous modal component into a custom hook:

import { useEffect, useRef } from "react";

export function useClickAway(ref, onClickAway) {
  // Keep a mutable reference to click away callback
  // and change it every time the component using it changes
  // using 'useRef' here will make sure that we have a mutable
  // and single callback lying around.
  const callbackRef = useRef(onClickAway);
  useEffect(() => {
    callbackRef.current = onClickAway;
  }, [onClickAway]);

  // listen for click events on ref element
  // attaching a handler and calling the callback if necessary
  useEffect(() => {
    const onPointerDown = (event) => {
      if (ref.current && !ref.current.contains(event.target)) {
        callbackRef.current(event);
      }
    };
    document.addEventListener("pointerdown", onPointerDown);
    return () => {
      document.removeEventListener("pointerdown", onPointerDown);
    };
  }, [ref]);
}

lets break our custom hook down.

We start by declaring a plain javascript function called useClickAway. This function takes two arguments. A ref which is a mutable reference to the component we want to watch for clicks "outside" of its boundaries. And a onClickAway callback, which will be executed once we detect a click outside.
We created a ref for the useClickAway callback using the useRef hook. This will make sure that we have only one reference to our useClickAway callback that is captured by our useEffect calls we will use later.
On our first useEffect call, we make sure to keep track of the useClickAway reference. So in case our component updates the useClickAway reference, we also have to update our internal reference inside our custom hook.
On our second useEffect call, this where rubber hits the road. If you pay close attention, this call is exactly the same as we implemented in our modal component. The only difference is that we are calling our callbackRef reference for the onClickAway function instead. This is an extra layer of check to make sure that we are calling the right reference of the callback once a click happens outside of the view.

With that in place, how can we use that in our modal component? Lets see how the code looks like now:

import React, { useRef } from "react";
import { useClickAway } from "./useClickAway";

export default function Modal({ onClose }) {
  const modalRef = useRef(null);

  useClickAway(modalRef, () => {
    onClose();
  });

  return (
    <div className="shadow-overlay">
      <div ref={modalRef} className="my-modal">
        <div className="modal-header">Super important Action</div>
        <div className="modal-body">
          This is an important message. read it carefully.
        </div>
        <div className="modal-footer">
          <button onClick={onClose}>Cancel</button>
          <button>Ok</button>
        </div>
      </div>
    </div>
  );
}

Can you notice how clean our modal component looks now? Better yet, we can reuse that same logic across our app just by reusing the useClickAway hook. Isn't that cool?

Here is the link to the Codesandbox demo we built on this blogpost. Feel free to copy and use it on your apps.

Hardening your server security with Fail2Ban

Bruno Paulino — Wed, 01 Jul 2020 15:34:58 +0000

I was recently checking the access logs from some linux servers I maintain and I was very surprised by the ssh login attempts those servers were facing. My servers have password access disabled by default, so only previously registered ssh keys are allowed to login. But even then, the amount of login attempts was disturbing. Around 500 attempts a day. I had to do something about it.

Talking to my coworkers about it, one of them suggested a tool called Fail2Ban. It runs a background service that monitors the log files on your server and based on suspicious activities, like unsuccessful login attempts, it blocks access from those bad actors by updating firewall rules to reject any connection for their IP addresses.

My first thought was "I should be careful because I could ban myself and lose access to my server permanently". So I started the installation process very carefully. Fortunately, the default configuration only blocks the IP access for 10 minutes, so worst case I would have a few minutes to have coffee. I also started the process in a "trashable" server, so if something goes wrong, I could just throw it away and start anew.

We will customize those settings for a more robust strategy later on here on this post.

Installing Fail2Ban

Let's get started. The first step is to install Fail2Ban on your server (Ubuntu):

# Update dependencies
apt update && apt upgrade -y

# install fail2ban
apt install fail2ban

Fail2Ban comes with a pretty solid default configuration, but since our goal is to customize it to our needs, they recommend us to copy the default configuration file with the .local extension. The reason for this is that if we update Fail2Ban, the original configuration file will get changed and we will lose our custom configuration.

Put those bad guys in jail

The configuration files are located at /etc/fail2ban, so lets go ahead and create a local copy of those files:

# Copy fail2ban default configuration
cp /etc/fail2ban/fail2ban.conf /etc/fail2ban/fail2ban.local
# Copy fail2ban jail configuration
cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

Fail2Ban uses the concept of jails to monitor specific services like nginx, ssh, apache and so on. Each jail specifies a configuration for a specific application or service running on your server. By default, the sshd jail is active.

Activating Fail2Ban

Now that we have Fail2Ban installed and pre-configured by default, lets start the service:

systemctl start fail2ban

As soon as you start Fail2Ban, you might already see some bad guys blocked. First lets check which jails are active with the following command:

fail2ban-client status
# You should see something like this as output:
Status
|- Number of jail:  2
`- Jail list: sshd

Ok, so we have Fail2Ban up and running, lets check the sshd jail with the following command:

fail2ban-client status sshd
# You should see something like this as output
Status for the jail: sshd
|- Filter
|  |- Currently failed: 10
|  |- Total failed: 511
|  `- File list:    /var/log/auth.log
`- Actions
   |- Currently banned: 9
   |- Total banned: 77
   `- Banned IP list:   218.255.86.106 222.186.31.83 85.209.48.228 180.166.184.66 218.92.0.220 109.255.185.65 150.158.178.137 111.231.132.94 66.70.130.149

In my case, I could immediately see the benefit of Fail2Ban. after a few minutes, I had already several IP addresses banned.

Lets lookup our IP table to see if those IP addresses match with the following command:

iptables -n -L
# You should see something like this as output
Chain f2b-sshd (1 references)
target     prot opt source               destination         
REJECT     all  --  103.100.211.72       0.0.0.0/0            reject-with icmp-port-unreachable
REJECT     all  --  66.70.130.149        0.0.0.0/0            reject-with icmp-port-unreachable
REJECT     all  --  111.231.132.94       0.0.0.0/0            reject-with icmp-port-unreachable
REJECT     all  --  150.158.178.137      0.0.0.0/0            reject-with icmp-port-unreachable
REJECT     all  --  109.255.185.65       0.0.0.0/0            reject-with icmp-port-unreachable

That is great. Fail2Ban is updating our IP filter rules which will prevent connections from those bad actors.

Changing the defaults

The default configuration blocks those IP addresses for 600 seconds (10 minutes). This is a pretty good start, but we can do better. Ideally, if some of those IP addresses are attempting to connect every 10 minutes, we could block them for a greater timespan or even permanently.

One thing to consider is that if we block IPs permanently, we can potentially increase our IP table lookup time, which means that connecting to our server can become very slow since this list of blocked IPs can grow indefinitely.

To help us with that, Fail2Ban comes with recidive which is a jail for its own logs. It works like that:

It looks into Fail2Ban own logs for banned IP addresses from other jails.
If those IP addresses are found in the logs more than 5 times in the current day, it blocks them for 1 week.

That sounds like a good strategy. Our IP table won't grow very large (in theory) because in 1 week it will rollback and allow those IP addresses to connect again. If they act in bad faith again, they will be blocked and the cycle repeats.

So let's go ahead and activate recidive. Edit the file /etc/fail2ban/jail.local (I am using nano, but feel free to use a different text editor). Look for the following code:

# Jail for more extended banning of persistent abusers
# !!! WARNINGS !!!
# 1. Make sure that your loglevel specified in fail2ban.conf/.local
#    is not at DEBUG level -- which might then cause fail2ban to fall into
#    an infinite loop constantly feeding itself with non-informative lines
# 2. Increase dbpurgeage defined in fail2ban.conf to e.g. 648000 (7.5 days)
#    to maintain entries for failed logins for sufficient amount of time
[recidive]

logpath  = /var/log/fail2ban.log
banaction = %(banaction_allports)s
bantime  = 1w
findtime = 1d

Notice that the configuration is already in place. We only need to activate it:

# ... comments
[recidive]
# Include the next line to enable recidive
enabled = true
logpath  = /var/log/fail2ban.log
banaction = %(banaction_allports)s
bantime  = 1w
findtime = 1d

Now we only need to restart the Fail2Ban service with:

systemctl restart fail2ban

Let's check our fail2ban status to see which jails are running after our update:

fail2ban-client status
# You should see something like this as output
Status
|- Number of jail:  2
`- Jail list:   recidive, sshd

Now that recidive is active, You can check if some IP addresses were banned for the whole week:

fail2ban-client status recidive
# You should see something like this as output
Status for the jail: recidive
|- Filter
|  |- Currently failed: 25
|  |- Total failed: 90
|  `- File list:    /var/log/fail2ban.log
`- Actions
   |- Currently banned: 10
   |- Total banned: 10
   `- Banned IP list:   129.226.114.97 103.246.240.26 142.93.60.53 167.172.163.162 109.255.185.65 150.158.178.137 66.70.130.149 180.166.184.66 64.225.35.135 218.255.86.106

Now we have Fail2Ban monitoring our SSH access and fully configured.

What to do if I block myself

You should be very careful with your server access from now on. Make sure that you have access from your computer and I highly recommend disabling password access.

You can wait the default 10 minutes or you can access from a different IP address (like routing your mobile phone) and remove your IP address from the blocklist with the following command:

fail2ban-client set jailname unbanip [IP_ADDRESS_HERE]
# Here is how it could look like for you:
fail2ban-client set sshd unbanip 103.1.1.103

Where to go from here

Fail2Ban is quite extensive and supports many different kinds of extensions like your own custom jails. The good thing is that amazing people around the world like to share their experience as well, so if you want to setup Fail2Ban for a different service like nginx, Digital Ocean has a great tutorial about it with a step-by-step guide.

You can also read more about it on the Fail2Ban official page

Dockerizing React Apps

Bruno Paulino — Tue, 03 Mar 2020 06:52:33 +0000

While creating ReactJS apps, you probably don't have to think too much about how to deploy them. ReactJS applications can be easily bundled in a folder, consisting of plain HTML, CSS and Javascript files. That should be simple enough to upload it to a S3 Bucket, host it on Github Pages or even integrating great services like Netlify or Zeit for fast and automated deployments.

But this week, I had the task of deploying a React app created with create-react-app on a VPS under a subdomain. I didn't want to use stone-age FTP, I wanted to have an automated docker container with my app where I could deploy anywhere without much configuration.

I created a demo app with all the configurations detailed on this post. The code is available here

Preparing our Dockerfile

We start out by creating a Dockerfile on our project root folder with the following content:

# This image won't be shipped with our final container
# we only use it to compile our app.
FROM node:12.2.0-alpine as build
ENV PATH /app/node_modules/.bin:$PATH
WORKDIR /app
COPY . /app
RUN npm install
RUN npm run build

# production image using nginx and including our
# compiled app only. This is called multi-stage builds
FROM nginx:1.16.0-alpine
COPY --from=build /app/build /usr/share/nginx/html
RUN rm /etc/nginx/conf.d/default.conf
COPY nginx/nginx.conf /etc/nginx/conf.d
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

On the snippet of code above, we are using a feature called multi-stage builds. It requires Docker 17.05 or higher, but the benefit of this feature is enormous, which I will explain next. On the first half of the script, we are building a Docker image based on node:12.2.0-alpine which is a very tiny linux image with node included. Now notice the as build at the end of the first line. This creates an intermediary image with our dependencies that can be thrown away after build. Soon after that, we install all the dependencies from my React app with npm install and later we execute npm run build to compile the React app optimized for production.

On the second half of the code, we create a new Docker image based on nginx:1.16.0-alpine which is also a tiny linux including nginx, a high performance web server to serve our React app. We use the command COPY to extract the content from our previous image called build and copy it into /usr/share/nginx/html. Next, we remove the default nginx configuration file and add our custom configuration under nginx/nginx.conf with the following content:

# To support react-router, we must configure nginx
# to route the user to the index.html file for all initial requests
# e.g. landing on /users/1 should render index.html
# then React takes care of mouting the correct routes
server {

  listen 80;

  location / {
    root   /usr/share/nginx/html;
    index  index.html index.htm;
    try_files $uri $uri/ /index.html;
  }

  error_page   500 502 503 504  /50x.html;

  location = /50x.html {
    root   /usr/share/nginx/html;
  }

}

This configuration is very important for apps using React Router. Whenever you share a link to your React app, lets say, a link to /users/1/profile, this link tells the browser to request this path from the web server. If the web server is not configured properly, our React app won't be able to render the initial index.html file containing our React application.

Using our custom configuration, we tell nginx to route all requests to the root folder /usr/share/nginx/html which is the directory we previously copied our React app during image build. We should not forget that React apps are Single Page Applications, which means that there is only one page to be rendered on the first request, the rest of the job is taken care by React on the browser.

Building our Docker Image

We already have all the required code to build our Docker image. Lets execute the Docker command to build it:

# Make sure to be on the same folder of your React app
# replace 'my-react-app' with whatever name you find appropriate
# this is the image tag you will push to your Docker registry
docker build -t my-react-app .

When the image is built, lets check the size of the image we just generated with the following command:

# List all the images on your machine
docker images
# You should see something like this:
REPOSITORY     TAG       IMAGE ID        CREATED          SIZE
my-react-app   latest    c35c322d4c37    20 seconds ago   22.5MB

Alright, our Docker image is ready to go on to a Docker Registry somewhere. One interesting thing about this image is that the size is only 22.5MB. This is really great for deployment because small images make automated pipelines run much faster during download, image building and upload.

Running our React app with docker-compose

What we need now is a way to run this Docker image. For testing it locally, lets create a file called docker-compose.yml with the following content:

version: '3.7'

services:
  my_react_app:
    build:
      context: .
    ports:
      - '8000:80'

Docker Compose will take care of building the image in case it doesn't exist and also bind the port 8000 from our local machine to the port 80 on the container.

Lets spin up our container with the following command:

docker-compose up

Now open your browser on localhost:8000 and check if our React app is running there. You should see something like this:

Conclusion

Running a React app with Docker might not be the best deployment, but if you need to run docker like in my case, it can be very simple and effective. This opens the door for a lot of automation pipelines you can hook up on the project like Github Actions or Gitlab CI/CD to automate your deployment process. You can find the code of this post here.

Rapid Prototyping with GatsbyJS

Bruno Paulino — Sat, 29 Feb 2020 13:19:42 +0000

On February 17th, I gave a talk at the React Vienna Meetup about this topic and I thought writing a blogpost about could benefit some folks that either couldn't make it or are living somewhere else around the globe. You can find my slides here.

I would like to start off with a question. What if you want to put together a website with the most modern web tech out there? You probably need to know a bunch of things to start a simple website. Do you want to use modern Javascript syntax? no problem, just use Webpack and Babel to help you transpile your code. Do you want to put your website online? just configure an small box on Digital Ocean, add Nginx and your website is online. Do you want to write blogposts and publish them using a CMS? No problem, just implement your backend, maybe using Postgres as a database. This list goes on and on if you try to start with a modern tool chain.

To get this whole setup done, and most importantly, correctly configured, can be hard. It is even worse if you are a beginner.

Static site generators come to the rescue

So you realize that this is an enormous amount of tools (and knowledge) you need to know upfront to start with a simple website. That is really overwhelming. This is where static site generators really shine. There is usually minimal to none configuration you have to do, there are many templates you can use to start with and most of the configuration thing is done for you. Some cool static site generators are:

The most interesting one that caught my attention lately was GatsbyJS. I have been working with React for the past 3 years and finding a decent static site generator based on React was very interesting. Right from the start, it solves all the problems I mentioned before. You don't have to configure anything to start. You only need the minimal tools installed like a good text editor and node.js. There is also no need to have a server for hosting. It generates all the pages statically, which means that when you bundle your website, you have one HTML file for each page of your website, just like the web is supposed to work. And simple enough, you can just upload those files to a static site hosting provider like netlify or even use Github Pages to host it for free.

Gatsby has an incredible feature that sets it apart from other generators: Your datasource doesn't have to be statically located within the code, like markdown files. It can be pulled from a remote datasource, like a headless CMS, before generating the pages.

That is a big deal if you want the freedom of publishing blogposts from a nice CMS or you have a team of content creators that are simultaneously creating content. Their don't have to be developers to be able to create a blog post, and Gatsby enables exactly that.

Our little experiment

At woom we are modernizing our tech stack. One interesting project we had was to rebuild our blog frontend, but in a way that we don't get stuck at a specific platform like we had before (using our ERP). As the main engineer responsible for this project, I decided to give Gatsby a try. I was impressed with the development speed we had using it to implement our blog prototype. We ended up using Hubspot as our CMS since we are using it for other marketing purposes, but the frontend is still portable if we decide to shift to a new CMS. You can take a look at our blog here.

This is how it looks like after we got it done:

But what are the main advantages of Gatsby anyway? What really made us to look at it differently?

It uses React

If you never heard of React before, it is the state-of-the-art of frontend libraries. Writing frontend with React requires a different approach, but it definitely pays off. It lets you break your application into reusable components, which makes it infinitely simpler to reason about it and debug.

React hooks.

Even though Gatsby generates static pages, you can still benefit from React state management. hooks like useState and useContext are still there to help us have a more dynamic page.

GraphQL included

Using the built-in GraphQL API, you can pull data from a remote datasource, process static files from your local repository, like lets say images and transform them to alternative resolutions for different device sizes and so on.

Development and Production configuration out-of-the-box.

You don't have to hassle around Webpack configurations, pipelines or anything like this. The basics, which is already what you need to start, is already there, properly configured and ready to row with the single command yarn develop during development and yarn build to deploy a new build.

Rich plugin ecosystem

When looking for a framework, you usually have to consider how flexible it can be, so you can benefit from the community, using code extensions and plugins. Gatsby has a very rich plugin ecosystem, and the most important ones, like gatsby-image for image processing are already there, provided and maintained by Gatsby directly, which is a good sign that will be kept up2date.

Lets try to build something

For this ~~talk~~ blogpost, I created a little demo. This is a website with a blog section. The blogposts come from the headless CMS Storyblok.. You can find the source code of this demo here.

Clone the demo repo and execute the following commands:

# Clone the repo
git clone git@github.com:brunojppb/gatsby-minimal-blog.git
# Now lets go to our newly created project
cd gatsby-minimal-blog
# install all dependencies
yarn install
# and fire up the dev server
yarn develop

Now lets go to our browser and type in localhost:8000 to see what happens.
You will see a nice and bare-minimum website, very similar to the screenshot I posted above, but with a link to the blog section of the website.

If you take a look at the terminal, you will see that there was an error with a plugin. something like failed createPages - 0.193s. This is because when we hit yarn develop Gatsby kicks in and try to fetch our posts from Storyblok. But since you don't have an account there yet, it can't find out your API token to access your blogposts. So go ahead and open Storyblok to create your account and select the demo.

After signing in, you will that there is a demo space created for you. Don't get bogged down with the details, Lets just try to create content there. On the left-hand side, click on Content, inside content, you will see a list of different assets. You have to delete all of them, but leave Blog Articles. Now select Blog Articles.

You will see a list of different contents, select all of them and delete it. We will create a new article from scratch.
On the top-right corner, select "+Entry". You will be asked to enter a title. On the content type dialog, select article and hit create. After this screen, you will land on a CMS-like page where you can write on the right-hand side menu and see it live rendering on the left-hand side. Try it out, update the title field and write something into the long text dialog. When you are happy with it, just hit publish on the top-right corner.

Now lets get the API Key to access our content. To to settings -> API-Keys. There you have an API token called public. copy it to your clipboard. Now head back to your text editor and create a file called .env.development on your project root folder. and inside of it, add your API token in the following pattern:

CMS_API_TOKEN=YOUR_API_TOKEN_HERE

After that, restart your development server. Go to your browser and click on Visit our blog section. You should see your recently created article there. You can click on it and to directly to the article page. But what happened there? Lets take a look at the a file called gatsby-node.js:

const axios = require('axios');
const marked = require('marked');

exports.createPages = async({actions: {createPage}}) => {

  const url = `https://api.storyblok.com/v1/cdn/stories`;
  const articles = await axios.get(url, { 
    params: {
      token: process.env.CMS_API_TOKEN,
      'space.version': new Date().getTime(),
    }
  });

  // Create articles list page
  createPage({
    path: '/articles',
    component: require.resolve('./src/templates/all_articles.js'),
    context: {
      articles: articles.data.stories
    }
  });

  // create each individual article page
  articles.data.stories.forEach(article => {
    createPage({
      path: `/article/${article.slug}/`,
      component: require.resolve("./src/templates/article.js"),
      context: { 
        article: {
          ...article,
          content: {
            ...article.content,
            // Don't do this at home :)
            // You need to sanitize this HTML first
            long_text: marked(article.content.long_text)
          }
        }
       },
    })
  })

}

This is a lifecycle script executed by Gatsby during build time. What this script does is:

fetch all articles from Storyblok
create an index page with all the articles so you have a complete list
create individual pages with each article

If you look into src/templates/all_article.js you will see:

import React from 'react';
import { Link } from 'gatsby';
import Layout from '../components/layout';

export default function AllArticles({pageContext: {articles}}) {

  return (
    <Layout>
    <div className="article-list">
      {
        articles.map(article => (
          <div key={article.uuid}>
            <Link to={`/article/${article.slug}`}>
              {article.content.title}
            </Link>
          </div>
        ))
      }
    </div>
    </Layout>
  );

}

The AllArticles component follows a pattern imposed by Gatsby. It must receive a prop called pageContext. This necessary for Gatsby to inject the content at build-time and render the component to generate the static pages. If you follow the convention, you get all this magic for free.

The same thing happens to the Article component. it expects a pageContext prop and from there on, you can create your React component in the same way.

Next Steps

This example was very naive and simplistic, but you can already have a feeling of what Gatsby can do. If you are considering to develop a new website and don't want to waste your time with tooling configuration, give Gatsby a try. It will be probably worth it.

We are now evaluating if makes sense or not to build out Shop frontend with it in a way that supports multi-language. I got some interesting feedback from folks using Gatsby in production during my React Vienna talk that will definitely help to try it out.

Automating your work with Github Actions

Bruno Paulino — Sat, 02 Nov 2019 14:04:08 +0000

I have finally joined the Github Actions beta program and figured why not play with it for a bit and see what I can do. So my first idea was to automate the deployment process of my blog, this one you are currently reading. I am currently using Jekyll as my static site generator. It works flawless for what I need. I just write whatever I want using Markdown and Jekyll digests everything inside my source folder and spits out HTML, CSS and JS files in a "ready-to-publish" folder where I can just upload to the cloud.

I am currently using Github Pages to host my blog and it has been working perfectly fine for the past couple years.

But how does a Github Action work anyway?

Github Actions is a way to perform tasks automatically for you. To give you an example, I will use my blog workflow.

It all starts when I want to write a new post. I just create a new markdown file, write down whatever is on my head and save it. After this whole process, I need a way to transform my text in a website. Jekyll is doing the heavy-lifting for me, so I just go to my terminal and type:

# This command will generate my entire website and all its dependencies
jekyll build

After generating all the necessary files, I need to upload it somewhere. In this case, I just have to commit my changes to a specific branch called gh-pages and Github will serve my site on the web. For doing that, I usually perform the following commands in a bash script:

# This is the folder Jekyll generates with my website. Lets just open it
cd _site
# Now we need a new git repository here, 
# so I can commit only the generated files and skip the source files
git init
git config user.name "Bruno Paulino"
git config user.email "bruno@bpaulino.com"
git add .
# That will create a nice commit message with something like: 
# New Build - Fri Sep 6 12:32:22 UTC 2019
git commit -m "New Build - $(date)"
# Now lets push my commit to the gh-pages branch and replace everything there
REPO=https://brunojppb@github.com/brunojppb.github.io.git
git push --force $REPO master:gh-pages
# Lets do some cleanup here since we don't need the generated files anymore
rm -fr .git
cd ..
rm -rf _site

That is pretty simple right? It is indeed, but how cool would that be if Github could do that for me instead? That is where Github Actions come to give us a hand.

It all starts with a folder on your repository called .github/workflows.

inside of this folder, create a file called deploy-workflow.yml with the content below. Each line will be explained with a comment:

deploy-workflow.yml

# This is the name of our workflow.
# Github will show it on its Website UI
name: deploy
# This configures our workflow to be triggered
# only when we push to the master branch
on:
  push:
    branches:
      - master

# Here is where we define our jobs. 
# Which means the tasks we want Github to execute
jobs:
  build:
    name: deploy
    # Here we specify in whith OS we want it to run
    runs-on: ubuntu-18.04
    # Now we define which actions will take place.
    # One after another
    steps:
      # This is the first action. It will make sure that we have
      # all the necessary files from our repo, including our custom actions
      # This action here is actually from a remote repo available from Githup itself
      - uses: actions/checkout@v1 
      # This is our custom action. Here is where we will define our git commands
      # to push our website updates to the `gh-pages` branch.
      # Notice that we are specifying the path to the action here.
      # We will create those files in a sec
      - uses: ./.github/actions/build-dist-site
        env:
          # Now make sure you add this environment variable.
          # This token will allow us to push to github directly
          # without having to type in our password.
          # The GITHUB_TOKEN is available by default
          GITHUB_TOKEN: {{ "${{ secrets.GITHUB_TOKEN"}} }}

Now lets create our custom action. Github Actions are divided in 2 types:

Docker container
Javascript

We are running our action using a Docker Container. Using Docker, we make sure the environment where our scripts are running will be the same, no matter what happens to the Github environment. So, lets dig deeper and create our actions folder under .github.

# build-dist-site will be the folder for holding
# our action configuration (Dockerfile, scripts and Metadata)
mkdir -p .github/actions/build-dist-site

Under .github/actions/build-dist-site lets create 3 files:

action.yml: It will hold the metadata of our action
Dockerfile: Will specify our Docker image to run Jekyll in a container
entrypoint.sh: Will have our custom scripts to generate and deploy our website update

Dockerfile

# Our Docker image will be based on ruby:2-slim
# it is a very light docker image.
FROM ruby:2-slim
LABEL author="Bruno Paulino"
LABEL version="1.0.0"

# Lets install all dependencies
# including git and Bundler 2.0.2
ENV BUNDLER_VERSION 2.0.2
RUN apt-get update && \
    apt-get install --no-install-recommends -y \
        bats \
        build-essential \
        ca-certificates \
        curl \
        libffi6 \
        make \
        shellcheck \
        libffi6 \
        git-all \
    && gem install bundler:2.0.2 \
    && bundle config --global silence_root_warning 1

# This is our entrypoint to our custom scripts
# more about that in a sec
COPY entrypoint.sh /

# Use the entrypoint.sh file as the container entrypoint
# when Github executes our Docker container
ENTRYPOINT ["sh", "/entrypoint.sh"]

Now that we have our Dockerfile ready, we need to tell Github to use it. That is why we need the action.yml file.

action.yml

# Ok, here the keys are pretty much self explanatory :)
name: 'Deploy new version'
description: 'Setup Ruby env and build new site version'
author: 'Bruno Paulino'
runs:
  using: 'docker'
  image: 'Dockerfile'

The action.yml file tells Github what to do. In this case, just tell it to use Docker and use our Dockerfile to build the container with it.

Now we just need our entrypoint.sh script to execute our website generation and deployment. Lets get our hands dirty with a bit of bash script:

entrypoint.sh

#!/bin/bash
# Exit immediately if a pipeline returns a non-zero status.
set -e

echo "🚀 Starting deployment action"

# Here we are using the variables
# - GITHUB_ACTOR: It is already made available for us by Github. It is the username of whom triggered the action
# - GITHUB_TOKEN: That one was intentionally injected by us in our workflow file.
# Creating the repository URL in this way will allow us to `git push` without providing a password
# All thanks to the GITHUB_TOKEN that will grant us access to the repository
REMOTE_REPO="https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"

# We need to clone the repo here.
# Remember, our Docker container is practically pristine at this point
git clone $REMOTE_REPO repo
cd repo

# Install all of our dependencies inside the container
# based on the git repository Gemfile
echo "⚡️ Installing project dependencies..."
bundle install

# Build the website using Jekyll
echo "🏋️ Building website..."
JEKYLL_ENV=production bundle exec jekyll build
echo "Jekyll build done"

# Now lets go to the generated folder by Jekyll
# and perform everything else from there
cd _site

echo "☁️ Publishing website"

# We don't need the README.md file on this branch
rm -f README.md

# Now we init a new git repository inside _site
# So we can perform a commit
git init
git config user.name "${GITHUB_ACTOR}"
git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
git add .
# That will create a nice commit message with something like: 
# Github Actions - Fri Sep 6 12:32:22 UTC 2019
git commit -m "Github Actions - $(date)"
echo "Build branch ready to go. Pushing to Github..."
# Force push this update to our gh-pages
git push --force $REMOTE_REPO master:gh-pages
# Now everything is ready.
# Lets just be a good citizen and clean-up after ourselves
rm -fr .git
cd ..
rm -rf repo
echo "🎉 New version deployed 🎊"

🤯 That was a lot different from what I started with right? Ok, the reason for that is just Docker. Now we have a more robust implementation of our deployment pipeline where we could even move away from Github to Gitlab and reuse the Dockerfile and entrypoint.sh (with minor changes).

Now that we are armed with those files, lets commit our changes and push to Github and see what happens. Going to our Github repository page, there you can see a new button called Actions:

Lets click on it. You will be taken to the Workflows list. There we see our Deploy workflow we just created.

Now inside of our workflow execution context, we can see all of our actions being executed:

Ok, now our automation work was fully done. As a cherry on top, you can also add a badge to your README.md file showing the current status of your custom actions like that:

# Where /deploy/ must be replaced with your workflow name
![workflow-badge](https://github.com/brunojppb/brunojppb.github.io/workflows/deploy/badge.svg)

That will render a nice image by Github on your repository page with the current action status.

Now I can enjoy my time spent building and deploying my website doing something else like playing videogames 🎮 or drawing 🎨. Here is the open-source repository of my blog if you want to take a look:
https://github.com/brunojppb/brunojppb.github.io