DEV Community: Aghyad Khlefawi

[Boost]

Aghyad Khlefawi — Thu, 08 May 2025 06:59:44 +0000

Aghyad Khlefawi

May 7 '25

Under the hood: What can you learn by building an HTTP Server from scratch?

#dotnet #programming #webdev #csharp

Comments

14 min read

Under the hood: What can you learn by building an HTTP Server from scratch?

Aghyad Khlefawi — Wed, 07 May 2025 17:56:04 +0000

Introduction:

I've always been curious about how most of the technologies I use on a day-to-day basis work. One of the things we as programmers have to interact with daily is HTTP servers. Most of the time, we don't think much about it since HTTP has been around for a long time, and there are thousands of HTTP servers and clients, so most people don't give much thought to how these technologies work!

As someone who worked on many web-based applications and built many restful APIs, I would like to think that I have a pretty good understanding of how the HTTP protocol works and how HTTP servers generally function, however, since I've always been using ready-made HTTP servers (Mostly Kesterl, IIS and Nginx) and HTTP clients (curl, postman, httpie) I felt that there's a lot that I can learn by writing an HTTP server from scratch, and so in this article, I will take you through my small HTTP server project that I've written and hopefully I will be able to share with you all the new things I got to learn along the way.

It's just text!

As you might already know, HTTP stands for HyperText Transfer Protocol, and it's simply one of the core protocols powering the internet and transferring data between your devices and servers all over the globe.

Just by reading the name "HyperText Transfer Protocol" we can get a few clues as to what HTTP is and how it works. To put it simply, it's a protocol that allows us to transfer text!

But could it be that simple? Per estimates, there are currently around 75 billion devices connected to the internet and over 1.1 billion websites accessible. Is it all running by simply sending text back and forth between servers and clients? Well, basically yes (for the most part).

For us to understand more why HTTP is so popular, we need to understand a few things about HTTP, and hopefully by the end of the article, we will have a clear picture of why HTTP to this day remains the most dominant protocol for web apps and server-to-client communication.

To avoid confusion about how HTTP works, let's first try to understand what HTTP is and what HTTP is not.

