Forem: Michal Gornicki

Event driven API documentation made simple (Client-Side Rendering).

Michal Gornicki — Sat, 30 Jul 2022 17:24:45 +0000

📢 Original article is available on my website where you can also find my Internship Journal.

This post is a bit different from the other articles.

In my previous posts, I have written for absolute beginners, but this one is for developers looking to automate and formalize documentation generation for event-driven projects.

This guide is directed toward folks looking for instructions on how to generate documentation using their AsyncAPI files. Event-driven APIs are not the same as the synchronous APIs you usually document with OpenAPI or GraphQL. Many people use AsyncAPI now, and it is time to provide the community with a guide that shows what options the community has to render documentation on the client-side.

Oh, if you are still not sure about Client-Side Rendering or Server-Side Rendering, then you can read all about it here 👉 Website rendering for beginners (shameless plug 😉).

I will cover the usage for:

React
Vue
Web Components
Standalone Bundle

All examples will use this same AsyncAPI sample file 👇

{
  "asyncapi": "2.2.0",
  "info": {
    "title": "Account Service",
    "version": "1.0.0",
    "description": "This service is in charge of processing user signups"
  },
  "channels": {
    "user/signedup": {
      "subscribe": {
        "message": {
          "$ref": "#/components/messages/UserSignedUp"
        }
      }
    }
  },
  "components": {
    "messages": {
      "UserSignedUp": {
        "payload": {
          "type": "object",
          "properties": {
            "displayName": {
              "type": "string",
              "description": "Name of the user"
            },
            "email": {
              "type": "string",
              "format": "email",
              "description": "Email of the user"
            }
          }
        }
      }
    }
  }
}

This is the expected look of the generated document 👇

All usage examples from this article are available to check on asyncapi-docs-rendering-examples repository.

React

If you wish to render documentation from your AsyncAPI file in React application, then you need to use AsyncAPI React component.

1️⃣ To install the React AsyncAPI component run the command npm install --save @asyncapi/react-component@next.

2️⃣ Now, create index.js file and type in:

import React from "react";
import ReactDOM from "react-dom";

import AsyncApiComponent from "@asyncapi/react-component";
import "@asyncapi/react-component/styles/default.min.css";

import { specMock } from "./testDoc";

const rootElement = document.getElementById("root");
ReactDOM.render(<AsyncApiComponent schema={specMock} />, rootElement);

React AsyncAPI component is imported on the line 4.

If you are happy with AsyncAPI styling then you need to import their CSS pattern with import "@asyncapi/react-component/styles/default.min.css";

On the line 7 is where AsyncAPI sample file is imported.

Vue

If you wish to generate documentation from your AsyncAPI file in Vue application, then you need to use AsyncApiStandalone bundle.

1️⃣ React AsyncAPI component is required here as well, so again you need to run npm install --save @asyncapi/react-component@next command.

2️⃣ In your App.vue just add this code:

<template>
  <div ref="asyncapi"></div>
</template>

<script>
import AsyncApiStandalone from '@asyncapi/react-component/browser/standalone';

// AsyncAPI specification, fetched or pasted.
const schema =
'{"asyncapi":"2.4.0","info":{"title":"Account Service","version":"1.0.0","description":"This service is in charge of processing user signups"},"channels":{"user/signedup":{"subscribe":{"message":{"$ref":"#/components/messages/UserSignedUp"}}}},"components":{"messages":{"UserSignedUp":{"payload":{"type":"object","properties":{"displayName":{"type":"string","description":"Name of the user"},"email":{"type":"string","format":"email","description":"Email of the user"}}}}}}}';

const config = {}; // Configuration for component. This same as for normal React component.

export default {
  name: 'AsyncApiComponent',
  props: {
    msg: String
  },
  mounted() {
    const container = this.$refs.asyncapi;
    AsyncApiStandalone.render({ schema, config }, container);
  }
}
</script>

<style scope src="@/assets/asyncapi.min.css"></style>

As you can see on line 6, you need to import AsyncApiStandalone bundle with import AsyncApiStandalone from '@asyncapi/react-component/browser/standalone'; command.

3️⃣ There is one more thing to do. If you like AsyncAPI styling then you need to go to 👉 node_modules/@asyncapi/react-component/style/default.min.css.

Copy that file and then paste it into your assets folder.
I renamed mine asyncapi.min.css.

You can import this in your main.js file with import './assets/asyncapi.min.css' or, as I did, add it at the end of App.vue file with <style scope src="@/assets/asyncapi.min.css"></style>.

Web Components

To generate documentation from your AsyncAPI file, you can use it as an element of an HTML webpage or as a web component in any other web framework you choose. You can do this by implementing web-react-components.

1️⃣ Just create a .html file then copy and paste this code 👇

<script src="https://unpkg.com/@asyncapi/web-component@1.0.0-next.39/lib/asyncapi-web-component.js" defer></script>

<asyncapi-component
  schema='{"asyncapi":"2.4.0","info":{"title":"Account Service","version":"1.0.0","description":"This service is in charge of processing user signups"},"channels":{"user/signedup":{"subscribe":{"message":{"$ref":"#/components/messages/UserSignedUp"}}}},"components":{"messages":{"UserSignedUp":{"payload":{"type":"object","properties":{"displayName":{"type":"string","description":"Name of the user"},"email":{"type":"string","format":"email","description":"Email of the user"}}}}}}}'

  config='{"show": {"sidebar": false}}'

  cssImportPath="https://unpkg.com/@asyncapi/react-component@1.0.0-next.39/styles/default.min.css">
</asyncapi-component>

2️⃣ If you need support for old browsers then you need to add this script as well <script src="https://unpkg.com/@webcomponents/webcomponentsjs@2.5.0/webcomponents-bundle.js"></script>.

That is it! 🤯 Just awesome!

Standalone Bundle

If you want to render documentation from your AsyncAPI file without the use of any framework but with just an HTML webpage then you will need the Standalone bundle.

1️⃣ All you need is just a basic HTML template.

2️⃣ In the head element enter <link rel="stylesheet" href="https://unpkg.com/@asyncapi/react-component@1.0.0-next.39/styles/default.min.css"> to get AsyncAPI document styling.

