Forem: Tomaz Lovrec

ForwardAuth with Traefik: Streamlining Security for Microservices

Tomaz Lovrec — Fri, 11 Oct 2024 19:49:30 +0000

In the information age, nothing is more important than the security of our services—and more importantly, the security of our users and their data. Ensuring security within a (micro)services architecture can quickly become complex and burdensome. As services grow and more spring to life within the ecosystem, maintaining consistent and reliable access control becomes a top priority. To streamline access control, we can leverage Forward Authentication, which centralizes the authentication mechanism and simplifies securing our (micro)services.

While many reverse proxies offer functionality for routing and authentication, Traefik stands out with its ease of use and flexibility. In addition to efficiently routing traffic, Traefik’s integration with Forward Authentication (ForwardAuth) enables us to centralize user authentication across all services. Using a centralized authentication not only makes the access management easier, but also strengthens the security of our services at the gateway level, making Traefik an excellent choice for the task.

In this post, we will look into the process of setting up and configuring ForwardAuth with Traefik and explore some advantages of using this authentication method within a (micro)services architecture to secure access to a protected Order resource in our hypothetical application.

What is Authentication

First a quick look into what authentication actually is. When we ask our users to authenticate, we are essentially asking them to prove to our application that they are who they say they are. In the most basic form of authentication, the users often prove their identity by supplying our application with an email address, or a unique username, and a password. Since the communication between the user/client and the server in the application leveraging the HTTP protocol is more often than not stateless, the user must prove their identity with every request.

If an attacker can obtain the users password which they are using to prove their identity with, the attacker can now identify as the user to our application at any time, until the user changes their password. And since users must prove their identity with the password on every request, the attacker has a lot of chances to get to the users password. To mitigate this, the access control system in our application will usually issue a short lived access token to our user, after they have proven their identity with their password. After this point, the user can use this access token to prove their identity, until the token expires, and they have to obtain a new one.

What is Forward Authentication

When our application now receives a request to the protected GET /order/{id} resource endpoint, it verifies that the request also contains the access token, and it ensures that the token is valid and belonging to a user. Since we are in a (micro)services architecture and we are using multiple services to serve different resources to our users, as in example, the request to retrieve an order with the ID {id} is handled by the order service, we would typically need to implement identity verification in each service, or rather implement an authentication service which will verify the identity of the users for us through the POST /auth/verify endpoint.

Instead of having each service verify user identities by calling the authentication service to verify the users identity, which quickly becomes cumbersome and can lead to inconsistencies between services, we can employ the Forward Authentication mechanism in our reverse proxy, Traefik. When using ForwardAuth each request that is received to a protected URI, like in example GET /order/{id}, Traefik will automatically forward the request to our authentication service for user authentication, before sending the request onward to the resource service, in our example, order.

Configuring ForwardAuth in Traefik

Below we have hypothetical service and http router definitions for our authentication and order services and routers in Traefik:

[http]
  [http.routers]
    [http.routers.order]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/order`)"
      service = "order"
    [http.routers.authentication]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/login`)"
      service = "order"

  [http.services]
    [http.services.order.loadbalancer]
      [[http.services.order.loadbalancer.server]]
        port = 8000
    [http.services.authentication.loadbalancer]
      [[http.services.authentication.loadbalancer.server]]
        port = 8000

In this configuration we have configured 2 services that we are running with docker, order and authentication, and Traefik will route all requests to https://order.domain.tld/order to the order service and all requests made to https://order.domain.tld/login the authentication service. We do not need to route the /auth/verify route, since we are going to be calling this only inside the same docker network bridge.

With this setup, the order service would have to manually call https://authentication:8000/auth/verify manually on each request made to the /order/{id} endpoint, and of course any other endpoint or service would need to do the same. To centralize the authentication and not require each service to handle it individually, we are going to use ForwardAuth by defining a middleware in Traefik and add it to our router for the order service:

[http]
  [http.middlewares]
    [http.middlewares.auth-user.forwardauth]
      address = "https://authentication:8000/auth/verify"

  [http.routers]
    [http.routers.order-secure]
      rule = "Host(`order.domain.tld`) && PathRegexp(`/order/[0-9]+`)"
      service = "order"
      middlewares = ["auth-user"]
    [http.routers.order]
      # kept the same as before

  # services defined as before