HTTP is not a transport protocol, it is an application layer protocol. This means that HTTP depends on a transport layer protocol (such as TCP/IP) to send and receive the data packets.
HTTP is designed to work with a client and server model and expects the client to initiate a request and a server to send a response back to the client, so HTTP is not optimized for real-time communication (Although it's capable of it, there are better alternatives)
HTTP is not a secure protocol by default, since we are sending plain text over the wire, anyone with access to the transported data will be able to read the contents, so the HTTPS (HTTP + SSL/TLS) protocol was later introduced to provide a security through encryption on top of HTTP

So, how does it all work?

As we have already established, HTTP works by transferring text with a request-response model, and for it to be supported on billions of devices and websites, HTTP needs to behave the same across all servers and clients and so there are specific rules that these servers and clients need to follow.

We've already established that the request and response messages are transferred as plain text, so how can the servers and clients parse these messages regardless of which HTTP server or client you are using?
Well, that's where the "Protocol" part comes into the picture. HTTP is a standard that's maintained and documented by the IETF HTTP Working Group, and full documentation of the standard can be found here if you're curious to see more details.
As long as the client and server are following the rules of the HTTP protocol, they should be able to communicate.

The Anatomy of an HTTP Message

Let's dig deeper into the HTTP message and the content it holds

Both the request and response have a pretty similar structure

1- Description line: A single line of text that specifies the version of the protocol, then the route and HTTP method in the request, and the status code in the response
2- Headers: (Optional) A set of headers, each single line is a single header, and each header consists of a key and value pair separated by a colon. These headers are supposed to add more details about the request/response, such as the format of data being transferred.
3- Empty line: The purpose of this line is to indicate the end of the message metadata and the start of the message content. To be more accurate, this line is represented as \r\n\r\n (section 4.1 of RFC 2616), which will be important later.
4- Message body: (Optional) If the message contains any content, it will be included in this part. Usually, the headers will help us identify whether the message also includes a body.

Now that we understand what HTTP messages look like and how they're supposed to be formatted, our HTTP server should just be able to read messages with this format and respond in the same expected format to the client.

Let's start coding!

For this project, I will be using .NET 9 to write the server, although there are many libraries already available in .NET to provide such functionality, my goal here is learning, and not necessarily taking the easy path.

I will be mainly utilizing a TcpListenter class to handle the TCP communication part, as I'm not planning to rewrite the whole TCP stack from scratch (not yet).

And this is what the first draft of my project looks like Github repo
Don't worry, I will go over the code next and explain every function!

using System.Net;
using System.Net.Sockets;
using System.Text;
using Serilog;
using Serilog.Core;

public class SiriusServer
{
  public SiriusServer()
  {
    _logger = new LoggerConfiguration().MinimumLevel.Debug().WriteTo.Console().CreateLogger();
  }

  readonly Logger _logger;

  private async Task HandleRequest(TcpClient tcpClient)
  {
    try
    {
      // Get the network stream
      await using var networkStream = tcpClient.GetStream();


      // Parse the headers
      var buffer = new byte[1024];
      byte[] bodyBuffer = null;
      var bytesRead = 0;
      var headerCompleted = false;
      var headerSb = new StringBuilder();

      while (!headerCompleted && (bytesRead = await networkStream.ReadAsync(buffer.AsMemory(0, buffer.Length))) > 0)
      {
        // Fine the end of the headers indicated by the \r\n\r\n sequence 
        var headerTerminatorIndex = GetHeaderTerminaorIndex(buffer, bytesRead);

        // Headers not finished
        if (headerTerminatorIndex < 0)
        {
          // Add header chunk - as per the standards, the header should be encoded using ASCII. which is why we can't have UTF characters in the headers
          headerSb.Append(Encoding.ASCII.GetString(buffer, 0, bytesRead));
          continue;
        }

        // Headers end detected
        headerCompleted = true;

        // Add header chunk
        headerSb.Append(Encoding.ASCII.GetString(buffer, 0, headerTerminatorIndex));

        // Check if any body data was also read in the buffer and store it in a buffer
        var bodyBytesLength = bytesRead - (headerTerminatorIndex + 4);
        if (bodyBytesLength > 0)
        {
          bodyBuffer = new byte[bodyBytesLength];
          Array.Copy(buffer, headerTerminatorIndex + 4, bodyBuffer, 0, bodyBytesLength);
        }
      }

      // Parse the headers into a dictionary
      var headerLines = headerSb.ToString().Split(["\r\n"], StringSplitOptions.None);

      var descriptionLine = headerLines[0];
      _logger.Debug("Request description line read: {line}", descriptionLine);

      var headers = new Dictionary<string, string>();
      foreach (var line in headerLines.Skip(1))
      {
        if (string.IsNullOrEmpty(line))
          break;
        var headerData = line.Split(':');
        headers[headerData[0]] = headerData[1];
        _logger.Debug("Request header read: {line}", line);
      }

      // Check if the message has body and read it
      if (headers.TryGetValue("Content-Length", out var value))
      {
        // Copy any data that was read while parsing the headers
        var contentLength = int.Parse(value);
        buffer = new byte[contentLength];
        var totalRead = bodyBuffer?.Length ?? 0;
        if (bodyBuffer != null)
        {
          Array.Copy(bodyBuffer, 0, buffer, 0, bodyBuffer.Length);
        }

        // Read the rest of the body content
        while (totalRead < contentLength)
        {
          totalRead += await networkStream.ReadAsync(buffer.AsMemory(totalRead, contentLength - totalRead));
        }

        // I'm assuming that the body will be encoded using utf8, this can be enhanced later by reading the charset from the headers
        var requestBody = Encoding.UTF8.GetString(buffer);
        _logger.Debug("Body content: {body}", requestBody);
      }

      // Send back a response
      var response = "Hello, World!";
      var responseSb = new StringBuilder();
      responseSb.AppendLine("HTTP/1.1 200 OK");
      responseSb.AppendLine("Content-Type: plain/text");
      responseSb.AppendLine($"Content-Length: {Encoding.UTF8.GetByteCount(response)}");
      responseSb.AppendLine("Connection: close");
      responseSb.AppendLine();
      var headerBytes = Encoding.ASCII.GetBytes(responseSb.ToString());
      var bodyBytes = Encoding.UTF8.GetBytes(response);
      await networkStream.WriteAsync(headerBytes);
      await networkStream.WriteAsync(bodyBytes);
    }
    catch (Exception ex)
    {
      _logger.Error(ex, "An error occured while processing the request");
    }
  }

  private int GetHeaderTerminaorIndex(byte[] buffer, int bytesRead)
  {
    for (int i = 0; i < bytesRead - 3; i++)
    {
      // Determine the location of the end of headers indicated by the sequence \r\n\r\n
      if (buffer[i] == '\r' && buffer[i + 1] == '\n' && buffer[i + 2] == '\r' && buffer[i + 3] == '\n')
      {
        return i;
      }
    }
    return -1;
  }

  public async Task StartServer(int portNumber, CancellationToken cancellationToken)
  {
    var tcpListener = new TcpListener(IPAddress.Any, portNumber);

    try
    {
      tcpListener.Start();
      _logger.Information("Server started at port {Port}", portNumber);
      while (!cancellationToken.IsCancellationRequested)
      {
        var tcpClient = await tcpListener.AcceptTcpClientAsync(cancellationToken);
        _ = HandleRequest(tcpClient);
      }
    }
    catch (Exception ex)
    {
      _logger.Error(ex, "An error occured while starting the server");
    }
    finally
    {
      tcpListener.Stop();
    }
  }
}

class Program
{
  public static async Task Main()
  {
    await new SiriusServer().StartServer(8000,CancellationToken.None);
  }
}

So, what is all this code doing? Let's get into it

public async Task StartServer(int portNumber, CancellationToken cancellationToken)
{
  var tcpListener = new TcpListener(IPAddress.Any, portNumber);

  try
  {
    tcpListener.Start();
    _logger.Information("Server started at port {Port}", portNumber);
    while (!cancellationToken.IsCancellationRequested)
    {
      var tcpClient = await tcpListener.AcceptTcpClientAsync(cancellationToken);
      _ = HandleRequest(tcpClient);
    }
  }
  catch (Exception ex)
  {
    _logger.Error(ex, "An error occured while starting the server");
  }
  finally
  {
    tcpListener.Stop();
  }
}

This is the first part of the server getting executed, it creates a new TCP listener provided by the .NET System.Net.Sockets library, and what it does is that it starts listening on the desired port we provided to the server. The AcceptTcpClientAsync function accepts a connection request asynchronously, and whenever a new connection request is received, it will execute the HandleRequest function. There's also some exception handling around the TCP listener start since there are some scenarios that it might throw an exception, if, for example, the desired port is already being used by another process or if the process is unable to listen to the port for some other reason.

Once we receive a connection request, the HandleRequest function will start executing, and it will do the following:

await using var networkStream = tcpClient.GetStream();

First things first, we will grab the underlying network stream managed by the TCP client. This network stream will allow us to read and write data using the TCP connection.

Now that we have a way to read the data, the next few lines will read the request message by reading and parsing the headers portion of the request

var buffer = new byte[1024];
byte[] bodyBuffer = null;
var bytesRead = 0;
var headerCompleted = false;
var headerSb = new StringBuilder();

while (!headerCompleted && (bytesRead = await networkStream.ReadAsync(buffer.AsMemory(0, buffer.Length))) > 0)
{
  // Fine the end of the headers indicated by the \r\n\r\n sequence 
  var headerTerminatorIndex = GetHeaderTerminaorIndex(buffer, bytesRead);

  // Headers not finished
  if (headerTerminatorIndex < 0)
  {
    // Add header chunk - as per the standards, the header should be encoded using ASCII. which is why we can't have UTF characters in the headers
    headerSb.Append(Encoding.ASCII.GetString(buffer, 0, bytesRead));
    continue;
  }

  // Headers end detected
  headerCompleted = true;

  // Add header chunk
  headerSb.Append(Encoding.ASCII.GetString(buffer, 0, headerTerminatorIndex));

  // Check if any body data was also read into the buffer and store it in a buffer
  var bodyBytesLength = bytesRead - (headerTerminatorIndex + 4);
  if (bodyBytesLength > 0)
  {
    bodyBuffer = new byte[bodyBytesLength];
    Array.Copy(buffer, headerTerminatorIndex + 4, bodyBuffer, 0, bodyBytesLength);
  }
}

Since we don't know the size or length of the headers beforehand, we will be reading the data from the client in chunks of 1024 bytes until we encounter the header terminator index, which, as explained earlier, is a sequence of "\r\n\r\n"

As that's happening, we will read the chunk of bytes, then convert it to a string using ASCII encoding, which, according to the HTTP standard, is the encoding that should be used for the HTTP message headers section.

This is why you cannot include Unicode characters directly in the URL or cookies without doing a URL encoding first.

if (headerTerminatorIndex < 0)
{
  // Add header chunk - as per the standards, the header should be encoded using ASCII. which is why we can't have UTF characters in the headers
  headerSb.Append(Encoding.ASCII.GetString(buffer, 0, bytesRead));
  continue;
}

As we are reading these chunks of data, we are using a string builder to append the chunk to form the full headers section once we reach the terminator index.

// Check if any body data was also read into the buffer and store it in a buffer
var bodyBytesLength = bytesRead - (headerTerminatorIndex + 4);
if (bodyBytesLength > 0)
{
  bodyBuffer = new byte[bodyBytesLength];
  Array.Copy(buffer, headerTerminatorIndex + 4, bodyBuffer, 0, bodyBytesLength);
}

One thing to take note of during this operation is that since we are reading the data in chunks and we have no idea how long the headers are, the last chunk of data we read might include some data of the message body as well. That is why we are keeping track of that in a separate bodyBuffer array that we will use later to combine with the message body.

      // Parse the headers into a dictionary
      var headerLines = headerSb.ToString().Split(["\r\n"], StringSplitOptions.None);

      var descriptionLine = headerLines[0];
      _logger.Debug("Request description line read: {line}", descriptionLine);

      var headers = new Dictionary<string, string>();
      foreach (var line in headerLines.Skip(1))
      {
        if (string.IsNullOrEmpty(line))
          break;
        var headerData = line.Split(':');
        headers[headerData[0]] = headerData[1];
        _logger.Debug("Request header read: {line}", line);
      }

Now that we are done reading the headers section, we can split it into individual header entries by reading each individual line, knowing that each line is terminated with a sequence of "\r\n" and then each key value entry is separated by a Colon. By the end of that snippet, we will have first a description line which contains the HTTP method, URL, and the protocol version, as well as a header dictionary that we can use to access the provided headers easily.

      // Check if the message has a body and read it
      if (headers.TryGetValue("Content-Length", out var value))
      {
        // Copy any data that was read while parsing the headers
        var contentLength = int.Parse(value);
        buffer = new byte[contentLength];
        var totalRead = bodyBuffer?.Length ?? 0;
        if (bodyBuffer != null)
        {
          Array.Copy(bodyBuffer, 0, buffer, 0, bodyBuffer.Length);
        }

        // Read the rest of the body content
        while (totalRead < contentLength)
        {
          totalRead += await networkStream.ReadAsync(buffer.AsMemory(totalRead, contentLength - totalRead));
        }

        // I'm assuming that the body will be encoded using utf8, this can be enhanced later by reading the charset from the headers
        var requestBody = Encoding.UTF8.GetString(buffer);
        _logger.Debug("Body content: {body}", requestBody);
      }

As mentioned earlier the request body is an option part of the HTTP request message and if the request is to include a body then it's responsibility of the HTTP client to specify that information in the header by providing a Content-Type, which indicates the MIME type of the content provided in the message body as well as the Content-Length wich specifies the length of that content in bytes.
That's why the server will first check if the Content-Type header is present, which in turn will let us know if the message has a body or not.
Once that's determined, we can easily read the request body by first reading the Content-Length header and then reading that number of bytes from the network stream.

while (totalRead < contentLength)
{
  totalRead += await networkStream.ReadAsync(buffer.AsMemory(totalRead, contentLength - totalRead));
}

Having the content length for the body helps us avoid reading the body in chunks in the way we did for the header. Since we know exactly how many bytes we need to read, we can do that in a more streamlined approach.

var requestBody = Encoding.UTF8.GetString(buffer);

Finally, we can read the content of the body by decoding the byte buffer.

Note that in this implementation, I'm assuming that the content is encoded using UTF-8 encoding. However, that might not be the case for all requests, and a better approach would be to check for the charset parameter that might be included in the Content-Type header, e.g. "Content-Type: text/html; charset=utf-8"

// Send back a response
var response = "Hello, World!";
var responseSb = new StringBuilder();
responseSb.AppendLine("HTTP/1.1 200 OK");
responseSb.AppendLine("Content-Type: plain/text; charset=utf-8");
responseSb.AppendLine($"Content-Length: {Encoding.UTF8.GetByteCount(response)}");
responseSb.AppendLine("Connection: close");
responseSb.AppendLine();
var headerBytes = Encoding.ASCII.GetBytes(responseSb.ToString());
var bodyBytes = Encoding.UTF8.GetBytes(response);
await networkStream.WriteAsync(headerBytes);
await networkStream.WriteAsync(bodyBytes);

Now that we are done reading the request, all that's left to be done is to send the response back to the client. To do so, we can use a StringBuilder to build the response content as per the expected format, and then we can encode it and send it back using the same network stream. Again, in this part, you can notice that the headers part is encoded using ASCII as per the standard.

An additional header I'm adding to the response is the Connection header. This header is used to communicate between the client and server whether the connection should stay open after the transaction is done. In this case, I'm specifying that the connection will be closed. Another option is to allow the same connection to be utilized again for other requests by providing the value of "Keep-Alive"; however, I won't be implementing that functionality for now.

Fire it up!

Once you run the project, you should be getting the message (Assuming you don't have other services listening on port 8000)
Server started at port 8000

Now we can go ahead and send a test request

We can see that our client is receiving the expected response message with the correct headers and body.

On the server side, we can see the logs getting generated and the server being able to read and parse the headers and body as expected

Add some syntax sugar to it 🍭

After that's done, I've spent a little time refactoring the code and adding some wrappers to make working with the server easier, This was the end result!

List<TodoItem> _todoItems = [];

await new SiriusServer()
  .AddRoute("GET", "/home", async request =>
  {
    if (request.QueryParameters.TryGetValue("name", out var name))
      await request.WriteTextResponse(200, $"Hello, {name}");
    else
      await request.WriteTextResponse(200, $"Hello, world!");
  })
  .AddRoute("GET", "/todo", async request => await request.WriteJsonResponse(200, _todoItems))
  .AddRoute("POST", "/todo", async request =>
  {
    var requestStringContent = await request.ReadBodyAsString();
    if (requestStringContent == null)
    {
      await request.WriteTextResponse(400, "Todo item must be provided in the request body.");
      return;
    }

    var todoItem = JsonConvert.DeserializeObject<TodoItem>(requestStringContent);
    if (todoItem == null)
    {
      await request.WriteTextResponse(400, "Todo item must be provided in the request body in a JSON format.");
      return;
    }

    todoItem.Id = _todoItems.Count;
    _todoItems.Add(todoItem);

    await request.WriteJsonResponse(201, todoItem);
  })
  .AddRoute("PUT", "/todo/{id}", async request =>
  {
    var itemId = request.RouteParameters["id"];
    var item = _todoItems.FirstOrDefault(e => e.Id == int.Parse(itemId));
    if (item == null)
    {
      await request.WriteTextResponse(404, "Item with the provided id not found");
      return;
    }

    var requestStringContent = await request.ReadBodyAsString();
    if (requestStringContent == null)
    {
      await request.WriteTextResponse(400, "Todo item must be provided in the request body.");
      return;
    }

    var todoItem = JsonConvert.DeserializeObject<TodoItem>(requestStringContent);
    if (todoItem == null)
    {
      await request.WriteTextResponse(400, "Todo item must be provided in the request body in a JSON format.");
      return;
    }

    item.Title = todoItem.Title ?? item.Title;
    item.Done = todoItem.Done;
    await request.WriteTextResponse(200, "Item updated");
  })
  .AddRoute("DELETE", "/todo/{id}", async request =>
  {
    var itemId = request.RouteParameters["id"];
    var item = _todoItems.FirstOrDefault(e => e.Id == int.Parse(itemId));
    if (item == null)
    {
      await request.WriteTextResponse(404, "Item with the provided id not found");
      return;
    }
    _todoItems.Remove(item);
    await request.WriteTextResponse(200, "Item deleted");
  })
  .StartServer(8000);

I have decided to go with a fluent builder pattern to make setting up the server easier.
I also have a request wrapper (Similar to ASP's HttpContext) that will be passed to each route, allowing me to read the request content as well as write the response back to the client in a more convenient way.
Finally, I added a router component that does a simple pattern matching and decides the correct route handler to execute.

What to do next?

Well, I encourage you to check out the code repository, see how these features are working, and better yet, fork the repository, experiment with it, and add some features. The implementation is still missing a lot of important features that you can improve your skills by implementing.
The following comes to mind:

TLS/SSL support
A more standardized response pattern
Better routing with route caching support
Middleware support
Authentication
Multithreading Or any other feature you think you could learn something new by implementing.

Final thought

Now, to answer the question I stated earlier in the article, why is HTTP so popular?
Well, in my opinion, it's the simplicity! HTTP is simple to implement, it's human-readable and simple to understand, and any device that can connect to the internet and parse text should be able to utilize it.

I hope you have learned something new about HTTP or .NET while reading this article. If so, let me know. I'm planning to focus more on the more advanced "under the hood" topics of software going forward, since I had noticed a lack of resources myself when trying to learn about these topics earlier in my career.

Keep on learning!

The second part of my containerization series is here! let's explore how to deploy containers on Azure

Aghyad Khlefawi — Sat, 22 Mar 2025 10:05:52 +0000

Containerization simplified: Part 2.a - Deploying containers to Azure

Aghyad Khlefawi ・ Mar 22

#azure #docker #dotnet #cloud

Containerization simplified: Part 2.a - Deploying containers to Azure

Aghyad Khlefawi — Sat, 22 Mar 2025 10:01:58 +0000

Intro

This article is another part of my containerization series, if you haven't yet, you can check out the previous parts here

Containerization simplified: Part 1.a - Containerizing a .NET app

In the previous part, we reviewed the steps required to containerize an application by creating a docker file and a container image. This article will explain the steps and resources needed to deploy the container image to Azure.

What are the components we need?

Let's go over the components needed to deploy a container to Azure before we go through the steps of deploying the container

Dockerfile: As explained in the previous part of the series, a dockerfile holds the instructions needed for docker to build a docker image that later allows a container runtime to pull the image and run it.

Docker build: Docker build is the process we will be using to interpret the dockerfile and copy the project files into a container image.

Container image: A container image is the executable package that contains everything our app needs to run, including the app executables and their dependencies.

Azure container registry: In any container deployment model, a container registry is a required component that allows you to store and distribute your container images. Since we are exploring the deployment option of Azure, then Azure container registry would be the most convenient option for us to use as it's integrated with the other Azure services we will be using. However, it's important to note that the Azure container registry is not the only option, and other options include:

Docker hub (Default docker repository)
Amazon Elastic Container Registry (AWS offering)
Google Artifact Registry (Google Cloud offering)
Harbor (Self-hosted and opensource option)

Azure container app: That will be the service that will eventually host and execute our container, there are many options provided by Azure to deploy your containers, although I won't be providing a full comparison between these services, I will give a brief explanation of the differences

Azure container instance: This is the simplest container service available on Azure. It is considered a low-level option since it doesn't offer any sort of orchestration or scaling capabilities. You provision a standalone container, and you pay for the instance you provision.

Azure container app: This service provides more capabilities than a container instance. It's built on top of Kubernetes and provides auto-scaling capabilities and service-to-service communication. It is much more suitable for microservices architecture. With this service, you pay for the execution time and resource consumption.

Azure Kubernetes Service: A fully fledged managed Kubernetes cluster with all the Kubernetes goodness you expect. Auto-scaling, Service-to-service communication, configurations, and secrets management as well as all the standard Kubernetes features. The option is more suited for larger and more complex systems and it requires Kubernetes experience from the teams utilizing it. With this option, you will pay per node VM, which will most likely be the most expensive option out of the three I mentioned.

If you're interested, a more comprehensive comparison is available here

Let's get to work!

The first thing we will be doing is creating a new Azure container registry, to do so, you can navigate to your Azure portal and search for container registry then click create.

You can choose the region that suits you but you should mind the registry name you enter since we will be using this name to tag the image later.
Once the container registry is created, we can go ahead and build our
image. To do so, we will navigate to our project directory (Source code available here) and execute the following command

docker build -t awesome-hr-app -f Dockerfile .

This will build our image and give it the tag "awesome-hr-app"

we can confirm that the image is created by running

docker image ls

now that we have the container image ready, we can push it to our container registry.
To do so, we first need to tag the image with a new tag that matches the name of our container registry. Usually, the image tag for the Azure container
registry should follow the following format
<Registry name>.azurecr.io/<Namespace>/<Image name>:<Version>
To tag our new image, we will execute

docker tag awesome-hr-app simplecontainers.azurecr.io/example/awesome-hr-app:latest

We can again confirm that the new tag is available by running

docker image ls

Now that we have our image tagged and ready, we can proceed to push it to our container registry.
First, make sure that you have the Azure CLI installed on your machine and you're logged in to your container registry

az login
az acr login --name simplecontainers

Once that's done, you can go ahead and push the image

docker push simplecontainers.azurecr.io/example/awesome-hr-app:latest

After the push operation is done, you will be able to see your container image in the container registry under the repository tab.

For demo purposes, we will update once last thing in the registry and that's to enable admin user access to the registry so we can deploy the container instance through the UI.

Deploying the container

As mentioned before, we have many options when it comes to deploying the containers, and for simplicity, I will be using the Azure container instance service to demonstrate this step.

So, let's head to Azure container instances and create a new one

I will leave all the default parameters, except for the image source, which will be an Azure container registry and the registry will be our newly created registry and image, as well as the port number under the networking tab which I will be changing to 8080 since that's the port our container is exposing.

After the resource creation has been completed, you should be able to see the new container instance and find the public IP address assigned to it

If you navigate to that IP address using your web browser, you should get the default response coming from your container!

And that's it! These are all the steps needed to deploy a container to Azure. The resources and configurations might be a little different from other cloud providers, however, the main idea and steps will remain the same. You will need to build an image, push it to a registry, and finally deploy it using a container runtime.

I will be exploring other cloud providers in the next parts such as Google Cloud and AWS as well as other Container services, so make sure you follow for more guides on containerization!

Containerization simplified: Part 1.a - Containerizing a .NET app

Aghyad Khlefawi — Sat, 15 Feb 2025 09:19:32 +0000

In this series of articles, I will provide a detailed step-by-step guide to enable you to containerize your application and deploy it on-premise or on any cloud platforms that support containers.
I will be using an example project to help me illustrate my points and help you understand the process better.

Prerequisites:

Some basic knowledge of docker fundamentals.
A machine running docker

if you don't have docker installed on your machine, you can follow the steps mentioned here to get docker up and running on your machine.

You can also download the source code I will be working with from this repository so you can follow along with the tutorial.

Why would you want to containerize your application?

Let’s start first by explaining why you would want to containerize your application.
Of course, there are many benefits to containerizing your application but in my opinion, the following are the most common reasons:

The first and most obvious benefit of containers is probably Portability. Being able to deploy your container image on any cloud platform or machine is super useful. Containers allow you to package your application binaries, dependencies, and configurations into one unit.
Scalability is another big benefit of containers. As long as your container image is designed correctly, you should be able to scale your system and spin up new containers very easily.
Being able to run your application or services inside a container provides a layer of Isolation that helps with decoupling services and isolates security vulnerabilities.

With that being said, this guide should help you containerize your application regardless of the goals you’re trying to achieve.

Let's start working!

In order to containerize an application, you will need to create a Dockerfile that contains the instructions that will allow Docker to build an image of your application, I will go step by step and explain the instructions used to build a container image.

In this example, I’m writing a dockerfile for a .NET application. However, the steps will be similar for other platforms and languages as well.

And so naturally the first step for us is to create a Dockerfile in our project. The full recommended dockerfile for an ASP .NET application (using .NET 8) which can be generated using Visual Studio or JetBrains Rider, looks something like this:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base  
EXPOSE 8080 
EXPOSE 8081 

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build 
ARG BUILD_CONFIGURATION=Release 
WORKDIR /src 
COPY ["HrApp.csproj", "./"] 
RUN dotnet restore "HrApp.csproj" 
COPY . . 
RUN dotnet build "HrApp.csproj" -c $BUILD_CONFIGURATION -o /app/build 

FROM build AS publish 
ARG BUILD_CONFIGURATION=Release 
RUN dotnet publish "HrApp.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false 

FROM base AS final 
WORKDIR /app 
COPY --from=publish /app/publish . 

RUN useradd -ms /bin/bash appuser
USER appuser

ENTRYPOINT ["dotnet", "HrApp.dll"]

I know this might look intimidating at first if you're not used to Dockerfiles, but don't worry we will go over the file line by line and explain what is it doing.

This particular dockerfile uses a multi-stage build, which will allow us to optimize the size of the final image by including only the necessary components in the final image.

So what do these lines mean?

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base

The first line of the docker file references the base image that we will also be using as the final image for our application. This image contains the runtime binaries required for our ASP application to run.
This image is created and maintained by Microsoft, although you can technically create your own image from scratch and then download the .NET binaries into it, it's much easier to use the official image and not have to worry about setting up the runtime yourself.

EXPOSE 8080 
EXPOSE 8081

These two lines state that the image will be exposing two ports 8080 and 8081. While the expose keyword doesn’t publish the port itself, it however serves as more of a documentation for the ports that the image users could connect to.
These ports of course could be different depending on your application framework so you can modify them to fit your use case.
In this specific example, the application will be using port 8080 for HTTP traffic and port 8081 for HTTPS traffic.

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build

At this point, we define the second stage of our image which is the build stage. we will be using the SDK base image from Microsoft which contains the necessary binaries required to build a dotnet core app.
Also, it's important to note that at this line, our image becomes a multistage image, I will be using a directory structure going forward to explain what these two images look like and how are our command going to be affecting the images.

ARG BUILD_CONFIGURATION=Release

The ARG keyword allows us to define arguments that could later on be passed to the image during the image build process, this allows us to change the behavior of the image being built based on these arguments. In this particular case, we are defining an argument for the build configuration that will be used by dotnet and we are giving it a default value of Release, so in case we want to build a version of the image with Debugging enabled, then we can pass the argument to the docker build command with a Debug value instead of Release.
This feature could be used to pass any argument you want to the image instead of hardcoding it and having to create a whole new image with a different value.

WORKDIR /src

Since the latest stage we have defined is the build stage, this command will be executed on it, and what it does is that it informs Docker that all the subsequent commands will be executed within the /src directory of the image. you can think of it as creating a directory in the image and then executing "cd" into that directory.

COPY ["HrApp.csproj", "./"]

This will copy the ".csporj" file of the project to the build image. now you might be wondering why are we only copying the ".csproj" file and not the whole project. Well, the reason is that in the next step, we will be using this file to execute "dotnet restore" command which will download all the dependencies packages defined in our ".csproj" file, the main reason for doing this step separately before building the project is to take advantage of the Docker caching capabilities, to put simply, Docker will perform a "dotnet restore" and if the next time we build the image, if it doesn't detect any changes to the ".csproj" file, then it will just reuse the cached layer from the previous build and will skip downloading the packages again. this technique can be used with most other frameworks/languages that have package systems and it results in a big time savings when building the image again in the future.

RUN dotnet restore "HrApp.csproj"

This will execute the restore command on our project file and dotnet will take care of downloading all the packages referenced in the project file.

COPY . .

Now that we have downloaded all the packages, we will go ahead with building the application, of course, to do so, we need to copy the rest of the source code files and that's essentially what this command is doing, it's copying all the file from the current host directory (our project directory) into the build image

RUN dotnet build "HrApp.csproj" -c $BUILD_CONFIGURATION -o /app/build

This command will execute the dotnet build process on our project file, you can also notice that we're passing the "$BUILD_CONFIGURATION" argument here to the process and we are specifying the output directory of the build process to be "/app/build"

FROM build AS publish 
ARG BUILD_CONFIGURATION=Release 
RUN dotnet publish "HrApp.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

Here we're defining yet another stage for publishing the application, the main reason that the build and publish phases are separated into two stages is to further take advantage of the Docker caching capabilities. Also in case we decide to target a different architecture or whether we want to have a self-contained deployment or a framework-dependent executable (UseAppHost=true)

A couple of things to note here, first we are specifying the output directory to be "/app/publish" and second is that we are specifying "UseAppHost=false" Since we are using an image that already contains the .NET runtime, we don't want our app to contain the runtime in its deployment as well which would be redundant and will take more space.

FROM base AS final

Now that the application is built and published, we can finally copy the application files from our build image into our base image.
This line will switch the context from the previous "build" image to the "base" image and so all the subsequent commands will be executed on the base image that we are now naming as final for better readability.

WORKDIR /app
COPY --from=publish /app/publish .

First, we are creating "/app" directory and setting it as the current working directory. Then after that, we copy the application files into the final image.
You can notice that here we are using a special "--from" parameter with the COPY command, allowing us to copy files between images/stages.

RUN useradd -ms /bin/bash appuser
USER appuser

Here we are creating and specifying the user that will be used to execute the subsequent RUN, ENTRYPOINT, and CMD commands in the dockerfile. This will help make sure that we are not running the application with a privileged user or root that could cause security vulnerabilities down the line.

ENTRYPOINT ["dotnet", "HrApp.dll"]

Finally, now that we have everything ready we can specify the entry point of our image, which will be executed whenever you run a new container using this image.
Since this example is using a dotnet application, we will be calling the dotnet CLI with the DLL of the application as an argument and that will take care of stating our application.

And that's it for creating the Dockerfile!

Let's test it out!

Now that we have the image ready, we can try building it and running a container to test it out.

To build the image, we need to execute the following command

docker build -t hrapp -f Dockerfile .

This will execute the docker build process and the "-t" flag will tag the resulting image with the tag "hrapp" that we can use to identify our image, also we are specifying the location of the docker file with the "-f" flag and lastly the "." specifies the build context which in our case is the project directory, and assuming you are executing the command from the project directory, our context should be the current directory with is "."

After the build is done, we should be able to spin up a new container using our newly created image

docker run -p 8080:8080 hrapp

This command should create a new container using our "hrapp" image and it will also bind the 8080 port of the container to our host machine

After the container starts running we can test that our application is running by calling

curl http://localhost:8080

That's it! you have successfully containerized your .NET app

What's next?

Well, the next step would be to deploy your containerized app on a hosting platform. In my future articles, I will be demonstrating how you can deploy your containers on cloud platforms such as Azure and AWS so make sure you follow me to get to the next step of the deployment process.