3️⃣ In the body element type in:

 <div id="asyncapi"></div>

    <script src="https://unpkg.com/@asyncapi/react-component@1.0.0-next.39/browser/standalone/index.js"></script>
    <script>
        AsyncApiStandalone.render({
            schema: '{"asyncapi":"2.4.0","info":{"title":"Account Service","version":"1.0.0","description":"This service is in charge of processing user signups"},"channels":{"user/signedup":{"subscribe":{"message":{"$ref":"#/components/messages/UserSignedUp"}}}},"components":{"messages":{"UserSignedUp":{"payload":{"type":"object","properties":{"displayName":{"type":"string","description":"Name of the user"},"email":{"type":"string","format":"email","description":"Email of the user"}}}}}}}'
            ,
            config: {
                show: {
                    sidebar: false,
                }
            },
        }, document.getElementById('asyncapi'));
    </script>

<script src="https://unpkg.com/@asyncapi/react-component@1.0.0-next.39/browser/standalone/index.js"></script> fetches everything required from the bundle.

I almost forgot.

There is one more way to configure the AsyncAPI component.
You can do it through config props, this same as for normal React component.

My Web Component and Standalone Bundle usage examples have config='{"show": {"sidebar": false}} which turns a sidebar off, but if you change it to true then your rendered document will have a sidebar.

This was only a sample of what could be done. AsyncAPI can do a lot more. Check AsyncAPI documentation for more information on how to generate docs.

I hope that you liked this quick guide through AsyncAPI Client-Side documents generation.

As usual, if you find any mistakes, don't go mad in the comments section. Just let me know and together we can fix it so this article can be even better.

Website rendering for beginners.

Michal Gornicki — Thu, 16 Jun 2022 21:45:46 +0000

📢 Original article is available on my website where you can also find my Internship Journal.

I decided to write an article about website rendering because this topic is not as easy as it may seem.

For all the people who have worked in this environment for some time, this subject may be as easy as pie, but if you are a beginner, it may be confusing or intimidating even.

I will try to explain everything as simple as possible. I will not dive too deep because the sole purpose behind this post is to give you a general idea of how rendering works.

If after reading you feel that this was interesting, and you wish to go into more details, then I will provide some extra links at the bottom 👇

What are the rendering types:

Server-side Rendering
Client-side Rendering
Build-level Rendering
Dynamic SSR

First, let me explain what the rendering is.

As you can see, a browser requests an HTML document from a server. Then a server returns a formatted HTML text file.

Within that file, there is the whole information about the elements (CSS, JavaScript, images, videos, etc.) required to create a visual representation with which you can interact in the browser.

Rendering is combining all that information to create a website. The way you are rendering the website means what way are all these elements fetched.

Website rendering affects how a page is indexed, which impacts Search Engine Optimization (SEO).

I will not cover indexing or SEO in great detail here. As I mentioned, I will add links at the end of the article.

Server-side Rendering (SSR)

Server-side rendering means that when you are visiting a website, all the website's content is processed and rendered on the server.

1️⃣ First, through your browser, you are sending a request to access a website.

2️⃣ Next, all necessary files (HTML, CSS, JavaScript) are prepared and compiled.

3️⃣ A fully rendered webpage is delivered to your browser.

Something like that 👇

When would you use SSR?

If your website doesn't have many users, it has a simple User Interface (UI), maybe a few pages, small dynamic data, and minor interactivity.

SSR pros:

It is Search Engine Optimization friendly, which means that a search engine such as Google can crawl each page on a website successfully, analyse the content efficiently, and index it in their databases. All this has then an impact on how high your website will appear on the search engine results page (we all want that #️1 page 🤑😉).
Faster initial page load time, which also impacts your SEO because Google prioritizes the ones that load faster.

SSR cons:

It can be very expensive. When your website increases the number of visitors, with each user accessing a new page, it has to send a server request every time. As a result, the server must deal with high memory usage and high processing power, which will have an impact on the hosting price 🤷‍♂️.

Client-side Rendering (CSR)

Client-side rendering means that when you are visiting a website, all the website content is downloaded, compiled and rendered in your browser.

1️⃣ First step is the same as in SSR, through your browser, you are sending a request to access a website.

2️⃣ Then, the server sends an HTML text file.

3️⃣ After that, the browser will download all static content required by the HTML file and JavaScript.

4️⃣ The JavaScript framework of choice (React, Angular or Vue.js) takes control and starts fetching and processing data within the browser.

5️⃣ Lastly, you can view a website of your choice in your browser.

Take a look here 👇

When would you use CSR?

If SEO is not a priority, your website has many visitors and depends on dynamic content and complex UI (or both).

CSR pros:

allows creating a website with complex user interactions.
although the initial load can be slow, but after that, we can see fast website rendering.

CSR cons:

as mentioned above, it can be slow when loading for the first time. It depends on many variables like a visitor's internet connection speed, or is the device used to access that website is an old computer or tablet (old machines might not be powerful enough to handle it).
if Search Engine Optimization is important to you, then you probably need to stay away. SEO for the website will be negatively affected because the content is not rendered until the browser is loaded. I know that they are ways around it, but apparently, these are complicated(hence expensive).

Build-level Rendering(BLR)

Before I can explain how Build-level Rendering works, I need to address what is CI/CD.

CI/CD stands for Continuous Integration, Continuous Delivery and Continuous Deployment; it is often referred to as a "CI/CD pipeline".

"How it works?" - you may ask. Most simply, this is a modern approach to product development. It is continuous automation of integration, testing, delivery and deployment phases in the life cycle of a website/application.

1️⃣ A developer works on a local environment. Code some changes to a website and run some tests (npm run dev). Once everything went ok, the code is pushed onto a shared branch.

2️⃣ At the Continuous Integration stage, a code is validated by automatically building an application and running different automated tests. If these changes break the app, then CI makes it easier to locate and fix these bugs. If all unit and integration tests were successful, then the code is merged into the release branch.

3️⃣ The Continuous Delivery is the part that interests us from the perspective of the Build-level Rendering. In the cloned production environment (an environment imitating your end product) all components are automatically tested and once everything is good, the code changes are deployed to production. The release branch can be deleted once it merges with the production.

4️⃣ Here is the last stage of CI/CD pipeline. During the Continuous Deployment stage, if all automated tests are completed, then all changes are applied to a website/application.

Some would say that Build-level Rendering takes place now, but I think that the whole "hard work" is done at the previous step. If any tests fail now, that would be more likely down to the development environment not being set up correctly (if you think of other reasons, please let me know in the comments below 👇).

In short, the CI/CD pipeline (steps 2-4) is very good and necessary because it allows you as a developer to get continuous feedback across all stages. This is an agile way of developing an application (Chris, my lecturer, would be very proud 😉).

5️⃣ Unlike in SSR where everything is compiled on the severer (once a user requests a website), BLR delivers a ready product to a server where it waits for a user to request it.

It looks like that 👇

When would you use BLR?

It would have this same application as Server-side Rendering.

Pros and Cons would be similar to SSR. I would add another potential con - if you decide to go with this way of building an application, just make sure that your CI/CD pipeline is set up correctly. It requires creating a high level of automation and continuous monitoring which can be costly at the beginning, but once it is set up correctly then it should work like a charm.

Dynamic SSR

Dynamic SSR is trying to combine SSR and CSR together. The goal is to provide solutions which would allow the creation of SEO-friendly, fast-loading, dynamic websites with loads of visitors with minimal performance impact.

"In a nutshell, dynamic rendering is the principle of sending normal, Client-side Rendered content to users, and sending fully Server-side Rendered content to search engines and to other crawlers that need it." (John Mueller at Google I/O 2018 event)

1️⃣ Just like on other occasions, through your browser, you are sending a request to access a website.

2️⃣ Next, initial HTML load and minimal JavaScript is sent to your browser and separate one to a renderer. This allows you to see the website in your browser (the website is not yet interactive).

3️⃣ Initial load sent to the renderer is now compiled into a formatted HTML text file.

4️⃣ Web crawlers (like Googlebot, Bingbot, DuckDuckBot) "digest" the website's content and then index it. This is what helps to improve Search Engine Optimization and user experience. Crawler focuses on the information best known to it, and you as a user can see a website on your screen.

5️⃣ Lastly, JavaScript downloads and runs all necessary code to make a website fully interactive.

Obviously, all the above steps take seconds to complete.

Here is a visual representation 👇

When would you use Dynamic SSR?

A large website with very demanding, dynamic JavaScript content.

Dynamic SSR pros:

it enables crawling and indexing of content without executing JavaScript.
SEO-friendly website with all interactive components that need JavaScript.

Dynamic SSR cons:

like with the SSR, it can be expensive. Now the website not only has to handle every visitor's traffic but crawl bots as well, and we know that this will put an extra burden on the server, hence the hosting price hike.

Something extra

The idea behind my article was to simplify website rendering for beginners, but if you feel that you need to dive deep into the nitty-gritty, then here are some other sources:

"deep dive into DOM and CSSOM to understand how the browser renders a webpage"
The Beginner's Guide to SEO
an interesting clip on how to deliver search-friendly JavaScript-powered websites
web crawlers

I hope that you have enjoyed this article and I managed to make the website rendering a little less overwhelming.

If you notice any mistakes on my part, please let me know in the comments section below 👇 then I will address them, and together we can make this article even better.

How to configure Next.js, Tailwind CSS starter blog.

Michal Gornicki — Tue, 24 May 2022 19:01:09 +0000

📢 Original article is available on my website where you can also find my Internship Journal.

After I wrote my article on How to make your blog feature-rich with Next.js, Tailwind CSS and Vercel I realised that some beginners might have troubles with configuration.

In this article, I will explain the changes which I made when I created my new website.

This is what I changed so far:

data/siteMetadata.js
data/authors/default.md
data/projectsData.js
components/comments/Giscus.js
data/blog
public/static

data/siteMetadata.js

Information about the site that should be modified to meet your needs. In this file I have only changed:

title: - this is the title of your page, it is what you will see in the tab

author: - put in your name
headerTitle: - your page name

description: - describe your website, put in something "catchy"😎

siteUrl: - your website address
siteRepo: - update the link to this project's repository on GitHub
siteLogo: - if you have a logo, update it here
image: - update the link to your picture here
email: - update your email (I don't have the newsletter switched on yet)
github: - showcase all of your GitHub repositories
linkedin: - put in the link to your LinkedIn profile page

I commented out other social media links but you do whatever you think is the best for you.

data/authors/default.md

This is your "About" page so it is important to change it.

data/projectsData.js

Styled cards are generated using data from the projectsData file.

components/comments/Giscus.js

Before you can activate the comments system on your website, you need to generate a script with your specific information.

1️⃣ Go to the giscus website then click on giscus app.

You should see this 👇

2️⃣ Click Install then select Only select repositories and pick your project repo.

3️⃣ Again, click Install. This should add giscus to your account.

4️⃣ Now you need to activate discussions. Go to Settings in your repository.

Scroll to Features and tick the box for Discussions.

5️⃣ Go back to https://giscus.app/ and scroll to Configuration. Here are some things you need to do:

Choose the language giscus will be displayed in.
Test if your repository meets all three highlighted criteria ( I would recommend to type in the details of your repository because Copy/Paste creates an error).
In Page ↔️ Discussions Mapping I selected Discussion title contains page URL but you select whatever you think is the best option for you.
In Discussion Category select from the drop-down menu a category where the new discussions will be created. If you want your own custom category then you need to:

Go back to your project repository and click on Dicussions and then the pen icon.

Now you should be able to add your custom category name, select discussion format and then click Create.

Go back to giscus main page, scroll to Discussion Category and your custom category should be there for you to select.

I did not change anything in section Features and Theme.
In Enable giscus you can see there was a script generated.

6️⃣ Now, go to your project folder, open your favourite editor and go to components/comments/Giscus.js.

7️⃣ Update all the data in that file (mine starts on line 33) with the data from the generated script.

8️⃣ Now, save that file, push it to your repository and voila - you have comments on your website.

data/blog

title: - here goes the name of your post, it is required.
date: - it is self-explanatory, also required.
tags:- this is a required field. If you don't want to use tags then you can leave it as an empty array, like this 👉 [''])
draft: - this is an optional but handy feature. Let's say that you are in the middle of writing a post but you don't want it to appear on your website. All you need to do is to type in draft: true and this post will remain invisible. Type in false if you want the blog to be visible.
summary: - another optional feature. You will use it to give brief information on what is the blog about.

public/static

Here you will store your images and favicons.

If you already have a logo but don't have the favicons, here is what I did.

First, I removed background from my logo.

Next, I used the updated logo to generate favicons.

Now all you need to do is to replace existing favicons with your design.

How to make your blog feature-rich with Next.js, Tailwind CSS and Vercel.

Michal Gornicki — Wed, 18 May 2022 16:41:17 +0000

📢 Original article is available on my website where you can also find my Internship Journal.

A few weeks ago I set up my first blog with the use of GitHub Pages and Markdown.

It was not that complicated and did not require any coding knowledge.

Today I decided to "pimp my blog"😀. I want it to look a bit better than it already looks but also add more features and maybe separate articles from the internship journal and also maybe add a bit about myself.

‼️First of all. This blog transformation would not be possible without Timothy who created this amazing starter blog 👏. It comes pre-configured with the latest technologies (Next.js, Tailwind CSS), it is highly customizable and not very difficult to configure. The original repository is available here. ‼️

This is not going to be as easy as last time but I will try to create a simple tutorial so you will be able to do it yourself.

Just to let you know, I am using Pop!_OS so if you are using MacOS or Windows then you may have to look for another tutorial 🤷‍♂️. If you are using other Linux distributions then you should be fine(there might be some differences in the command line but I am not expecting anything major).

Also, you need to run these commands:

sudo apt install build-essential
sudo apt install libssl-dev

We don't need to get into details now but these packages may be required at some stage during this or future projects.

Last but not least, you need a GitHub account. It is essential.

Here are the steps I did to complete my website transformation:

Downloading and installing Node.js
Starting my "new look" site
Push everything to GitHub
Deploying to Vercel

Downloading and installing Node.js

What is Node.js? It is the back-end JavaScript runtime environment. We will also need npm which is the world's largest software registry and the default package manager for JavaScript. More information about npm is available here.

1️⃣First of all check if you need to install Node.js. Open your terminal and type:

node -v

If you have it then you will see this(you may have a different version number)👇

If you don't have it then you will see

command 'node' not found...

After reading a few articles it looks like the best way to install Node.js is through nvm (node version manager) because it allows to quickly install and use different node versions for different projects.

2️⃣Open your terminal and type👇

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

If you don't have curl, install the utility by running the command:

sudo apt install curl

(curl is used in command lines or scripts to transfer data).

Close your terminal and open, then type this nvm --v. If everything worked ok then you should see something like this👇

Let's install the latest long term support Node.js with the following command👇

nvm install --lts

Now, verify if everything is installed. Type these commands:

node -v
npm -v

If you run into any issues, please check this 👉 very detailed source.

Starting my "new look" site.

1️⃣You need to create a new empty folder(name it whatever you like). If you will try to run the command from step2️⃣ in the directory where you have an existing git project then you will see this message

! destination directory is not empty, aborting. Use --force to override

2️⃣Open console in your new folder and type 👉npx degit https://github.com/timlrx/tailwind-nextjs-starter-blog.git.

More likely you will see this message👇

Don't worry, just hit "y" and it will install it. degit makes copies of git repositories, it is like a clone in GitHub.

Once you successfully installed degit, run the step2️⃣ command once again and you should see 👉 > cloned timlrx/tailwind-nextjs-starter-blog#HEAD

3️⃣Open your favourite editor (I am using Visual Studio Code) and access the cloned folder.

Here are some files that you need to edit:

data/siteMetadata.js - here you personalize your site related information.
next.config.js - here you modify the content security policy if you want to use any analytics provider or a commenting solution other than giscus (visitors leave comments and reactions on your website via GitHub).

If you are a beginner like myself, I would recommend staying away from that one for a time being. Just leave it be 😉.

data/authors/default.md -here you put your info, this will be your "About" page.
projectsData.js - if you have any projects completed that you would like to show then you need to edit this file as well.
headerNavLinks.js - here you customize the navigation links.
data/blog - here you put in your blog posts.
public/static - here you keep your images and favicons.

4️⃣Once you are happy with your changes then you need to run this command 👉 npm install.

5️⃣Now enter npm run dev. This will create a build directory with a production build of your app and also will highlight any issues which may potentially cause your app to break.

I had to resolve the chaining issue in file components/comments/Giscus.js and on line 31 I removed all "?"(no, I am not that advanced, I managed to fix it with help of my mentor👏).

6️⃣After you are happy that all issues were resolved🤞, you need to open this address http://localhost:3000 in your browser to see if the website looks like you wished.

This is mine at the moment👇

Push everything to GitHub.

So far everything happened locally, on my laptop. Now it is the time to send everything to my GitHub.

This is the first time where I created a project before having the repository.

I usually clone repositories with HTTPS and then I need to create a token to securely communicate with GitHub but this time I decided to try SSH(Secure Shell). Not only because it is considered more secure but entering the secure token before each push was getting on my nerves.

1️⃣First, open a terminal and generate a new SSH key. Follow these instructions 👉 here

⚠️You need to remember the password that you created in step 1️⃣ because you will need it in the future(each time PC reboots you will need to enter it).⚠️

To copy that key, go to your Home directory and in settings, tick the box to show hidden files.

Locate your .ssh folder and then open .pub file and copy your key.

2️⃣Next, you need to add your key to your GitHub account as per instructions in this 👉 document.

3️⃣Go to the folder where you keep your project and open the terminal. Add your SSH key to the ssh-agent. This is explained 👉here.

4️⃣Now, please follow this great tutorial on How to Push an Existing Project to GitHub. To push your repository to GitHub, you will need these commands👇.

git init
git add .
git commit -m 'some comment'
git remote add origin git@github.com:your-GitHub-name/new-project.git
git push --set-upstream origin main

I really recommend going through the tutorial first(unless you know what you are doing).

5️⃣All files should be now uploaded to your GitHub repository.

Deploying to Vercel.

Vercel is another company offering website hosting, and it is maybe even easier to deploy your website than with GitHub Pages. Again, personal opinion.

1️⃣Go to their website and click "Start Deploying" and then pick the option to sign in with your GitHub.

2️⃣After successful sign in you should see this 👇

3️⃣Click on "Select a Git Namespace" and then "Add GitHub Account".

Select your account and then tick "Only select repositories" which will allow you to pick the one with the project.

Now click "Install"(you will need to enter your GitHub password).

4️⃣Once successful, you should see this 👇

Click "Import".

Change "Project Name" to the name of your website. This is important because it will become a part of your domain name i.e. "your-website-name.vercel.app".

Now, click "Deploy".

It will take a minute which (if you are lucky😉) should finish with your website deployed.

Clicking on the image will take you to your website.

That's... The best luck scenario. If you managed it without any issues then go and get yourself some Lotto tickets😉.

More likely you will encounter some errors or issues. That's ok. Investigating these problems will increase your knowledge because you will need to read more material/documentation.

I understand that this might be frustrating. Believe me, I KNOW.

Once you pass this stage where you want to smash your laptop with the hammer and you will make this project work, I can guarantee you that you will feel amazing.

If after deployment some things don't work yet, don't worry. It is your ongoing project. Who knows, maybe with time, you will select a different blog to clone or you will build your own from scratch.

Keep your chin up and don't give up 💪.

As always, please share your comments👇. I am still learning so if you notice something wrong with the article, please let me know and together we will improve it🤝.

Increasing visibility of my articles.

Michal Gornicki — Tue, 19 Apr 2022 20:44:27 +0000

📢 Original article is available on my website where you can also find my Internship Journal.

In this article, I will share my experience and opinion on how I went about increasing the visibility of my blog.

What I describe here are my personal views which may be different to yours, but that's ok. No need to get angry. You are more than welcome to leave your opinion in the comment section below.

After I posted my first internship blog on How to use GitHub Pages and Markdown to host a website I went on LinkedIn to promote it.

It was very straightforward. I clicked on Start a post, wrote an introduction, pasted the link to the blog, added hashtags and hit Post. Quite easy.

I used hashtags to reach an audience other than just my followers so this can lead to greater engagement. I use only four hashtags.

I read a few articles and some pointed out that tags are important but plastering your post with them makes it look "spammy". That may put off the audience. So I decided to use a maximum of four (if you think that this is a bad idea, please let me know 👇).

I had an exactly similar experience with Twitter. Ease of use, very straightforward.

I will post on LinkedIn my main blogs and maybe 🤔 weekly internship updates.

I am planning to use Twitter for daily updates. Not only I will be sharing my blogs when they are ready but I will add my internship journal news.

My tag "strategy" on Twitter - I am using #100DaysOfCode. This tag refers to a challenge to code a minimum of an hour every day for the next 100 days. More of it 👉 here . Whenever I tweet with this hashtag there are bots that present my content to loads of readers(bots are automated Twitter accounts, programmed to perform tasks such as tweet and retweet content for specific goals on a large scale).

Both of these platforms allow me to analyse how my post or tweet performs. All I need to do is to click on post/tweet and then below the content I can see this:

When I click on the highlighted content then:
LinkedIn provides me with something like this 👇

and Twitter with something like this 👇

As you can see there is plenty of information that can be very useful to verify if I am reaching the right people or do I need to change something to achieve my goals.

I decided to explore other options and I focused on two platforms that were new to me: Reddit and Hacker News.

Signing up for them wasn't an issue, posting either, but everything after that was not as intuitive as Twitter or LinkedIn.

I shared my blog at around this same time and pretty much immediately both were taken down 🤷‍♂️.

On Reddit, I have received this 👇

When I was trying to re-post it, it was getting blocked. Eventually, I managed to post it but when I checked recently there was no engagement.

On Hacker News, I couldn't figure out why my post was taken down so I am assuming that it is for similar reasons as on Reddit.

I must admit that both platforms are not that intuitive, especially Hacker News. I guess because it is new to me, I need some time to get used to it.

There are a few other things that I observed over the last few days. Mainly, when writing a blog don't try to be perfect 🤷‍♂️. Up until now, I was trying to be perfect. I was chopping and changing and what I end up with is delay after delay.

Write it down. Run it through Grammarly and then read it out loud. If it makes sense - post it. If you will try to make it perfect you will never finish. If there are any content issues then don't worry, readers will let you know in the comments section.

Another, very important thing. Make sure that your software auto-saves your work. I was testing a new application for markdown and my laptop froze.

I thought, no worries. Well... I lost everything because the document didn't recover. You can imagine that there was a lot of 😡🤬🤬🤬😡.

Aha, if you are blogging for a living I have a newfound respect for you. There is so much to do apart from writing a blog. I didn't even mention Search Engine Optimisation.

As usual, thank you for your time and please let me know what you think in the comments below.

How to use GitHub Pages and Markdown to host a website.

Michal Gornicki — Mon, 11 Apr 2022 21:50:51 +0000

📢 Original article is available on my website where you can also find my Internship Journal.

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub,optionally runs the files through a build process, and publishes a website.

If you are a seasoned programmer or tech guru then this post may not be for you. Although you are still welcome to read it as you may find some issues with this tutorial and I am open to corrections.

I will try to write it as simple (like myself) as possible so even people who are not tech-savvy will be able to follow and start blogging or just publish a website.

Here is the summary of what you will find in this post:

What you need before you can follow this tutorial
Creating a new repository
Setting up your website
Working on your website/blog
Sources required to master Git, GitHub and Markdown

What you need

Most important. Before you start you need to have a GitHub account.

What is GitHub?

Briefly, it is a platform offering internet hosting for software development and version control. You are going to store your code here and you will be able to collaborate with whoever you wish and track and control changes.

I will not cover here how to open a GitHub account. There are many tutorials available on YouTube or just search on Google.
I would recommend just diving right in as the process is not that complicated. Just go to GitHub click "Sign up for GitHub" and follow the instructions. They are straightforward.

I am assuming that you already have an account and you are logged in.

Creating a new repository

1️⃣ On the top right-hand side click on your avatar and then click "Your repositories".

Depending if you are just starting fresh, you may see just info that "your profile name doesn’t have any public repositories yet." or the list of your existing repositories.
2️⃣ Most important is that you need to click on "New".

Now you should see this 👇

Your repository name should be the same as the owner followed by github.io so like m1ner79 is an owner so the repository is m1ner79.github.io.

A description is optional so you can leave it blank, also leave the selection at Public.

3️⃣ Next, you need to tick "Add a README file" - here is where you will be creating your website content.

"Add .gitignore" is not required at this stage because .gitignore creates a list of files that do not need to be tracked. This can be added at any moment and depending on how complicated your blog is, might not be necessary at all.

4️⃣ Tick "Choose a license" because it will help future collaborators what they can and can't do with your code. You can't go wrong with "MIT License" so select it and click "Create repository" (Before you are going to follow my advice, please have a look 👉 here where Kevin makes a valid observation).

You should see this 👇

We are almost there. I know, it is THAT easy.

Setting up your website

1️⃣ Now, as you can see on the screenshot below, click "Settings" and then on the left select "Pages" (highlighted in green).

After you do that you will be advised where is your website "Your site is published at...".

2️⃣ Source(red highlight) should be set to "main" and "/root".

3️⃣ Now the best part. Click on "Choose a theme" (on my screenshot, it says "Change theme" because I already selected the theme).

On the top each square represents a theme and below you will see what your website will look like when you select it.

4️⃣ Once you are happy with your theme, click on "Select theme" and that's it. You will be presented with a page full of markdown language like this 👇

5️⃣ Don't worry, just scroll to the bottom and click "Commit new file".

Now you should see an extra file in your repository.

Yours might be different because you may selected another theme.

Now starts the best part.

Working on your website/blog

Depending on your needs there are two ways to write your blog.

Option one:

1️⃣ Click on README.md file and then on the pencil, like on the highlighted picture below.

2️⃣ All you need to do now is remove everything and start writing your blog. In the end, make sure to commit your changes.That will amend your file and new content will appear on your website.

Option one has also another way of editing your code ("another way" is marked with*️⃣).

*️⃣1️⃣ If you have your repository open and you are on your laptop /desktop(it will work with other devices too), all you need to do is just hit "."

This will open Visual Studio Code in your browser and you can start editing right away.

*️⃣2️⃣ After you will make your changes, you will notice that the source control icon indicates a number of changes. Click on it and then on the top you will see a space where you will enter a message.

*️⃣3️⃣ This message needs to make sense. Just assume that there might be someone else reading that comment so give them a chance to understand what you did i.e. "add a folder for images" or "update xyz file".

*️⃣4️⃣ Now click the tick and your changes are pushed to your repository.

Give it a few seconds and your changes should be visible when clicking on your GitHub Pages address.

Option two:

A bit more complex and I am doing that(because I like a challenge 😉).

1️⃣ You need to create a folder on your local machine where you are going to keep all files required for your blog. Open a terminal.

2️⃣ Now, in your repository, click "Code" and copy that highlighted link.

3️⃣ Go back to your terminal and type in "git clone your link goes here"

This will download all files into your folder. You can now use your favourite editor to work on your blog.

4️⃣ After you have done all changes you need to push these to your repository.

I will not cover how to do it here, instead, I will share some links to the tutorials I have used myself to get better with Git and GitHub.

Hone your Git, GitHub and Markdown skills

This is a very good tutorial from well known freecodecamp.com 👉 How to Start and Create your First Repository.

If you prefer YouTube then try this one 👉 Git and GitHub explained for beginners.

Also, I know that I said it is easy to start writing your blog but you need to get some of the basics for the markdown language so your website will render the way you wanted.

Here is a great source 👉 Markdown Guide and if you like emojis then this is a must 👉 Emojipedia.

That would be all. Please let me know what you think about this post.

Oh, and if you wish to check my internship journal (shameless plug) then click here 👉 Internship Journal.

Thank you for your time, bye!

Thread Synchronization within Linux Operating System.

Michal Gornicki — Tue, 01 Mar 2022 22:41:55 +0000

This short article is about thread synchronization. It will examine the matter under the following headings: Race Condition, Mutex Locks, Critical Section Problem, Solutions to Critical Section Problem, and Deadlock & Starvation.

Race Condition

“A thread is a flow of execution through the process code, with its program counter..., system registers which hold its current working variables, and a stack which contains the execution history[1]”.

A race condition can be defined as the behavior of an electronic, software or another system, in which the output depends on the sequence or timing of uncontrollable events.This term refers to the idea of two signals competing to influence the output first. When events do not occur in the order intended by the programmer, it becomes a bug.

A critical section is where shared variable scan be accessed. A race condition may occur inside a critical section. In a critical section of code, multiple threads execute the code concurrently, and the sequence in which each thread executes the code can make a significant difference to the result[2].

Semaphore is a signalling mechanism of an integer variable that is shared between threads and used to solve the critical section problem and to accomplish process synchronization in the multiprocessing environment.Semaphore enables multiple processes to be managed with simple integer values.Semaphore uses two atomic operations: wait() and signal() for process synchronization.

Mutex Locks

Mutex lock is a simplified version of semaphore. It is a shared variable that can be in one of two states: unlocked or locked.If a process or thread needs access to the critical region, it calls mutex lock.

If the mutex is unlocked the call succeeds and the calling thread is free to enter the critical region.If the mutex is locked, the calling thread is blocked until the thread in the critical region is finished and calls mutex unlock. When multiple threads are blocked on the mutex, one of them is selected randomly and allowed to acquire the lock[3].

There is some vagueness between binary semaphore and mutex. The use cases of mutex and semaphore are different. Because of their implementation similarity, mutex would be referred to as a binary semaphore.

Mutex is a locking mechanism created to synchronize access to a resource. Only one task can obtain the mutex which means that only that process can release the lock (mutex).

Semaphore is a signalling mechanism; an interrupt is activated upon which an interrupt service routine (ISR) signals the call processing task to wake up[4].

Critical Section Problem

A critical section is a part of the code where shared data can be manipulated and a possible race condition may occur. The critical section problem is to create a procedure where processes can synchronize their activities to jointly share data.

Following conditions are required to deal with critical section problem:

Mutual exclusion–only one process is active inside the critical section.
Progress–programs will jointly decide which process will get inside a critical section.
Bounded waiting–how long a program must wait before it can get inside critical section[5].

Race Condition, mutex lock and critical section problem which were discussed in above paragraphs are demonstrated and explained below.

This program will show what is happening when mutex lock is not used.

As per Figure 2.2,we can see that race condition starts when both threads t1 and t2 race towards the shared variable “x”. Both threads entering now the critical section of the code at line 15.
Without the lock,both treads can write in the accumulated register at the same time which will affect the result.

This behavior is noticeable in Figure 2.3 below.

Figure above shows that not a single result is this same and is far from the expected outcome of 2000000. The result depends on which thread gets to the shared variable first (line 7, Figure 2.2) and then which is going to be executed first.
Highlighted in yellow is the moment when two threads entered the critical section at the same time.

Solutions to Critical Section Problem

There are two types of solutions to the critical section problem:

Hardware solutions
Software solutions

Hardware solutions are using memory barriers, compare-and-swap operations, and atomic variables[5].

A memory barrier is a type of instruction that makes a central processing unit (CPU) or compiler enforce an ordering constraint on memory operations issued before and after the barrier instruction[6].

“Compare and swap operation compares the value of a variable with an expected value, and if the values are equal then swaps the value of the variable for a new value[7].”

The atomic operation takes place when two operations running in parallel, a processor reads and writes a location during the same data transmission, and until this operation is completed, another input/output process cannot perform memory reading or writing tasks[8].

Software solutions are using mutex locks, semaphores, monitors, and condition variables.The code below demonstrates the use of mutex locks to address the critical section problem.

The code in Figure 2.4is almost the same as in Figure 2.2 with one significant difference – mutex lock.
Mutex lock() was introduced just before threads can enter the critical section (line 15 of the code) and then mutex unlock() was added at the end of the critical section.

This means that threads t1 and t2 still racing for that shared variable (line 11) but then whichever thread gets first into the critical section then it locks it and no other thread can be executed until that first one unlocks the critical section.

Figure 2.5 below show the considerable impact of the mutex locks.

Figure 2.5 shows that all results are the same and with the expected outcome of 2000000. Thread synchronization took place by the use of mutex.

Deadlock & Starvation

Deadlock and starvation are conditions where processes demanding a resource have been deferred for a long time but there are differences between these conditions.

Deadlock takes place when several processes hold a resource and wait to acquire a resource that is held by some other processes.
Figure 2.6 illustrates the deadlock situation.

Four conditions are required for the deadlock to take place:

Mutual exclusion–one process at a time can use a resource,and if another process needs to access the same resource, then it must wait until the other process releases it.
Hold and Wait–a process must hold a resource and wait to obtain another resource that is held by another process.
No Preemption–a process that holds the resources must release them voluntarily when it has completed its task.
Circular wait–a process must circularly wait for resources as per Figure 2.6.

Starvation happens when processes with high priorities constantly use resources, which prevents low priority processes from obtaining them or when a process is never given the resources it requires for execution because of faulty resource allocation judgments[9].

I hope that you have enjoyed this post, please let me know what you think about it in the comments section below.

If you wish to study thread synchronization in depth then here are the sources I used to create this post:

[1] Tutorialspoint.com. n.d. Operating System - Multi-Threading. [online] Available at:https://www.tutorialspoint.com/operating_system/os_multi_threading.htm [Accessed 3 December 2021].
[2] Barnes, R., 2018. Race Condition, Critical Section and Semaphore. [online]Tutorialspoint.com. Available at: section-and-semaphore> [Accessed 15 November 2021].
[3] Tanenbaum, A.S. and Bos, H., 2015. Modern operating systems. 4th ed. Pearson, pp.135,pp850.
[4] GeeksforGeeks. 2021. Mutex vs Semaphore - GeeksforGeeks. [online] Available at:https://www.geeksforgeeks.org/mutex-vs-semaphore/ [Accessed 6 December 2021].
[5] Silberschatz, A., Galvin, P. and Gagne, G., 2018. Operating system concepts. 10th ed.
Hoboken, N.J.: Wiley, pp.55, pp.106-110, pp.287.
[6] En.wikipedia.org. n.d. Memory barrier - Wikipedia. [online] Available at: lso%20known,and%20after%20the%20barrier%20instruction.> [Accessed 20 November 2021].
[7] Jenkov, J., 2021. [online] Tutorials.jenkov.com. Available at:http://tutorials.jenkov.com/java-concurrency/compare-and-swap.html [Accessed 20 November 2021].
[8] Techopedia.com. 2011. What is an Atomic Operation? - Definition from Techopedia.[online] Available at: https://www.techopedia.com/definition/3466/atomic-operation[Accessed 20 November 2021].
[9] www.javatpoint.com. n.d. Difference between Deadlock and Starvation - javatpoint.[online] Available at: https://www.javatpoint.com/deadlock-vs-starvation [Accessed 21 November 2021].

Header picture thanks to the https://pixabay.com/images/id-4854847/

Processes within the Linux Operating System.

Michal Gornicki — Mon, 31 Jan 2022 16:02:02 +0000

This post will explore the following topics: Process Management, Process Creation, Process Scheduling, and Process Destruction.

Process Management

"Process management includes creating and deleting processes and providing mechanisms for processes to communicate and synchronize with each other"[1].

A process is a running program (active entity). The execution of processes must be sequential, a program counter specifies the next instruction to execute and the associated resources. A single process cannot execute its instructions in parallel. Once an executable file has been loaded into memory, a program becomes a process[1].

The memory layout of a process is typically represented by multiple sections and is shown in Figure 1.1.

These sections include:
• Text section — the executable code
• Data section — global variables
• Heap section — when the program is running, memory is dynamically allocated
• Stack section — this is temporary data storage when using functions (such as function parameters, return addresses, and local variables)

Processes change their states as they execute. The state of a process is partly defined by the activity of that process. The following are possible states for a process as shown in Figure 1.2:

• New – a process is created
• Running – instructions are executed
• Waiting– a process is waiting for some event to occur (such as an Input/Output (I/O) completion or reception of a signal)
• Ready– a process is waiting to be allocated to a processor
• Terminated– a process is finished

All operating systems have the same states they represent, but their names may vary.

Every process in the operating system is represented by a Process Control Block (PCB)—also called a task control block. Each process has a process ID (PID).

There are many pieces of information related to a specific process, among which are these:

• Process state – i.e., new, ready, running, waiting, halted, etc.

• Program counter – it specifies the address of the next instruction to be executed for a process. This state must be saved during an interruption for a process to continue correctly.

• Central Processing Unit (CPU) registers – depending on the computer architecture, registers differ in number and type, i.e.: accumulators, index registers, stack pointers. Just like the program counter, this state information must be saved during
an interrupt occurs, otherwise, a process will not continue correctly when it is rescheduled to run.

• CPU-scheduling – process priority information, scheduling queues and schedule parameters can be found here.

• Memory-management – depending on the memory, which is used by OS, here we can find information about limit registers and the page tables, the segment tables, or the value of the base.

• Accounting – here is information about real-time CPU usage, time constraints, process numbers, etc.

• I/O status – information about I/O devices assigned to the process, a list of open files, etc.

In summary, a PCB as shown in Figure 1.3, is the source of information needed to start or restart a process.

Process management in Linux OS views each single-threaded process, or every thread within a multithreaded process or the kernel—as a distinct task.
A process is then exemplified via two key elements, the process control block and the additional information describing the user address space.
PCB is always in memory, but the latter data can be paged in and out of memory[2].

Process Creation

Process creation is replicating the Process Control Block by using fork() system call. Process creation is called the parent process whereas the created process is called the child process.
The parent process can have many children, but the child process can only have one parent.
Parent and child processes share all resources but, they have distinct address spaces.
Figure 1.4 represents process creation using fork().

System call fork() creates a new process, then exec() system call replaces process memory with a new program. The parent calls the wait() process while it waits for the child to terminate[3].

Process Scheduling

Often there are multiple processes requiring access to the CPU at this same time. The objective of the process scheduler is to maximize the use of a microprocessor by deciding which of the processes in the queue must be executed next.
The scheduler maintains the queues of processes:

• Ready queue – all processes in main memory, ready and waiting to execute.
• Wait queue – processes waiting for an event (i.e., I/O).

The ready queue can be implemented as a first-in, first-out (FIFO) queue, a priority queue, a tree, or just an unordered linked list.

Types of schedulers:

• Long term(job scheduler) – it picks processes from the ready queue and loads them into memory for execution.

• Medium-term(swapping) – it removes processes from the memory which reduces the degree of multiprogramming.

• Short term(CPU scheduler) – it picks the process ready to be executed next and allocates CPU.

The context switch in OS is an integral part of multitasking. It saves and restores the state of the CPU in the Process Control Block so that the process can be continued from the same point later stage. Context switch allows many processes to share a single CPU.

A Process Scheduler plans various processes to be allocated to the CPU based on scheduling algorithms.
These algorithms are either non-preemptive (once a process enters the running state, it can’t be preempted up until it finishes its assigned time) or preemptive (is based on priority where a scheduler may preempt a low priority running process at any moment when a high priority process arrives at a ready state).

Process scheduling algorithms:

• First-Come, First-Served (FCFS) Scheduling – this is a non-preemptive, pre-emptive scheduling algorithm and it is based on FIFO (First In First Out) queue. Due to high wait time, this algorithm has very poor performance.

• Shortest-Job-Next (SJN) Scheduling – this is a non-preemptive, pre-emptive scheduling algorithm. Gives a minimum average waiting time for a given set of processes but it requires knowing CPU time in advance.

• Priority Scheduling – this is a non-preemptive algorithm. Processes are given a priority and the process with the highest will be executed first and then next after that. Priority requirements can be based on memory, time etc.

• Shortest Remaining Time(SRT) – this is a preemptive scheduling algorithm. Processors are assigned to the jobs next to completion, however, they can be preempted by a newer job with a shorter completion time. Same as the SJN algorithm, it requires CPU time to be known.

• Round Robin(RR) Scheduling – this is a preemptive scheduling algorithm. Each process is given a set time to execute. Once a process is executed for that length of time then it is preempted and the next process is executed for its given time.

• Multiple-Level Queues Scheduling – each queue is the combination of existing algorithms with similar characteristics. Each queue has its priorities assigned[4].

Process Destruction

A process is destroyed when the execution of code, which was expected to run, terminates.
The process will expire voluntarily or involuntarily.

Voluntarily:
• Normal exit – process terminates because it has completed its task.
• Error exit – process finds a serious error.

Involuntary:
• Fatal error – termination caused by a program bug.
• Killed by another process – process runs a system call telling the operating system to terminate other processes as well.

I hope that you have enjoyed this post, please let me know in the comments section.

Here are the sources I used to create this post:

[1] Silberschatz, A., Galvin, P. and Gagne, G., 2018. Operating system concepts. 10th ed. Hoboken, N.J.: Wiley, pp.55, pp.106-110, pp.287.
[2] Tanenbaum, A.S. and Bos, H., 2015. Modern operating systems. 4th ed. Pearson, pp.135,pp850.
[3] Meador, D., 2018. Process Creation vs Process Termination in Operating System. [online]
Tutorialspoint.com. Available at: https://www.tutorialspoint.com/process-creation-vsprocess-termination-in-operating-system
[4] Tutorialspoint.com. Operating System - Process Scheduling. [online] Available at: https://www.tutorialspoint.com/operating_system/os_process_scheduling.htm