We have not defined a new ForwardAuth middleware with the name auth-user, and instructed Traefik to redirect all requests made to all routers that employ this middleware to the https://authentication:8000/auth/verify address. Further on, we have now added a new router, order-secure which uses the auth-user middleware, and catches only requests that are made to https://order.domain.tld/order/{id} address while keeping the https://order.domain.tld/order requests non-authenticated.

Now whenever the order service receives a request to the /order/{id} URI, we know we can trust this request as it was already forwarded to our authentication service for user identity verification by Traefik and we can proceed servicing the request right away.

Sharing information between the services

In real-world scenarios, we might also want to share some user information from the authentication service to the order service once the user has been authenticated, since the authentication service will already have probably accessed the database, and we want to limit the access to the database in the downstream services in order to help maintain high performance.

To achieve this, we have a couple of options:

use of JSON Web Tokens or JWT
set any required data to the response headers with the authentication service

Use of JSON Web Tokens

If we are using JWTs for authentication of the users, we can already keep the required user data in the JWT itself, since it was designed for exactly this. When the user sends the JWT in the request headers, Traefik will naturally forward this JWT to the authentication service through the ForwardAuth middleware, as well as send this JWT on to the order service, where the authentication service can check the validity of the JWT token and the order service can extract user data from it.

Setting required data to response headers after authentication

Since JWTs expose user data, we might want to avoid that, and can therefore set any user data that the downstream services will require in the response headers of the /auth/verify call and instruct Traefik to add data from that specific header to the follow-up request headers that will be sent to the order service. Ideally in a way where the downstream services will be able to verify that the data was indeed set by the authentication service. We achieve this by adding a slight modification in our ForwardAuth middleware:

[http]
  [http.middlewares]
    [http.middlewares.auth-user.forwardauth]
      address = "https://authentication:8000/auth/verify"
      authResponseHeaders = ["X-Authenticated-User"]

# all else remains the same

Putting it all together

Now let’s put everything we have learned together:

[http]
  [http.middlewares]
    [http.middlewares.auth-user.forwardauth]
      address = "https://authentication:8000/auth/verify"
      authResponseHeaders = ["X-Authenticated-User"]

  [http.routers]
    [http.routers.order-secure]
      rule = "Host(`order.domain.tld`) && PathRegexp(`/order/[0-9]+`)"
      service = "order"
      middlewares = ["auth-user"]
    [http.routers.order]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/order`)"
      service = "order"
    [http.routers.authentication]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/login`)"
      service = "order"

  [http.services]
    [http.services.order.loadbalancer]
      [[http.services.order.loadbalancer.server]]
        port = 8000
    [http.services.authentication.loadbalancer]
      [[http.services.authentication.loadbalancer.server]]
        port = 8000

Note: the above configuration is omitting HTTPS configuration as it is beyond the scope of this post.

And here we have it, congratulations! We now have a secure GET /order/{id} endpoint in our order service, and to secure any more services or endpoints, we simply need to add the middleware to their route definitions. Now let's take look at the lifecycle of the GET /order/{id} request:

ForwardAuth with Traefik: Streamlining Security for Microservices

Tomaz Lovrec — Fri, 11 Oct 2024 19:49:30 +0000

What is Authentication

What is Forward Authentication

Configuring ForwardAuth in Traefik

Below we have hypothetical service and http router definitions for our authentication and order services and routers in Traefik:

[http]
  [http.routers]
    [http.routers.order]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/order`)"
      service = "order"
    [http.routers.authentication]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/login`)"
      service = "order"

  [http.services]
    [http.services.order.loadbalancer]
      [[http.services.order.loadbalancer.server]]
        port = 8000
    [http.services.authentication.loadbalancer]
      [[http.services.authentication.loadbalancer.server]]
        port = 8000

[http]
  [http.middlewares]
    [http.middlewares.auth-user.forwardauth]
      address = "https://authentication:8000/auth/verify"

  [http.routers]
    [http.routers.order-secure]
      rule = "Host(`order.domain.tld`) && PathRegexp(`/order/[0-9]+`)"
      service = "order"
      middlewares = ["auth-user"]
    [http.routers.order]
      # kept the same as before

  # services defined as before

Sharing information between the services

To achieve this, we have a couple of options:

use of JSON Web Tokens or JWT
set any required data to the response headers with the authentication service

Use of JSON Web Tokens

Setting required data to response headers after authentication

[http]
  [http.middlewares]
    [http.middlewares.auth-user.forwardauth]
      address = "https://authentication:8000/auth/verify"
      authResponseHeaders = ["X-Authenticated-User"]

# all else remains the same

Putting it all together

Now let’s put everything we have learned together:

[http]
  [http.middlewares]
    [http.middlewares.auth-user.forwardauth]
      address = "https://authentication:8000/auth/verify"
      authResponseHeaders = ["X-Authenticated-User"]

  [http.routers]
    [http.routers.order-secure]
      rule = "Host(`order.domain.tld`) && PathRegexp(`/order/[0-9]+`)"
      service = "order"
      middlewares = ["auth-user"]
    [http.routers.order]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/order`)"
      service = "order"
    [http.routers.authentication]
      rule = "Host(`order.domain.tld`) && PathPrefix(`/login`)"
      service = "order"

  [http.services]
    [http.services.order.loadbalancer]
      [[http.services.order.loadbalancer.server]]
        port = 8000
    [http.services.authentication.loadbalancer]
      [[http.services.authentication.loadbalancer.server]]
        port = 8000

Note: the above configuration is omitting HTTPS configuration as it is beyond the scope of this post.

Proper Way of Using a Makefile

Tomaz Lovrec — Fri, 29 Jan 2021 16:17:18 +0000

The Makefile has been with us for quite a long time. Primarily used with C or C++ software, but in the recent years it has seen use in projects using almost any programming language. And why not, it is a powerful tool. Although, I have seen many people arguing that "it is just another task manager", which is of course far from the truth.

I understand why you might think so, because like me, you are probably using make and the Makefile wrong. I knew that it is capable of doing things that need to be done and not simply do everything all the time, but I never bothered to actually dive into it to see how I can improve my build times. There are countless resources in the internet how to get you started with Makefile, but most if not all simply just present it as a task runner, even if they do comment that it is just a basic usage for it.

Basic usage is completely fine, but imagine you are creating a
build target to build multiple services that are built from the source code in a shared repository. You could rebuild all of them every time you change something, but why, if you only need to rebuild those that you actually changed? And here comes Makefile to the rescue. Lets start with a hypothetical source code structure:

my-awesome-project
|-dist/
|-pkg/
| |-libA/
|   `-libA.go
| |-libB/
|   `-libB.go
| `-libC/
|   `-libC.go
`-internal/
  |-serviceA/
  |  |-main.go
  |  `-functionality.go
  `-serviceB/
    |-main.go
    `-functionality.go

The general idea is, that we want to rebuild both services A and B if the libraries in the pkg directory change and rebuild only service A or B if their source files change. You might want a Makefile something like:

all: dist/serviceA dist/serviceB

dist/serviceA: internal/serviceA/*.go pkg/*/*.go
    go build -o dist/serviceA ./internal/serviceA/

dist/serviceB: internal/serviceA/*.go pkg/*/*.go
    go build -o dist/serviceB ./internal/serviceB/

The first line, all: dist/serviceA dist/serviceB is just an alias and allows you to run simply make and it will execute all of the targets listed on its line. The further lines are actual build targets, but they are named after the file that the build will produce followed by files that are used to build it. Using this format allows make to track the file change timestamps and when a run for a specific target is requested make will check if any of the specified files have a newer timestamp than the target file and only if they do will it run run that target.

Of course you can specify aliases for those as well so you do not need to type make dist/serviceA should you wish so:

serviceA: dist/serviceA

And now you can execute make serviceA and it will build service A, but only if the source has changed.

This can be applied to anything of course, like generating code, tests, etc. Of course this seems like an overkill for smaller projects and you will spend more time configuring and writing a Makefile than you will save by shorter build times, but if you have a larger project on hand it can be very beneficial to
have certain tasks run only if they are necessary.

Ancient art of Git-fu

Tomaz Lovrec — Tue, 28 Apr 2020 11:22:36 +0000

I have been using Git for quite some time now, my GitHub profile is almost 8 years old, and I have been using Git before joining GitHub for at least 2 years. I think I can safely say I have been using it for around 10 years. Not just as a contributor to the various repositories on Git, but also as a tool to help me debug an error in the application or library. You might wonder how Git could provide help with that, well, it holds the secrets to when something was changed, why it was changed, and by who it was changed. Its a treasure, and you should treat it like on as well.

Of course there are some unwritten rules or guidelines on how to treat your Git history like a treasure, and I will try to run through a couple of them.

Commit soon, commit often

This first guideline might seem a bit backward, since to keep the history clean you might want to reduce the number of commits, but committing sooner and more often will help your with writing the code, more specifically when you need to make alterations, because you've decided to design your code in a different way. So for now, do not worry how your history looks like, make commits as soon as some logical piece of your code is finished. If you later find out you don't need some piece of your code, you can simply remove that commit, and presto, that piece of code or that change of code is gone.

This will hopefully keep you from keeping up with another guideline, don't commit commented code. Seriously, just don't. When searching through the history you create a whole lot more false positives, extending the time to find what you are actually looking for in the history as all those commits which commit commented code also show up. You don't need to comment some old code in case you'll need it later or you're not sure about the change. That code you changed is still kept in the original form in git history, even if you don't commit anything, you can still find it by issuing a git diff -- filename command.

Clean up commits before publishing

If you are following the above guideline, you probably now have a pretty messy history on your hands. And hopefully you also haven't already have published your commits to the remote, and you have them only locally. It's time to clean them up. To start, execute git rebase --interactive, if you still have some uncommitted changes, commit them now, or stash them using git stash. The rebase command will open your git set editor with something similar to:

pick a4e64eb canged the error response text
pick 919f447 return an error when record not found
pick c7d7e82 bubble the error object up to the handler

# Rebase f2b16ac..c7d7e82 onto f2b16ac (3 commands)
#
# Commands:

... description of the commands follows bellow in the article ...

At the very beginning each line is one commit in the following form:

<command> <commit short hash> <commit message title>

To edit the history you simply edit the command for each line that you want to edit. Available commands are:

pick - use commit as is
reword - use commit as is but edit the commit message
edit - pause the rebase and allow for amending of the commit
squash - merge the commit with the previous commit
fixup - same as squash and use previous commits message
exec - execute the shell command found on the same line (add a new line with this command, i.e.: exec ls)
drop - remove the commit (removing the line will also remove the commit)

In the above example I would want to squash the 919f447 and c7d7e82 commits together, which would mean I would change the 3rd commits command from pick to squash or fixup, depending if I want to edit the commit message or not. After the change, simply save the file and quit the editor and rebase will run.

Finish your work before committing

Don't use git as a means to transfer your work from one machine to another. Or at least don't do this in any branches that are used by you or your team. If you absolutely HAVE to use git to transfer your edited files to a different machine then at least create a brand new branch, commit your changes there, and once you've transferred your work, remove that commit and branch from the remote immediately:

git push # I guess you will want to, but this step is optional
git checkout -b yourhandle_temp # create a new branch with your uncommited changes
git add . && git commit -m "transfering my work"

# on the other machine:
git fetch
git checkout yourhandle_temp
git push origin :yourhandle_temp # remove the remote branch
git reset HEAD~1 # remove the temp commit and leave files unstaged

Alternatives

A much more cleaner approach would be to stash your changes and export them to a file:

git stash
git stash show -p > some.patch

Now take this file to your other machine via a thumb drive or some file sharing service, or however you want and apply this patch on your other machine:

git apply some.patch

This way you are not polluting the remote with your temp commits or temporary branches.

Test your work before you publish

Always test your work before you publish your work. If you want to do yourself a favour, also test before committing, because it will save you some time needed to edit/squash the commits where you fix your newly created bugs right away.

Write sensible commit messages

There is literally nothing worse than a non-descriptive commit message when you need to inspect Git history. Imagine the following history:

...
* fd4befe 
|          [3 days ago]     Tomaz Lovrec: more work 
* 08a128a 
|          [3 days ago]     Tomaz Lovrec: fix 
* 84a43f1 
|          [3 days ago]     Tomaz Lovrec: work 
* d8de94b 
|          [3 days ago]     Tomaz Lovrec: fix 
...

And you are looking through the history trying to piece together when and where some change was made, to understand maybe why it was made. Now you have to open every commit and inspect all the changes in the commit. Painful work. And since all the commit messages are almost the same it is much harder to keep track of which you already inspected and remembering which does what.

This is why it is recommended to write commits in the following form:

short descriptive title, up to 60-80 chars

Longer description about what you did, why did you do it, what you were trying
to solve. Your goal here should be to explain the change enough that someone
inspecting your commit does not need to contact you. Although, do try and keep
it short, because no one has time to spend 5 minutes on each commits message.
And keep the lines shorter than 80 characters.

Furthermore the title should describe what you have done in the code, not the effect the change had. Instead of writing fixed the wrong error response write:

error response to ErrFoo in foo endpoint

The previous error message was false and did not properly describe the error to
the client. ErrFoo is a better alternative since it......

Conclusion

Those are just some of the guidelines you should keep in mind when working with Git in order to maintain some sensibility in your Git history and transmit your changes more effectively to the rest of your team, and also maybe to just get your co-worker of your back "bugging" you all the time why you did something.

There are a lot more guidelines, but most important is, that you and your team agree on them and follow them, even if you deem some of them unnecessary or stupid.

Do you have any other guidelines you think I should have mentioned? Please feel free to add them to the comments bellow!

My Go Toolset

Tomaz Lovrec — Fri, 17 Apr 2020 12:42:49 +0000

When developing some software, you very often tend to use some 3rd party tools or libraries to enable yourself to focus more on the task at hand. And this makes perfect sense, imagine if you had to write your own HTTP server everytime you wanted to develop a web application. Or a router, or, or, or... This would be insane and nothing would get done. Ever.

We as developers also grow used to certain tools, and don't switch much between them, unless we really have to due to many reasons. And here is the list of my tools and libraries that I tend to use, with short description of each of thembellow:

Lets dig in!

go-delve/delve - Debugging

When it comes to debugging Go applications, go-delve/delve is my go-to library. To start debugging your source code, simply execute:

dlv debug gitlab.com/youruser/project/

Or to debug a built binary:

dlv exec $GOPATH/bin/built_bin

Even debug your pesky tests:

dlv test gitlab.com/youruser/project

Now you can start setting breakpoints using break pkg_name.FuncName or break filename.go:<linenum> and then starting the execution by calling continue.

You can also start the debugging session with the --headless flag to start the debugger in headless mode and connect to it with your editor or IDE.

spf13/cobra - CLI commands

Creating a CLI interface to my applications is really simple when using the spf13/cobra library, all you need to do is execute:

cobra init nameofexec --pkg-name gitlab.com/yourname/yourproject

And cobra will create everything, the directory structure inside a new directory named nameofexec, the root command inside nameofexec/cmd/root.go, all you need to do is open the file, edit the descriptions and tell the command what you want it to actually do.

Need a new command to go with your executable? No problem:

cobra add mycmd

This will create the nameofexec/cmd/mycmd.go file and register the command. Again, all you need to do is set descriptions and tell it what to do.

Of course you can also add flags and options to your executable and/or commands, but this is beyond the scope of this article.

spf13/viper - Configuration

Need to parse configuration files? Need to parse configuration from a distributed key-value store like etcd? Look no further, spf13/viper got you covered! If you're using spf13/cobra from above, it already imports and configures spf13/viper for you, if not, configuration is really simple:

// initConfig reads in config file and ENV variables if set.
func initConfig() {
    if cfgFile != "" {
        // Use config file from the flag.
        viper.SetConfigFile(cfgFile)
    } else {
        // Find home directory.
        home, err := homedir.Dir()
        if err != nil {
            fmt.Println(err)
            os.Exit(1)
        }

        // Search config in home directory with name ".yourproject" (without extension).
        viper.AddConfigPath(home)
        viper.SetConfigName(".yourproject")
    }

    viper.AutomaticEnv() // read in environment variables that match

    // If a config file is found, read it in.
    if err := viper.ReadInConfig(); err == nil {
        fmt.Println("Using config file:", viper.ConfigFileUsed())
    }
}

Accessing the configuration is even simpler:

import (
    "fmt"

    "github.com/spf13/viper"
)

func main() {
    fmt.Println(viper.GetString("my.key"))
}

It supports multiple file types, JSON, YAML, TOML,... Whatever you need!

sirupsen/logrus - Logging

To log my messages nicely under different levels or even to different destinations I let sirupsen/logrus handle it. It doesn't even need any configuration, you can just use it from the get go:

package main

import "github.com/sirupsen/logrus"

func main() {
    logrus.Info("Hello!")

    details := "important stuff"
    logrus.WithField("details", details).Info("I've got something important to tell you")

    err := anything.Do()
    if err != nil {
        logrus.WithError(err).Fatal("I couldn't do anything!")
    }
}

Of course this is just basic usage, you can set the desired log level to ignore messages that are in lower levels and log just the errors, you have countless hooks readily available to help you send your log messages to any service you want, and if the hook isn't available, it's really easy to write one yourself.

gorilla/mux - HTTP Router

When writing a web application or a RESTful API, you need a HTTP router and dispatcher. I tend to always use gorilla/mux in my projects. It satisfies all my needs, and is very simple to use:

package main

import (
    "fmt"
    "net/http"

    "github.com/gorilla/mux"
)

func main() {
    rtr := mux.NewRouter()

    rtr.HandleFunc("/hello", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprint(w, "Hello, World!")
    })

    http.ListenAndServe(":8080", rtr)
}

Compile, run and visit http://localhost:8080/hello and there you go! Want to make it more personal? No problem let's just change the above HandleFunc to include a parameter or leave the above one in place and create a new route:

// ...
rtr.HandleFunc("/hello/{name}", func(w http.ResponseWriter, req *http.Request) {
    fmt.Fprintf(w, "Hello, %s!", mux.Vars(req)["name"])
})
// ...

Compile, run and visit http://localhost:8080/hello/foo.

adams-sarah/test2doc - API documentation

I must say I simply love adams-sarah/test2doc! Writing tests can be a daunting task, and then you still need to write documentation. Well here comes test2doc to the rescue! Simply write up a test for a handler using the test2doc server:

package main

import (
    "testing"

    "github.com/adams-sarah/test2doc/test"
    "github.com/adams-sarah/test2doc/vars"
)

func TestMyHandler(t *testing.T) {
    // init the router and register a handler to a route
    rtr := mux.NewRouter()
    rtr.HandleFunc("/hello", helloHandler)

    // register the mux extractor
    test.RegisterURLVarExtractor(vars.MakeGorillaMuxExtractor(rtr))

    // start the server and defer the Finish call
    var err error
    server, err = test.NewServer(rtr)
    if err != nil {
        t.Errorf("unable to create test server, %s", err)
    }
    defer server.Finish()

    // get the named route from mux and get its URL
    urlPath, err := rtr.Get("hello").URL()
    if err != nil {
        t.Errorf("unable to get route URL, %s", err)
    }

    resp, err := http.Get(server.URL + urlPath.String())
    if err != nil {
        t.Errorf("unable to process the request, %s", err)
    }
}

Now simply execute the test with go test and you should get a new file in your directory ending with an .apib extension.

Web application directory layout

I have also prepared a small bare-bones project that I tend to use often when starting a new project, since I already have a lot of the above tools and libraries already incorporated, as well as some deployment options. It is personalized to my own use, but can probably be useful for someone else too, since it does not enforce anything. Please check it out at my GitLab repository and feel free to use it if you find it useful!

Deploying Secure Web Applications With Docker

Tomaz Lovrec — Fri, 10 Apr 2020 17:14:42 +0000

Over the past few we have seen more and more use of containers and I think this will continue in the future. And from a developers point of view, rightly so. I still remember using cumbersome and slow Virtual Machines that would take ages to provision and start up. Then along came containers and Docker. Yes there are some drawbacks to be considered before you start using it, but the bottom line is, I can quickly fire up a container or multiple containers, do my work on the project, tear everything down at the end and switch to a different project, where I can do more of the same.

Aside from helping out in the local environment, there is one other advantage that Docker and containers bring to the table. Deployments, and ease of it. It is fairly simple to ship your application with Docker. There are tools that allow you to set up everything in a matter of minutes. This is what this article will try to walk you through, and at the end you will have shipped your application to the web, and better yet, you have it deployed behind a HTTPS secured server.

The basics

For this you will need a server with Docker installed. As long as you have a server running Linux you can easily install docker on it. If you do not have a server you can get one fairly cheap nowadays at different providers. And be sure to install docker-compose as well, as it will simplify a lot of the tasks before us.

In this walk through we will build and deploy a very simple expressjs frontend application, but you can deploy basically anything you want. To achieve our goal we will use the traefik as our ingress router which will route the incoming traffic from the public to our expressjs app.

Preparing the server

Now that you have docker and docker-compose installed, we are going to bring the ingress router up and running and apply a small configuration to it. To do this, create a docker-compose.yml file somewhere in your system, i.e. in /opt/env/. Create the directory and file, and paste in the following contents:

version: "3"

services:
  traefik:
    image: traefik:2.2
    ports:
    - "80:80"
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - ./traefik.toml:/etc/traefik/traefik.toml:ro
    container_name: traefik
    networks:
    - public
    restart: always

networks:
  public:

Here we define a pretty straight forward docker network and a service connected to that network. Note that the image version of traefik, 2.2 might be outdated when you are reading this article, but at the moment it is the newest version. Setting the container_name is optional, but it is highly recommended to set the restart policy for traefik as you want it up all the time. Of course you will also have to bind the service to the port 80. And the volume mounts, you need to bind the Docker socket to the service, since traefik connects to it, listening for Docker container creations, and the traefik.toml file:

[entryPoints]
  [entryPoints.web]
    address = ":80"

[providers]
  [providers.docker]
    endpoint = "unix:///var/run/docker.sock"

[log]
  level = "DEBUG"

[accessLog]

In this simple configuration file we enable the access logging, turn the logging level up to debug, which you can lower later to info, set the location of the Docker socket as the provider, and define an entrypoint. This is it, you can start traefik now by simply executing docker-compose up -d.

Create the sample application

You can skip this step if you wish to build your own application. And even though we are using a JavaScript application here, you can use whatever you want.

Now, lets create the sample expressjs application on your local machine:

mkdir docker-deploy
cd docker-deploy
npm init
# simply use all default values
npm install express --save

Now in that same directory create a new index.js file with the following contents:

const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => res.send('Hello World!'))

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

Quickly make sure it's working:

node index.js

And open http://localhost:3000/ in your browser.

Deploy the application

Create the image

To deploy your application we must first create the Docker image which will hold your application and from which a container will be created on the server later. First we create a .dockerignore file, telling Docker which files to ignore when creating the image:

node_modules
npm-debug.log

We will ignore the debug log, because we don't want it in the container, and our local node_modules usually hold some development version files, and we want the container to be production ready, so we will install production ready modules at image creation. Now that we have this in place, lets create the Dockerfile:

FROM node:13.12-alpine3.10

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm ci --only=production
COPY . .

EXPOSE 3000

ENTRYPOINT ["node","index.js"]

This is our sort of a blueprint for creating our own Docker image, where we tell Docker to create our image FROM the node base image, more specifically the 13.12-alpine3.10 version of the node Docker image. We must use the node image in order to have tools like npm and node available. Of course if your application is using other technology, you will want to use a different base image. However, it is recommended to use the alpine version of the image if it is available. Alpine Linux is a small Linux distribution perfect for Docker, since it is very basic and small and reduces the size of your Docker images.

Next we set the WORKDIR to /usr/src/app and COPY any package*.json files to that directory and clean install the node modules. After that we copy the rest of our application to the image, which in our case will only copy the index.js file, since the rest is ignored anyway.

Finally we set the EXPOSEd port to 3000, since our application will listening on port 3000 inside the container, and we set the ENTRYPOINT, which is basically a command that will be executed when the container is created using this image.

Before we go on to create the image, head on over to theDocker Hub and register, since we will be pushing the newly created image there. And while you're there, go ahead and create a new repository there.

Now, let's create the image:

docker build -t your_dockerhub_name/express-sample .

After a short while, a new image should be created. Now lets see if everything is ok by creating a new container with it:

docker run --rm -d -p 3000:3000 your_dockerhub_name/express-sample

Again open http://localhost:3000/ in your browser. If you see the same result, this means we have successfully created a Docker image and a Docker container from it.

Now we must push that image to Docker Hub, before proceeding to deployment.

# if you have not yet logged in to Docker Hub from your shell do so now
docker login
docker tag your_dockerhub_name/express-sample:latest your_dockerhub_name/express-sample:1.0.0
docker push your_dockerhub_name/express-sample:1.0.0

Before we pushed the image, we have also tagged it with a new version, because our command above has created a new image with the latest tag by default.We could have specified this version there as well. This is an optional step,but recommended, since you want to tag images with versions if you are doing to deploy them, to avoid overwriting them and breaking something on the server.

Deploying the image

Now we have finally come to the deployment part. To execute the deployment, we will once again use the power of docker-compose and create yet another docker-compose.yml file, not on the server, but locally, right there by your code:

version: "3"

services:
  express:
    image: your_dockerhub_name/express-sample:1.0.0
    labels:
    - "traefik.http.routers.express-sample.rule=Host(`express-sample.yourdomain.com`)"
    - "traefik.http.services.express-sample.loadbalancer.server.port=3000"
    container_name: express-sample
    networks:
    - env_public
    restart: unless-stopped

networks:
  env_public:
    external: true

You may also want to add this file to .dockerignore since its of no use inside the container. To quickly walk through the file again, we again define a network, but this time the name is env_public. public comes from the network defined by the traefik container but we must prepend it with env_, since docker-compose will by default prepend the created network with directory name of where the docker-compose.yml is located.

We assign this network to the service, set a restart policy, and optional container name. Ports do not need to be bound, since traefik will handle the traffic.

What we absolutely do need to define are the labels, those tell traefik which host will be routed to this service, and which port is in use. There are more rules that can be used for routing, but they are beyond the scope of this article and I invite you to check the wonderful traefik docs.

All that there is now is to fire up the docker-compose command:

DOCKER_HOST="ssh://root@your-server-ip" docker-compose up -d

By setting the DOCKER_HOST variable we instruct docker-compose to execute all commands through the SSH connection that it establishes. If all has gone well you should be able to view your deployed application by visiting http://express-sample.yourdomain.com.

Securing the application

Since all of this is now served over the insecure HTTP connection it is time for us to secure it. To do this we must re-configure traefik and instruct it to try and obtain a valid SSL certificate from Lets Encrypt for every new registered container.

First open up the docker-compose.yml file on the server and edit the traefik service:

# ...
  traefik:
    image: traefik:2.2
    labels:
    - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
    - "traefik.http.routers.global-redirect.rule=HostRegexp(`{host:.+}`)"
    - "traefik.http.routers.global-redirect.entrypoints=web"
    - "traefik.http.routers.global-redirect.middlewares=redirect-to-https"
    ports:
    - "80:80"
    - "443:443"
# ...

Here we added a couple of rules to the labels to instruct traefik to redirect all HTTP traffic straight to HTTPS, and bound the servers 443 port to the services 443 port for HTTPS traffic. Now, let's tell it to use Lets Encrypt, by editing the traefik.toml file:

[entryPoints]
  [entryPoints.web]
    address = ":80"
  [entryPoints.web-secure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  email = "your@email.com"
  storage = "acme.json"
  [certificatesResolvers.myresolver.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"

# ...

As you can see, we added a new web-secure entrypoint and an acme certificate resolver which uses http challenges, that will be handled by the insecure web entrypoint. Now we need to recreate the traefik service which can be done by simply running docker-compose up -d again.

After the server reloads, add the following two labels to your applications docker-compose.yml file:

# ...
    labels:
    - "traefik.http.routers.express-sample.tls=true"
    - "traefik.http.routers.express-sample.tls.certresolver=myresolver"
# ...

Now we have instructed the service to use the myresolvre certificate resolver, defined in the servers traefik.toml configuration file, to handle SSL certificates for it. To apply this simply run the following command again:

DOCKER_HOST="ssh://root@your-server-ip" docker-compose up -d

Conclusion

Docker can make your life easier, be it locally for your development needs, or deployments, or,... but it is not the silver bullet. There are some considerations to make before you start using it, you should also take care with the containers, since there is a possibility that you hand your whole server to an attacker on a silver platter. But this is beyond the scope of this article. However, I do invite you to educate yourself about Docker and containers in general further, as they are already playing a big part in software development and I sense that they will not go away any time soon.

I hope you were able to get your application deployed, and you found this article helpful and informative. If you have run into issues, please, leave me a comment, and I will be more than happy to help!