DEV Community: Domenico Luciani

How to create an always up to date alias for your Mastodon account

Domenico Luciani — Sat, 19 Nov 2022 08:00:00 +0000

Mastodon is a new hot-trend topic, so I spent some time trying to wrap my head around it.

The decentralisation is an exciting part of Mastodon; if tomorrow I don’t like the instance where my account resides anymore, I can always switch to another instance and bring all my data seamlessly. It’s fantastic, except that now it’s like having another account with a different address, so I need to share it with my “audience” again and again.

Doing some research, I discover how to create a custom alias for my Mastodon account to have it always pointing to my current account; let’s see how!

How is it look like?

The alias I created for my account is dlion@domenicoluciani.com where dlion is my nickname, and domenicoluciani.com is my custom domain.

If you try to search it on Mastodon, you will find my current account, which resides on mastodon.social

Behind the scene

I discovered that Mastodon uses ActivityPub to communicate between different actors and that those actors are found using WebFinger, a way to attach information to a specific email address or other online resources.

So I just needed to implement the WebFinger spec on my domain to have it working.

On your Mastodon instance, you have an endpoint called .well-known/webfinger, which accepts a query parameter that allows other Mastodon instances to get information around a particular account.

<youmastodonaddress>/.well-known/webfinger?resource=acct:<yournick>@<youmastodonaddress>

For instance, in my case, doing a curl GET request to this URL:

https://mastodon.social/.well-known/webfinger?resource=acct:dlion@mastodon.social

I get the WebFinger response for my account:

{
   "aliases" : [
      "https://mastodon.social/@dlion",
      "https://mastodon.social/users/dlion"
   ],
   "links" : [
      {
         "href" : "https://mastodon.social/@dlion",
         "rel" : "http://webfinger.net/rel/profile-page",
         "type" : "text/html"
      },
      {
         "href" : "https://mastodon.social/users/dlion",
         "rel" : "self",
         "type" : "application/activity+json"
      },
      {
         "rel" : "http://ostatus.org/schema/1.0/subscribe",
         "template" : "https://mastodon.social/authorize_interaction?uri={uri}"
      }
   ],
   "subject" : "acct:dlion@mastodon.social"
}

I need to put this response on my server under the same directory and inside the same file and that’s it.

How to do it on a Jekyll website

For my blog, I use GitHub for the hosting; specifically, I use github-pages which means using Jekyll, a static site generator.

To have your Mastodon alias in your custom domain using Jekyll, you need to:

In the root of your repo, create a directory called .well-known.
Inside the directory .well-known, create a new file called webfinger.
Inside the webfinger file, put the response you get when you curl your actual Mastodon instance WebFinger endpoint, as mentioned before.
In your _config.yml, add include: ["/.well-known"] to include that directory in your rendering.

And it’s done. Just push and wait a bunch of minutes. Your alias will be founded as anything@your-custom-domain.whatever by Mastodon, redirecting everyone to your actual account.

References

If you want to know more about WebFinger, you can have a look at the original website of the spec and at the Mastodon’s documentation:

I found out about this method thanks to this article by Maarten Balliauw:

https://blog.maartenballiauw.be/post/2022/11/05/mastodon-own-donain-without-hosting-server.html

Misleading Pair Programming

Domenico Luciani — Fri, 22 Jul 2022 08:00:00 +0000

I often read tweets, threads and posts full of complaints about this weird practice called Pair Programming , frequently due to a lack of understanding and wrong implementation.

Today I’d like to spend some time clarifying why those complaints are misleading and why you should keep doing pair programming.

It’s tiring!

Do you use pair programming? How do you do it?

It often feels like a more tiring way to move slower to me. Great for solving gnarly bugs together, but not for coding.

— Swizec Teller encouraging you to Be An Expert (@Swizec) February 22, 2021

I heard people complaining that 8 hours of pair programming are a nightmare. It is ruining their life, draining all their mental energies, and making them brainless at the end of the day. Let me tell you a thing, and I want to make it clear:

If you are doing 8 hours of straight pair programming, you are doing it wrong!

Take breaks!

Pair programming is a powerful and brain energy-consuming activity; therefore, having breaks IS KEY.

One technique I like is the Pomodoro.

Essentially it forces you to have breaks every 25 minutes of straight pair programming. The break usually lasts 5 minutes whenever you shouldn’t do anything related to that specific task.

Of course, you can be flexible according to your needs, but you shouldn’t push too hard on that limit. Taking breaks is part of this activity; you and your pair should have it as frequently as possible. It’s essential to have breaks and rest. Please do it.

It’s slow!

Another false assumption is that pairing slows you down.

Why have two people on the same task when you can have two people on two different tasks and speed up the development?

It seems a fair statement, but it doesn’t take into consideration the result of doing that, let’s explore a few of them:

Code Reviews

Doing code reviews is a common practice. Once you are done with your story, another (or more than just one) person has to review and accept your code to be merged.

What are the pitfalls of this practice?

Lack of context : the person reviewing your code doesn’t have the same context as you, it will lead to possible misunderstanding or long debates due to this deficiency, delaying the integration and having a longer feedback loop.
It requires another person’s availability : waiting for another person to review your code leads to a significant delay creating a bottleneck within the team.
Context Switch : the other person probably is busy doing something else, like working on a different task. That person, just for unblocking you, has to do a context switch, review your code and then get back to the task by doing another context switch again. It has been proved that doing context switching often leads to spending lots of time restoring concentration and getting back on track.
Fake Code Reviews : Reading others’ code is complex, and it requires concentration, especially without the context becoming time-consuming, so what do usually people do? Read quickly through the code, acting like a linter or a compiler. It is like doing a fake code review. It doesn’t add any value; it can lead to side problems in the codebase and give the team a fake feeling of security. It often happens, especially when the team is in a rush due to imposed deadlines or constraints.

Bus Factor and Collective Ownership

Working alone on a task is cool until the rest of the team needs to know what you have done and how but you are not available.

Handing over your knowledge around that task will require spending some time with the team explaining to them the code you have written, giving them the context and the choices you have made, and hoping they get it quickly. It could involve having different sessions with different people, drawing flows and having multiple discussions.

All the things you can mitigate by having another person pair with you.

In that scenario, two people are getting the same knowledge around a specific task; frequently rotating helps to spread this knowledge increasing the collective ownership of the codebase.

Are you off tomorrow? No worries, you are covered by another person who knows what you know without the need to wait for you to be back.

Sometimes I don’t think that pairing is a good idea!

Then don’t do it!

Pairing is a valuable activity with multiple benefits, but it has to be used whenever it has sense; otherwise, it’s just another practice you follow because of some “rules” written somewhere that someone is telling you to respect.

If you see a task that doesn’t require pairing, then you can just go ahead and do it by yourself. It is okay to have a sole moment, and it’s up to you to decide whether or not to pair with someone else.

Remotely is harder!

True, remote pairing is more complicated than pairing physically, and it is a fact. However, nowadays, we have some tools, precautions and equipment to overcome this situation as much as possible.

Slow internet connection : Be ensure to have an internet connection that can support your pairing activities seamlessly. Without a good internet connection, the whole pairing activity will degrade, and it is no longer working anymore.
High-quality audio channel : pairing forces you to communicate as much as possible. It’s about sharing your thoughts; it’s about having discussions and telling what you will do while driving. During the pairing sessions, properly communicating is key. Having a good headset with a good microphone (with noise reductions, for example) will allow you to not bother your pair with annoying noises and, on the other hand, to have a smooth call listening to your colleague seamlessly.
High-quality camera : The body language is an essential part of the pairing session; it allows you to understand what the other person thinks (even unconsciously) and whether that person is following you or not. It will enable you to have a more human centre experience. These critical factors are missing during the remote pairing session. For this reason, it is essential to emulate the physical pairing as much as possible, having the camera on and streaming high-quality video.

Having the camera on allows you to see the other person’s expression and feeling of not being alone. It helps you to ensure to be listened to and force the other person to not be distracted. Turning your camera off is okay if you need it or if you have a problem with your internet connection. It’s okay turning it off during your breaks, and it’s okay if you are not feeling comfortable, but be conscious that you will lose lots of communication, making the session harder.

Use the right tool : Don’t stick with a single tool; if you need to use multiple tools, do it. The smoother the session is, the better. For instance, if you find the Zoom screen sharing pretty bad, try to use Visual Studio Live Code and use Zoom just for the call. Sure, you will use more resources, but it is the right thing to do if it improves your pairing session. Nowadays, there are a lot of tools you can try; use the one you and your pair find more comfortable.
Breaks breaks breaks! : Pairing is a brain power-consuming activity, so if by default you need breaks, when remote, you need it even more. Don’t be shy and ask whenever you need a break preventing zoom’s fatigue or, in general, being exhausted at the end of the day.

I have less experience than my pair

Pairing is not only about showing what you know but also showing what you don’t know.

It’s totally fine saying “I don’t know” during a pairing session. It’s fine admitting you have less experience or are just blocked. Your pair have to support, unblock and guide you.

Pairing has this colossal benefit that cultivation is part of this activity. It helps juniors grow together by getting more confident, and it allows seniors to learn from less experienced engineers (it happens frequently).

Pairing is about trust and being honest and open with your pair, so don’t be afraid. Learning is a beautiful journey, and pairing is the safest way to do so.

I have more experience than my pair

Having more experience than your pair shouldn’t be a problem; it should be an occasion to do mentoring and cultivation.

As a more experienced person, you should adjust your speed accordingly.

The pairing session is also an excellent way to clarify whether or not you understood something; if you can explain it in simple words, then you understood it. It is a perfect way to improve your skills.

Yara Yara

I’m pretty sure there are many other complaints we can consider and address, but the result will always be the same.

Pair programming brings to your team tons of benefits if it is done correctly.

My advice would also be to set the right expectations at the beginning of the session. Let’s agree on what the pairing session would look like and clarify the style with your pair to avoid wrong assumptions and behaviours that can degrade the experience for both of you.

Happy Pairing!

Other resources

Here there are some resources you can find useful to convince your boss that doing pair programming is the way:

How to mock with Jest and Typescript

Domenico Luciani — Fri, 17 Jun 2022 08:00:00 +0000

As an Extreme Programmer I used to jumping often into different engagements, each of them has challenges I need to overcome and problems I need to solve.

This time I jumped into an engagement with a legacy codebase composed mainly by AWS lambdas written in Typescript. Language and technology I’ve never used before.

How can I learn the language and at the same time being able to quickly deliver value?

The answer in my head was clear: let’s create some tests, the rest will follow!

Disclaimer: I’m still learning the language so any feedback would be very welcomed, I’m writing this article to describe my journey and what I learned so far, so any suggestion and correction will be definitely appreciated.

Jest Testing Framework

Working on a legacy code often means you have to use whatever it’s already there and in this case the testing framework that has been installed but that I’ve never used before was Jest.

Luckily most of these frameworks are quite similar but definitely have a look into the documentation, helps.

Let me test, let me teeest!

One of the problems we have working on a legacy code is that testing it is quite tricky due the fact the code wasn’t made to be tested at first place.

So you find these gigantic classes full of large methods that are impossible to test with a lot of dependencies, a big ball of mud.

A legacy codebase can be composed by thousands of classes, composed by hundreds of methods and lines of code, so where should we start from?

Core Business Logic

My first step into a legacy codebase is about identifying the core business logic, the critical one. I work with the client’s team to identify which part should never break and which part delivers value.

Once identified, I start retrofitting some unit tests, trying to cover the main use-cases ensuring that everything work as expected and start creating my safety-net.

Working without a safety-net is risky, will slow us down and increase the likelihood that we are going to break something.

Mock Mock Mock

Often you have lots of dependencies you need to take care of and most of the time those dependencies are doing lot’s of weird stuff you don’t know anything about so the safest way to test everything without worrying how those dependencies behave is to mock them, brutally.

In the following sections you can find some snippets of code I found useful during my journey on that project, handling legacy code could be tricky and having the right snippets at the right moment could be life saver.

Typescript, what are you doing??

I found out that compared with other languages Typescript allows you to mock an object easily thanks to the duck-typing.

Let’s see an example:

const readlDependency = {
  functionIneedToMock: () => { ... },
  anotherFunctionIwantToMock: () => { ... },
}

We can just create a new object which reflects the same properties composition of the dependency we need to mock and that’s it, Typescript compiler will identify that object as the same type automagically allowing us to use it seamless . ✨

const mockedDependency = {
  functionIneedToMock: jest.fn(),
  anotherFunctionIwantToMock: jest.fn(),
}

As you can notice, I’ve replaced the implementation with jest.fn() which allows us to mock that function using jest functionality.

Let’s see a more concrete example:

it("Should test something", () => {
  const mockedDependency = {
    functionIneedToMock: jest.fn(),
    anotherFunctionIwantToMock: jest.fn(),
  };

   const obj = new ClassUnderTest();
   obj.methodUnderTest(mockedDependency);

   expect(mockedDependency.functionIneedToMock)
   .toHaveBeenCalledTimes(2);
})

In the previous example we want to be sure to have our mocked function called 2 times. Easy right?

How about the implementation? Easy peasy!

  const mockedDependency = {
    functionIneedToMock: jest.fn(() => "hello world"),
    anotherFunctionIwantToMock: jest.fn(),
  };

jest.fn(implementation) is a shorthand for jest.fn().mockImplementation(implementation)

Mocking imported dependencies

Everything look nice when you can inject your dependencies but in the Typescript world you can avoid passing parameters and just import whatever you need and use it wherever you want more or less, how can we mock or spy on those dependencies? Let’s see an example how to do it:

import { MessageService } from "../message-service";

const messageService = new MessageService();

export class Manager {

  methodWhichUseLotsOfDependencies() {
    ....
    messageService.publishMessage("hello");
    ....
  }
}

and then let’s try to spy on our dependency using Jest:

import { MessageService } from "../message-service";

const spiedPublishMessageService = jest.spyOn(
  MessageService.prototype,
  "publishMessage"
);

it("Should publish the message", () => {

  const manager = new Manager();
  manager.methodWhichUseLotsOfDependencies();

  expect(spiedPublishMessageService)
  .toHaveBeenCalledWith("hello");
}

Simple and clean, essentially we are spying on our dependency, specifically on the publishMessage method and then asserting that it receives hello as parameter.

Of course we can always program the mocked dependency behaviour since the jest.spyOn method returns a Jest mock 🏋🏻‍♂️

What if the class contains static methods?

Often in legacy codebases we may find multiple static methods, used improperly.

How can we handle them with Jest?

Here an example:

We have a Mapper class with a static mapSomethingToSomethingElse method that we want to mock, for instance:

export class Mapper {
  static mapSomethingToSomethingElse() { ... }
  ...
}

our mock:

import { Mapper } from "../mappers/mapper";

jest.mock("../mappers/mapper", () => ({
  Mapper: {
    mapSomethingToSomethingElse: jest.fn()
    .mockImplementation(() => {
      return "dummyMock";
    }),
  }
});

And then we can perform some assertions like:

expect(Mapper.mapSomethingToSomethingElse)
.toHaveBeenCalledTimes(1);

What about AWS Lambda handlers?

Testing an AWS Lambda handler is very similar to what we already done, for instance:

export async function ApiGatewayDoSomethingWithLambdaHandler(
  event: APIGatewayProxyEvent,
  context: Context
): Promise<APIGatewayProxyResult> { ... }

And our test will look like something similar:

Let say we want to spy on our AuthService providing dummy dependencies

const mockedAuthService = jest.spyOn(AuthService.prototype, "checkPermissions");

it("Should test the handler", () => {
    const dummyProxyEvent: Partial<APIGatewayProxyEvent> = {
      headers: { Authorization: "dummyToken" },
      body: "dummyBody",
    };

    const dummyContext: Partial<Context> = { 
      awsRequestId: "dummyAwsRequestId" 
    };

    const response = await ApiGatewayDoSomethingWithLambdaHandler(
      dummyProxyEvent as APIGatewayProxyEvent,
      dummyContext as Context
    );

    expect(mockedAuthService)
  .toHaveBeenCalledTimes(1);
})

As you can see we used the Partial type to avoid moking every property of those objects and then passing them to our handler, asserting that one of our mock has been called correctly.

Just the tip of the iceberg

I still need to learn more than a bunch of things around this very powerful language and I’ve just scratched the top of the iceberg and I’m looking forward continuing exploring this world called Typescript.

InnerSpace 🚀

Domenico Luciani — Tue, 11 Jan 2022 08:00:00 +0000

This year one of my annual resolutions was to be more present online.

I want to be more visible and share more content.

I want to create more articles and share them with more people.

Learn from feedback and grow the number of people with whom I interact.

So, today I decided to create my newsletter called: InnerSpace 🚀

RSS? Can you eat it?

I don’t know how many people still use feed RSS nowadays.

I’ve been using them for a while, but I don’t see many people speaking about them anymore, so I decided to find another way to share my blog posts regularly without the need to share them everywhere.

I have a RSS feed just right here maybe someone who is still using them could find it useful.

Revue

I discovered https://www.getrevue.co/, a simple tool that helped me to create my newsletter, customise it and even have a fixed subdomain where to find all the issues, for free. The experience was quite smoothly so far, let’s see how it goes.

Topics

I will share my blog posts about:

extreme programming
system design
security
IoT
thoughts, useful links and articles

Insights

Revue also gives some insights about my articles, receiving passive feedback.

Here I don’t have analytics and I think that I’m missing a lot of feedback from them.

I think would be nice verifying which content you like most.

For you to obtain more tuned content and for me to understand you better.

Subscription

It’s free, you just need to subscribe, and once in a while, you will receive my issues.

I don’t have a specific plan for them, I don’t want to put to myself any kind of constraint and I don’t want to set any kind of expectation.

You can find the newsletter here: InnerSpace 🚀

I don’t know how it goes, but I’m looking forward to seeing it!

And as always any feedback is super appreciated!

How to sync your Obsidian vault on your Android

Domenico Luciani — Fri, 31 Dec 2021 08:00:00 +0000

I recently moved from Notion to Obsidian and one big problem I’ve had to face was how to sync my desktop instance with my android mobile one without having a paid plan on Obsidian.

After some researches, I discovered how to do it smoothly…

The main tool that I use for my backup/sync is git and specifically, I use a private repo on Github to store my vault.

I don’t have any sensitive information in my vault, so be aware that even tho your vault is inside a private repo, it won’t be encrypted.

Computer

There is an amazing plugin called Obsidian Git which automatically commit and push toward my repo each 10minutes.

Make sure that the Disable push option is deactivated.

It works out of the box if you have already set your credentials on your computer and of course, you always need to initialise your git repo first with

git init
git remote add origin <your repo's address>

Obsidian Git will automatically pull new changes when you start Obsidian, you can also pull it by yourself through the command line or the hotkey ctrl+p searching for “Obsidian Git: Pull”.

I would suggest to put in your .gitignore :

.obsidian/workspaces.json
.obsidian/workspace
.obsidian/cache
.trash/
.DS_Store
.vault-stats

You can just commit and push

git add .
git commit -m "First commit"
git push

Now the Obsidian vault is on Github 🎉

Android

Okay, the vault is online, but how can we sync it on your android mobile phone?

We can install https://termux.com/ to get a Linux shell on your Android, then you can install git and clone the repo.

You can install termux from the Play Store and then execute it, installing and configuring what we need with:

> pkg install git #to install git
> termux-setup-storage #to make storage available

Now let’s configure the Github credentials.

Github credentials

First of all, you need to generate an ssh key for the Android mobile phone

ssh-keygen -t ed25519 -C "email@provider.com"

Don’t add a passphrase, just press enter

If you don’t have ssh installed type

pkg install openssh

Now you need to add the ssh key to the Github’s account, just following these instructions: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account

To get the ssh key you can just type on termux cat .ssh/id_ed25519.pub copying the key and pasting it into the key field of Github’s form adding the ssh key to your account.

Once we have followed these steps we can try to clone the repo:

git clone git@github.com:YOUR_USER/YOUR_REPO_NAME.git

and then let’s move it to the shared folder so you can access it from any Android application:

mv YOUR_REPO_NAME/ storage/shared/

Now you can just open the directory from your Obsidian application and here we go, we have the vault up to date with the latest changes.

I also suggest putting inside your vault a .nomedia file so you won’t see the image contained in your vault in your gallery.

But how can make this process simpler?

Let’s first create a soft link to the repo to simplify the process:

ln -s storage/shared/YOUR_REPO_NAME YOUR_REPO_NAME

And then let’s create a pull.sh script that you will run to pull the latest changes from the repo:

cd YOUR_REPO_NAME/
git pull -r

and the push.sh script:

cd YOUR_REPO_NAME/
git add .
git commit -m "synched with android on $(date)"
git push

then let’s make them executable:

chmod +x push.sh pull.sh

From now on, you can push and pull executing those scripts with:

./pull.sh
./push.sh

Be aware that this solution doesn’t handle possible conflicts which I try to avoid as much as possible resetting my mobile vault considering the desktop one as the most up to date (having regular backups helps me to validate this assumption easily).

Of course, there is surely a window of improvement on this solution but I’m ok right now with this one, it’s easy to open termux, type ./pull.sh and then exit right after that I updated my vault.

Why did I switch from Notion to Obsidian

Domenico Luciani — Fri, 17 Dec 2021 08:00:00 +0000

It’s been a while when I started using notional tools for my day to day. I use these tools constantly, trying to use it as a second brain.

I used Notion for 3 months and it was amazing. I could organize my entire life creating my life’s dashboard, work section and so on.

I could track everything quite smoothly for those 3 months and it’s been an happy journey till I found myself on an airplane. Above the clouds I wanted to track something down in my Notion instance, but then I realized the worst: Notion doesn’t have the offline support.

My second brain was for offline, was unreachable, and let’s say for a so important organ being offline it’s a shame.

Once back to the interconnected world I decided that I wanted to have my second brain always available, always there for my needs, always up and running.

I started googling around and I found a bunch of Notion alternatives, one of these is Obsidian.

Obsidian

Obsidian is a powerful notional tool where everything is a markdown file which means you have the file always available, being able to edit your files with any editor on any platform. You don’t have a fricking database, instead you have a directory called vault which contains all your sub-directories and files.

You can find it here: https://obsidian.md

Links

One of the most outstanding Obsidian feature is the one which allows you to link markdown files between them, also using hashtag visualizing the connections in a graph that is generated by a core plugin. It helps to visualize your “ideas”, clarify the connections between ideas, topics and thoughts.

Configuration

Out of the box obsidian does its amazing job but it’s quite limited to a basic usage, if you want customize more your second brain you have to work a bit on the configuration which is very simple thanks to the amazing work done on the GUI

Plugins

One of the best part of the tool is the community behind it. You can find literally thousands of plugins made by the community for the community.

Most of the authors use their plugins which are open source, so it means that the whole community can contribute, review and approve them.

You can find the available plugins on Settings → Community Plugins → Browse

I really recommend to use few plugins to enrich your experience according to your needs.

My favorite plugins are:

Calendar
Kanban
Admonition
Banners
Highlightr
Natural Language Dates
Reminder
Obsidian Git
Dictionary
Zettelcasten prefixer

Themes

You can customize the Obsidian’s theme using different themes made by the community, having a comfortable environment is the key.

You can find them on Settings → Appearance → Manage

How to move from Notion to Obsidian

I had lots of Notion’s notes so I needed an hand to move everything from there to Notion but luckily the community already thought about that, I found a nice script made by a member of the community to move all my Notion notes to my Obsidian vault.

You can find the script here: (https://forum.obsidian.md/t/import-from-notion/636/2)
You can find the whole documentation about how to do that here: https://forum.obsidian.md/t/notion-2-obsidian-migration-instructions/2728)
For the generic import you can find everything on the Obsidian documentation: https://help.obsidian.md/How+to/Import+data

Backup

I backup my vault using a personal repo on Github and the Obsidian Git plugin. It backups my files every 15minutes with a specific commit.

You can customize your settings as you prefer and it is fully integrated with your git instance so you don’t need to provide any kind of token or credential.

Mobile App

There is also a mobile application that you can use: https://obsidian.md/mobile

I found a way to integrate my backup on my mobile phone using the free plan but that is a topic for another article.

My Obsidian

This is a screenshot of my Obsidian instance when I was writing this article:

Final thoughts

I find Obsidian very flexible and simple enough to stick with it for a while.

Of course there are always windows of improvement but I’m happy about my choice so far.

I think that all the hype around Notion is very well deserved but still it has downside which forced me to think about the future of my notes.

Obsidian is a way to be sure to have my notes forever and you should think about it too if you don’t want to find yourself in a particular uncomfortable situation where you can’t get your note and you need it.

The Fifteen-Factor App

Domenico Luciani — Sat, 30 Oct 2021 08:00:00 +0000

Have you ever wondered how to deliver good Software As A Service? Nowadays, as developers, we spend most of our time delivering software as a service, but it brings a lot of uncertainties about how to do it properly. Do you know that we already have 15 tips that can help us to achieve that visionary goal?

I’ve been reading a lot about it, and I decided to summarise them in a small article. Let’s dig deeper and find more about this methodology and the fifteen factors which belong to it…

Wait, fifteen?

I thought we had only twelve factors. Who added the other three?

The idea of extending the twelve-factor has been thought of by Kevin Hoffman, explaining them in his book Beyond The Twelve Factor.

1. Codebase

A version control system like Git always tracks the fifteen-factor app.
If we have multiple codebases, it’s not an app but a distributed system.
If multiple apps share the same code, it violates the fifteen-factor. The solution is to add the shared code as a dependency.
There is only one codebase per app, but there are many deploys of the app. The app is the same across all deploys, but different versions may be active in each deploy.

2. Dependencies

A fifteen-factor app declares all dependencies, completely and exactly, via a dependency declaration manifest. It simplifies the setup for developers new to the app. The new developers will set up everything by running the app’s code with a deterministic build command.
A fifteen-factor app doesn’t rely on the implicit existence of any system tools. If the app needs to shell out to a system tool, that tool should be vendored into the app.

3. Config

Never store constants in the code. To be fifteen-factor compliant requires a strict separation of config from code.
Config varies across deploys; code doesn’t.
Always prefer storing the config in environment variables; environment variables are easy to change between deploys without changing any code.
Environment variables are fully orthogonal to other environment variables; they are never grouped but independently managed for each deployment.

4. Backing Services

Backing Service: any service the app consumes over the network as part of its normal operation.
Systems administrators who deploy the app’s runtime manage the backing services.
There are local and third-party services, and a fifteen-factor app doesn’t make any distinction between them.
Deploy a fifteen-factor app should swap out a local backing service with one managed by a third party without any changes to the app’s code.
Each particular backing service is a resource, called attached-resource.

5. Build, release, run

The build stage is a process that converts a code repo into an executable bundle known as a build.
The release stage takes the build and combines it with the deploy’s current config.
The run stage runs the app in the execution environment.
Each stage is strongly separated.

6. Processes

Fifteen-factor processes are stateless and share-nothing. We have to use a stateful backing service whether we want to store any data. We can use the memory space or filesystem as a temporary, single-transaction cache.
Never use sticky sessions. Never assume that anything cached in memory or disk will be available on a future request or job.

7. Port binding

The fifteen-factor app is completely self-contained.
The web application exports HTTP as a service by binding to a specific port and listening to requests coming in on that port. Note also that the port-binding approach means that one app can become the backing service for another app.

8. Concurrency

Processes are first-class citizens.
We should design our application to distribute workload across multiple processes. Individual processes can leverage a concurrency model like Thread internally.
Fifteen-factor app processes should never daemonize or write PID files, instead, rely on the operating system’s process manager.

9. Disposability

The application should be disposable; it means that we can start or stop it at any moment.
We should aim to minimize startup time. The process should take a few seconds from the time the launch command is executed until the process is up and ready to receive requests or jobs.
Processes should also be robust against sudden death. A fifteen-factor app is designed to handle unexpected terminations.

10. Dev/prod parity

The fifteen-factor app is designed for continuous deployment by keeping the gap between development and production small.
The time between deploys should be just hours than weeks.
The author of the code and who deploy the application is the same person.
Dev env and prod env should be as similar as possible.

11. Logs

Logs are the stream of aggregated, time-ordered events collected from the output streams of all running processes and backing services.
Fifteen-factor app never concerns itself with routing or storage of its output stream. The application should write its event stream, unbuffered to the standard output.
The stream can be sent to a log indexing and analysis system like Splunk to find past events, graph trends, and active alerting.

12. Admin processes

One-off admin processes should be run in an identical environment as the regular long-running processes of the app.
Admin code must ship with application code to avoid synchronization issues.

13. API First

We should define the service contract first to help our consumers understand what to send and receive, defining a common contract.
This approach enables consumers and service developers to work in parallel.
It helps avoid bottlenecks and facilitates the virtualization of the APIs so the consumers can run the tests against the mocks.

14. Telemetry

Monitoring our microservices, containers, and env help us to scale, self-heal and manage alerts for end-users and platform operators.
We can use machine learning towards those metrics to derive future business strategies.
We can observe the application’s performance, stream of events and data, health checks, when the application starts, scales, and so on.

15. Authentication

Make sure all security policies are in place. Developers tend to underestimate the importance that security has.
APIs should be secured using OAuth, RBAC, etc.
Web content should be exposed externally on HTTPS
MFA
Database protection

References

12 Factor App
Beyond the Twelve-Factor App by Kevin Hoffman

Distributed Tracing

Domenico Luciani — Mon, 13 Sep 2021 08:00:00 +0000

Recently I’ve seen a thread on Twitter regarding distributed tracing systems. I recognise that sometimes it’s an underestimated topic, so I thought to write a short and introductory article about it…

Scrolling my TL, I’ve seen a thread by Jaana Dogan regarding distributed tracing systems; under that thread, I’ve read many people asking about it or just interested in that topic, so here we go.

What is distributed tracing?

One of the advantages of having a monolithic application is that we don’t need to worry too much about tracing our incoming requests because everything is self-contained.

However, when a request comes into a microservice, that could result in a cascading chain of calls to various other services, and there the tracing could become a very complex task.

Distributed tracing allows the logs to span servers, not only through multiple instances of a single service but through multiple instances of multiple services establishing a correlation between them.

By the book, the tracing system should allow scalability and have low overhead and application-level transparency. Ideally, it should enable quick analysis of the tracing data.

Practical Example

Let’s see a diagram of what can happen in a real use case scenario

To track and monitor this entire request flow, considering that we have multiple instances of the web app and other services running, an origination id is needed that spans the request as the whole flow.

Each step must generate and use span ids to helps us to view each step is still considered as part of a bigger request flow.

For instance:

A user requests a webpage, so we will generate an Origination Id: 123 and a Span Id: 1, then the page calls another service to get the profile detail, so we are going to have an Origination Id: 123 and a Span Id: 2, and so on.

This is important to trace logs to reverse a sequence diagram from the available data for any request. Having enough context will be simpler and faster, helping us to react quickly when needed.

How to implement it

The implementation is relatively straightforward. For every incoming request, examine the HTTP headers. If there is a trace id, we know we are already tracing it down; if there isn’t, create a new one. Always create a new span id and then make the trace and span context available to our code to add metrics and helpful information for later.

I really recommend not reinvent the wheel. Nowadays, there are many already well-known solutions, and most of them work very well for most scenarios.

References

Distributed tracing is essential for troubleshooting microservices applications; most modern distributed tracing solutions are based on the Google Dapper Whitepaper that I suggest reading.

Save 5 minutes web scraping with Rust

Domenico Luciani — Fri, 30 Apr 2021 08:00:00 +0000

Often I read that for simple tasks Rust is not a good choice. Go is more adopted when we need to create a small script to automatize our jobs. But is it true?

Read the article!

Stop the data mess with the data mesh

Domenico Luciani — Tue, 20 Apr 2021 08:00:00 +0000

One of the hottest topics of the moment in Big Data is undoubtedly the Data Mesh, but what is it? Why is this better than the solutions we had before? Do we need it? Should we adopt it?

Read the article!

Manage your learning process with Toby

Domenico Luciani — Sat, 27 Mar 2021 08:00:00 +0000

As a greedy learner, I used to find myself full of bookmarks of stuff I want to read or watch. I’ve never had a good place to keep all the things I read/watched until I found Toby.

Read the article!

Hacktoberfest 2020

Domenico Luciani — Sun, 31 Jan 2021 08:00:00 +0000

Ah shit, here we go again. Another year passed, and another Hacktoberfest is over. I’ve just received my swag, and I can’t be more excited!

Since 2014, every year I try to find the time to contribute to some open-source projects that need help, every year I get swag and an awesome t-shirt from @DigitalOcean in exchange of my contributions. Amazing, eh?

Read the article!