Docker on inherent site

Docker Multi-Binary Images

Sun, 01 Aug 2021 17:43:30 +0300

Problems in deploying distributed applications

If you read my background in the front page, you know I’m not a prolific programmer by any definition. This isn’t going to be a gigantic revalation and if you’ve worked with deploying your own applications to kubernetes you’ll already know most of the following things. With that said, what are the problems with deploying a distributed application? I was tinkering with gifinator and while writing the kubernetes manifests I realized there was a problem. A few bugs required multi-service re-deployments. Let’s say there was something affecting the render service and the gifcreator worker service. I could rebuild 2 new docker images, push them to the local image repository, update the version in their respective manifests and apply the changes. The issue is that after doing it once or twice it became really annoying when wanting to roll back to check the previous behavior. The more this cycle went on, I had to keep track of a set of 4 different versions which quickly became unmanageable.

Lightbulb moment

That’s when the obvious dawned on me, the upstream kubernetes manifests all used the same image somehow. I quickly opened them up and checked to see they were redefining the container’s CMD directive! In fact the actual Dockerfile did not even have a CMD nor ENTRYPOINT defined. The code was built, the binaries were copied to the second stage and the final image was shipped. Using this method the final image is as small as possible without needing 4 separate ones.

How do

It’s pretty easy to do this so let’s take a look at the Dockerfile as well as the kubernetes manifests.

Dockerfile

This specific Dockerfile is available on gitlab for those interested but I’ll paste it here for ease:

# build stage
FROM golang:1.16 as build

ENV CGO_ENABLED 0
ENV GOOS linux
ENV GOARCH amd64
ENV GO111MODULE on

WORKDIR /go/src/gifinator
COPY . .

WORKDIR /go/src/gifinator/render
RUN go get -v
RUN go vet -v
RUN go install -v

WORKDIR /go/src/gifinator/gifcreator
RUN go get -v
RUN go vet -v
RUN go install -v

WORKDIR /go/src/gifinator/frontend
RUN go get -v
RUN go vet -v
RUN make installwithvars

# run stage
FROM busybox as run
RUN mkdir /tmp/objcache
RUN mkdir /tmp/scene
COPY --from=build /go/bin/render /render
COPY --from=build /go/bin/gifcreator /gifcreator
COPY --from=build /go/bin/frontend /frontend
COPY ./gifcreator/scene /tmp/scene
COPY ./frontend/templates /templates
ENV FRONTEND_TEMPLATES_DIR=/templates

First up we set some basic environment variables and copy the code into the building environment. Then one by one the services are compiled and installed into the build stage image. Following that, in the run stage the needed directories are created, the binaries are copied over, assets are also copied over and a final environment variable is set. There is no CMD or ENTRYPOINT as you can see, this will probably result in the inability to just docker run -p externalport:internalport imagename but the tradeoff is well worth it.

Kubernetes deployment manifests

With the Dockerfle out of the way, let’s look at the way these images are deployed. The primary way I run containers is through kubernetes so we’ll be looking at kubernetes manifests. Same as the Dockerfile you can find the source for these manifests on gitlab, I’ll be linking each one. kube/manifests/gifinator/render/deployment.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: render
  namespace: gifinator
  labels:
    app: render
spec:
  replicas: 1
  selector:
    matchLabels:
      app: render
  template:
    metadata:
      labels:
        app: render
    spec:
      containers:
      - name: render
        image: inherently/gifinator:0.0.5
        command: ["/render"]
#the rest of the file is omitted

kube/manifests/gifinator/gifcreator-server/deployment.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gifcreator-server
  namespace: gifinator
  labels:
    app: gifcreator-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gifcreator-server
  template:
    metadata:
      labels:
        app: gifcreator-server
    spec:
      containers:
      - name: gifcreator-server
        image: inherently/gifinator:0.0.5
        command: ["/gifcreator"]
#the rest of the file is omitted

kube/manifests/gifinator/gifcreator-worker/deployment.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gifcreator-worker
  namespace: gifinator
  labels:
    app: gifcreator-worker
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gifcreator-worker
  template:
    metadata:
      labels:
        app: gifcreator-worker
    spec:
      containers:
      - name: gifcreator-worker
        image: inherently/gifinator:0.0.5
        command: ["/gifcreator", "-worker"]
#the rest of the file is omitted

kube/manifests/gifinator/frontend/deployment.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  namespace: gifinator
  labels:
    app: frontend
spec:
  replicas: 1
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
      - name: frontend
        image: inherently/gifinator:0.0.5
        command: ["/frontend"]
#the rest of the file is omitted

Here are 4 different services, all easily using the same image. Just by redifining the command it’s easy to simplify the development process by a quite a lot. It’s worth noting that I’ve only shown the deployment manifests since the other ones don’t have anything to do with the container image used.

Conclusion

This is a short post mostly made up of code snippets but I hope you learned something and can improve your workflow with distributed microservice applications.

Beyond Docker

Tue, 22 Sep 2020 12:29:52 +0300

Preamble

(Warning: the examples haven’t been fully validated so they’re not guaranteed to work)

On the first part I only talked about docker and functionality included with it by default. This time we are going to look at a few extras. The list includes but is not limited to:

docker-compose since it’s often the next step after standalone docker
a couple tips for Dockerfiles like being extra paranoid about the base image used and how to make sure the thing inside the container is running and listening to requests
setting up a quick and dirty nextcloud + gitea + simple test site and using the traefik to reverse proxy traffic to all of them
having a local docker registry to be less reliant on an always-on internet connection

Sounds exciting, right? Let’s get started then

Prerequisites

MUST :
- Have Linux installed
- Have Docker installed
- Read the first part
OPTIONAL:
- Some basic knowledge of YAML
- PfSense with DNS Forwarder as the DNS server of the network

Docker-compose

We didn’t delve into real multi-container applications last time and that was intentional. The simple site example, reactjs website and golang backend were all self-contained and ran on their own but it’s fairly rare to have something like that running. Many selfhosting-oriented images out there might have an embedded sqlite database suitable for single-user or low use but provide a way to connect to a real database, like mariadb or postgres, when the use exceeds the basic requirements. How would one go about that you might be asking. Write a nice shell script to handle starting/stopping/restarting everything in the right order? That was my first thought too but the answer is docker-compose. Here is where we enter the concept of a set of services, a collection of all images and configuration that a complete application needs to run. This might include a client component, a server component, a database (or two with one being a cache) maybe even multiple server components. All of this can be done in a single YAML file, no long docker run commands, and can be used in quite a few different ways.

Installation

First of all, how do we get that. Following the first-glance upstream documentation and suggestions it might seem like you install it like docker but I suggest a different route. Of course, first priority is through the repository (if applicable). If you can’t, there is a script in the alternative installation options that is placed in /usr/local/bin or wherever else in$PATH we deem appropriate that in turn downloads docker-compose as a container. This is by far my favorite way of getting it and I recommend you give it a try. However, you are welcome to ignore my advice and use the default method for your distro that is mentioned in the installation section of docker’s docs. After it’s installed we can jump into the fun.

First Use

Writing the docker-compose file

For our first multi-container deployment, let’s try gitea since it already has pretty good examples. The first ingredient we need is a file named docker-compose.yaml or docker-compose.yml if we wish it to be automatically recognized by the docker-compose command the same way a file named Dockerfile is recognized by docker build. However, an argument can be give to the -f flag in order to specify a different file if that’s what we wanted to do. For now, we open our favorite editor and start writing.
First up, we need to specify what version we’re using at the very top of the file. This will determine what features we have access to. The latest major version is 3 so let’s go with that:

`1`	`version: "3"`

It needs to be provided as a string which is why it’s surrounded by double quotes. Next up we specify our services, meaning the declaration block for the individual containers and their settings:

1
2
3

version: "3"

  services:

Please note the whitespace indentation, this is how YAML is written. After telling docker-compose that we’re about to define our services, let’s actually define one:

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always

Which means the service is named server which uses the gitea/gitea image and should always be restarted. Below that we can specify some environment variables:

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=gitea
      - DB_USER=gitea
      - DB_PASSWD=gitea

The lines below environment that start with a dash are items of a list in YAML, in this case environment variable and their values. The example above has the disadvantage of possibly including passwords and access keys or tokens in this file so you can’t store it in a public git repository. We’ll take a look at how to remedy this later on and we’ll assume it’s fine for now.

Let’s move on to specifying the networks and volumes this container will use (declarations for networks and volumes will be covered later, don’t worry). First a mount point for data and two for sourcing the time from the host system (the :ro means read only so don’t worry about your host files being overwritten or corrupted). This is what the file looks like after those additions:

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=gitea
      - DB_USER=gitea
      - DB_PASSWD=gitea
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

Quite a bit nicer and easier to read than the multiple command-line declarations I think. Now that it’s hooked up to a network, it needs at least one port to expose its web interface on (port 3000) and there is also the ability to ssh into it (using port 22 which is the standard port for it). Here is how ports are mapped in a docker-compose file:

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=gitea
      - DB_USER=gitea
      - DB_PASSWD=gitea
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

The above covers the gitea server part but we defined a database to be used so next up we have to add that. The format is the same as above and no new concepts are introduced so here is the file in full as it exists now:

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=gitea
      - DB_USER=gitea
      - DB_PASSWD=gitea
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

  db:
    image: postgres:9.6

    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data

However there is are a few things still missing from the above. First, the gitea network definition. Second, we’re still storing credentials in the docker-compose file in plaintext form. Last, and less apparent, nothing guarantees that the gitea server instance will start only after the database is operational. To achieve this, we will use depends_on. In this case, the server should not start until the database is ready so depends_on will be added to the server declaration:

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=gitea
      - DB_USER=gitea
      - DB_PASSWD=gitea
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:9.6
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data

Simple as that, we have now defined a startup dependency and ensured that our containers are started in the correct order. Let’s move on to the network declaration now.

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=gitea
      - DB_USER=gitea
      - DB_PASSWD=gitea
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:9.6
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data


networks:
  gitea:
    external: false

So we are defining a network named gitea and specifying that it is not external (meaning it was not created using docker network create gitea but is instead managed by docker-compose). This is all that’s needed to make this run, improvements will be discussed afterwards.

Running the application

After having written our docker-compose.yml or docker-compose.yaml (as mentioned before, both names are acceptable), we have to actually run it. I assume everyone reading installed the docker-compose command-line tool using their preferred method so we can all run docker-compose up or docker-compose up -d to start in detached mode while in the same directory as the docker-compose.yml file. Same as docker, it will pull the images and then bring up the containers. Pointing a web browser to http://localhost:3000 should be enough to see gitea’s front page. We’re up and running!

I’ll have to be a buzzkill and remind you that we’re still storing access credentials inside a file that could and should be in a source code version control repository. Public git repositories are free of charge on the vast majority of code hosting websites and allow other people to reuse our docker-compose YAML files to run services more easily. It becomes clear then that our credentials should be stored outside the docker-compose.yml file. Where could we store them though? Inside .env of course! Docker-compose can read environment variables if there is a file called .env inside the same directory that the docker-compose.yml file is. This means that only that single file can be excluded from version control or encrypted and stored in the repo while keeping everything publicly accessible. Let’s take a look at the .env file then:

UUID=1000
UGID=1000

DBNAME=gitea
DBUSER=gitea
DBPASSWD=gitea

PSTGRSUSR=gitea
PSTGRSPASSWD=gitea
PSTGRSDB=gitea

Simple as that, variable=value pairs is all that’s needed. I avoided underscores and refactored the names a bit to make it clear when the above variables are used. Let’s see how the docker-compose file will look if we want to source the values of the variables we defined:

version: "3"

services:

  server:
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=$UUID
      - USER_GID=$UGID
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=$DBNAME
      - DB_USER=$DBUSER
      - DB_PASSWD=$DBPASSWD
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:9.6
    restart: always
    environment:
      - POSTGRES_USER=$PSTGRSUSR
      - POSTGRES_PASSWORD=$PSTGRSPASSWD
      - POSTGRES_DB=$PSTGRSDB
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data


networks:
  gitea:
    external: false

Pretty easy, right? Just like grabbing the value from variables in the shell. Now all that’s required is to put .env in the repository’s .gitignore so access credentials are sure to be kept safe. Not only that, it’s now possible to use a different .env in production and a different one while developing without changing the docker-compose.yml at all. Feel free to play around with this and see what else you can use this trick for. For now, stop the running containers using docker-compose down if running in detached mode or by hitting Ctrl-C if you started it with docker-compose up and then start it again. We should notice no functional difference other than knowing our credentials are safe.

Personal preference of mine is to set the name (equivalent to --name in docker run) for the containers as well as their hostnames (equivalent to --hostname in docker run), usually to the same value. The final docker-compose.yml would look like this if you wanted to adopt my pet peeve:

version: "3"

services:

  server:
    name: gitea-server
    container_name: gitea-server
    image: gitea/gitea
    restart: always
    environment:
      - USER_UID=$UUID
      - USER_GID=$UGID
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=$DBNAME
      - DB_USER=$DBUSER
      - DB_PASSWD=$DBPASSWD
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    name: gitea-db
    container_name: gitea-db
    image: postgres:9.6
    restart: always
    environment:
      - POSTGRES_USER=$PSTGRSUSR
      - POSTGRES_PASSWORD=$PSTGRSPASSWD
      - POSTGRES_DB=$PSTGRSDB
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data
networks:
  gitea:
    external: false

Healthchecks

Docker is unwise as to the actual status of the container, its knowledge by default is limited to the exit code of the command in the ENTRYPOINT or CMD declaration. Fear not though, we can definitely make it a little smarter. Enter the HEALTHCHECK statement. Its syntax is quite easy and it provides better understanding of the program’s status to the container runtime. Admittedly, this is much more useful when working with kubernetes but it never hurts to know if the program is actually working or if it’s hanging but hasn’t fatally exited.

As on the previous part, we’ll start with a simple example. Our old pal nginx will be useful once more. Also this is a great opportunity to learn a new trick. If we start the nginx image in non-detached mode, the web server’s logs will be streamed to our terminal and any commands we type will have no effect since we’re not in a shell. How can we override this and get a shell when we start a new container? The docker run command will be useful here. See, we can redefine the entrypoint and set it to be a shell. Combine that with the -i and -t arguments and we should be off to the races. After a quick docker run --rm -it --entrypoint /bin/bash nginx we get a shell prompt. But hold on, since we redefined the entrypoint, nginx is not actually running (you can check that by installing the procps package and then running top or the old trusty ps aux). Hit Ctrl-C to exit the interactive session (the container will be removed due to --rm) and let’s find a different route.

First, start an nginx container in detached mode docker run --rm -d --name ngx nginx and then with the help of docker exec -it ngx /bin/bash get a shell. Ta-da! Don’t forget, if you don’t give it a nice name you can always use the hash-like name shown in docker container ls, no hindsight required. I walked you through all of this because it’s going to be useful for debugging should you find yourself in a sticky situation and because we’ll demonstrate a common healthcheck command. The one in question is curl --fail http://localhost || exit 1. This will exit with 1 (which is the error/problem code) if there is an error or 0 if there isn’t. Of course we can also replace http://localhost with the URL of our choice. This is a common way to check if a service is still responding normally for obvious reasons, all that is required is curl, a very common utility and we get improved awareness of our program’s status. Let’s see how we can take a Dockerfile from the previous part and add a healthcheck to it. Here is the original (to be used with this project):

FROM node:14.1.0-alpine3.11 as build
WORKDIR /app
COPY . .
RUN npm install --global react-scripts
RUN npm install
RUN npm run build

FROM nginx:1.17.10-alpine
COPY --from=build /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

And here it is with the healthcheck added:

FROM node:14.1.0-alpine3.11 as build
WORKDIR /app
COPY . .
RUN npm install --global react-scripts
RUN npm install
RUN npm run build

FROM nginx:1.17.10-alpine
COPY --from=build /app/build /usr/share/nginx/html
HEALTHCHECK CMD curl --fail http://localhost || exit 1
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Easy to read and write. It doesn’t end there though. We can tweak a few knobs on it. What if it’s a pretty complex Spring Boot program that takes a couple minutes to start up but after it gets there, we want to check up on it every 15 seconds and allow it 9 seconds and 5 retries to respond since it’s not mission critical? This can all be tweaked. Let’s take those one by one (please note: -f is the same as --fail and Spring Boot runs on port 8080 by default and exposes a health endpoint on /health).

In English:

2 minutes to start up, after that check every 5 seconds

In Dockerfile:

`1`	`HEALTHCHECK --start-period=120s --interval=15s --timeout=9s --retries=5 CMD curl -f http://localhost:8080/health \|\| exit 1`

And that’s it! Now it’s going to run that command and change the container’s health status accordingly. But what if I told you that I don’t recommend using curl for this? Why would that be? If you read the first part, you can see that I used a pretty slim image by picking busybox to base the actual running image. In fact, you can replace that command with no more than 25 lines of Go. What might that look like? I’m glad you asked. Here it is:

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    URL := os.Getenv("URL")
    if URL == "" {
        URL = "http://localhost"
    }

    fmt.Println("getting:", URL)
    r, err := http.Get(URL)
    if err != nil {
        os.Exit(1)
    }
    fmt.Println("status code:", r.StatusCode)
    if r.StatusCode != 200 {
        os.Exit(1)
    }

    fmt.Println("exit status 0")
    os.Exit(0)
}

And that’s all of it, you can compile the above into a single, tiny, static binary and move into any compatible image. Not to mention that with Go’s amazingly easy cross compilation ability, a quick and easy CGO_ENABLED=0 GOOS=linux GOARCH=arm go build -v gets you a binary to run or a Raspberry Pi for example. Play around with it if you want, I’ve been liking it lately and using it (mostly in images built on the scratch one) instead of using a bigger image that either includes curl or has access to it.

LAN-only setup with reverse proxy

Time to move back to docker-compose. Traefik came to my attention when looking up reverse proxy options. To be precise, this tutorial about traefik v1.x which was the latest version available back then, as well as a new guide for traefik v2.x and I’ve greatly benefited from both. In my view, they’re amazing for a public-facing server (that’s what this site is using) but for LAN-only setups the solutions from the above tutorials seem overcomplicated and overkill. Below I’ll share my docker-compose.yml as well as traefik-related configuration. Feel free to to also look at the raw files in the repository for more help. Specifically, for how to run nextcloud without https which took me a good 20 minutes of searching to find the relevant documentation (always love multiple major version old docs linked from a forum post made at least half a decade ago). However, let’s back up just a bit, one thing at a time.

Reverse Proxies

What are they and what do they do? A proxy is essentially a middleman, in the context of internet traffic, it usually means that it’s taking the traffic you send it and forwarding it somewhere. Flipping this concept, a reverse proxy takes the traffic sent to it and decides where in the servers behind it to send it. So, normal proxy is a middle man for all its clients to reach any server while a reverse proxy is a middle man for all its servers to be reached by a client. Too theoretical? Here is an example then, say my gitea instance is running on my laptop and my blog is running on my desktop. When someone visits git.inherently.xyz they should be redirected to my laptop and if they visit blog.inherently.xyz they should be redirected to my desktop (assuming those things are hosted on the respective devices). It would be possible to open the required ports on both computers and keep opening ports for each new thing I decide to run but it gets out of hand quickly. Here is where a reverse proxy comes in to solve the problem. I can run hundreds of applications or services and only open 1 port, the reverse proxy’s port. The most used reverse proxies are nginx, haproxy and traefik (maybe caddy too). Initially I chose traefik because it was created for a container-focused workload and the excellent tutorial for traefik v1.x that I linked above existed. Now that this is covered, let’s move on to the actual setup.

Writing the docker-compose.yml

First up, make a directory (I recommend $HOME/docker) to put all the relevant files in (this will be known as DOCKDIR for our purposes). Since the basics have been explained, here is where we are going to start from, create a docker-compose.yml inside the DOCKDIR with the following content

version: "3"

services:

  traefik:
    image: traefik:1.7-alpine
    container_name: traefik
    hostname: traefik
    restart: always
    networks:
      - default
      - traefik_proxy
    ports:
      - "80:80"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ${DOCKDIR}/traefik:/etc/traefik


networks:
  traefik_proxy:
    external:
      name: traefik_proxy
  default:
    driver: bridge

You didn’t read this wrong, I’m using the latest release of the v1.x of traefik since the configuration is much simpler. This isn’t fully ready but we’re taking it one step at a time. So, remember what external means? We have to run docker network create traefik_proxy before ever running docker-compose up since it will fail due to the network missing. As for a brief explanation, traefik’s api is running on port 8080 so we expose that and port 80 is where all HTTP traffic will go to. We also bind mount the configuration directory so we can edit traefik’s config easily. Save and exit the file and create a subdirectory named traefik under DOCKDIR to put the traefik.toml in. Said file will include the following:

#options for loglevel are: DEBUG, INFO, WARN, ERROR, FATAL, PANIC
logLevel = "DEBUG"

#turns off traefik's checking of certs
#since we use none, it's fine
InsecureSkipVerify = true

defaultEntryPoints = ["http"]

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

[api]
  entryPoint = "traefik"
  dashboard = true
  address = ":8080"

[docker]
endpoint = "unix:///var/run/docker.sock"
domain = "docks.localhome"
watch = true
#we're on LAN only and it avoids a label
exposedbydefault = true

First, enabling debug mode to be able to get logs in case something is wrong and turning off certificate checking since it will all be http-only. We set http as the only default entrypoint and then define it addresses on port 80. After that, we enable the api with the dashboard and make it accessible on port 8080. Finally, we add docker-related settings and set all services to be exposed by default without requiring the use of a label for the container. Labels? Let’s go back to the docker-compose.yml and add a couple things. Traefik uses labels for configuring apects of how the reverse proxy will treat an application. For example:

version: "3"

services:

  traefik:
    image: traefik:1.7-alpine
    container_name: traefik
    hostname: traefik
    restart: always
    networks:
      - default
      - traefik_proxy
    ports:
      - "80:80"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ${DOCKDIR}/traefik:/etc/traefik
    labels:
      - "traefik.backend=traefik"
      - "traefik.frontend.rule=Host:traefik.$DOMAINNAME"
      - "traefik.port=8080"
      - "traefik.protocol=http"

networks:
  traefik_proxy:
    external:
      name: traefik_proxy
  default:
    driver: bridge

This sets the name for the backend that handles its traffic to traefik, makes it accessible by using traefik.$DOMAINNAME (we’ll define this in our .env), sets the port that the application runs on as 8080 and defines the protocol as http. This little bit will be added to almost every container with some modifications if it’s a container that should accept traffic from clients and not a database or something else meant for internal use only. I’ll use a container running caddy and one using nginx to demonstrate:

version: "3"

services:

  caddy:
    image: caddy
    restart: always
    networks:
      - traefik_proxy
    labels:
      - "traefik.backend=caddy"
      - "traefik.frontend.rule=Host:web1.$DOMAINNAME"
      - "traefik.port=80"
      - "traefik.protocol=http"

  nginx:
    image: nginx
    restart: always
    networks:
      - traefik_proxy
    labels:
      - "traefik.backend=nginx"
      - "traefik.frontend.rule=Host:web2.$DOMAINNAME"
      - "traefik.port=80"
      - "traefik.protocol=http"

  traefik:
    image: traefik:1.7-alpine
    restart: always
    networks:
      - default
      - traefik_proxy
    ports:
      - "80:80"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ${DOCKDIR}/traefik:/etc/traefik
    labels:
      - "traefik.backend=traefik"
      - "traefik.frontend.rule=Host:traefik.$DOMAINNAME"
      - "traefik.port=8080"
      - "traefik.protocol=http"

networks:
  traefik_proxy:
    external:
      name: traefik_proxy
  default:
    driver: bridge

Fairly simple, right? Only one thing is missing at the moment and that is our .env to define a few commonly used variables. Here it is then:

PUID=1000
PGID=998
TZ="Europe/Athens"
DOCKDIR=/home/user/docker
DOMAINNAME=docks.localhome
MYSQL_ROOT_PASSWORD="Th1s1s_A_verySecurePassword_123"

I defined some commonly used things like a password for databases, timezone, the domain name along with the user and group docker runs as. The last two can be discovered by running id and checking the output. But wait, localhome is not the current local domain and there is no host called docks on this non-existent local domain. Sounds weird but this is not a problem, it will be solved through the DNS server (explained later on in the guide) but for now you can put the IP of the computer and put it in /etc/hosts like below

if it is remote:

1
2
3

192.168.35.18	web1.docks.localhome
192.168.35.18	web2.docks.localhome
192.168.35.18	traefik.docks.localhome

or if you’re running it on the same host you’re accessing it from:

1
2
3

127.0.1.1	web1.docks.localhome
127.0.1.1	web2.docks.localhome
127.0.1.1	traefik.docks.localhome

We need this because traefik responds based on the name that is requested. Time to run docker-compose up -d finally and then visit web1.docks.localhome thenweb2.docks.localhome followed up bytraefik.docks.localhome to check if the setup was successful. Hopefully you see the correct page for each one (web1 is caddy, web2 is nginx and traefik is traefik as expected).

Logs

The above is all fine and dandy but what if things go wrong? A common first action is to look at the logs. Since everything is running inside docker, we could start an interactive terminal and check there but anything that has already been printed will not be shown. Here is where the logs subcommand comes in. While in the same directory as the docker-compose.yml (or by using the -f flag) we can see the logs from all the containers that were launched, including the previous 50 lines, like so:

`1`	`docker-compose -f docker-compose.yml logs --tail=50 -f`

I included the file flag for docker-compose and the follow flag for logs to showcase how they should be positioned since order is important here. This command will print the last 50 lines of logs from all containers that were started from the specified docker-compose.yml and keep following the logs as they’re printed. That’s not what we want to always do because the problematic container might be a single one and the clutter from the rest is distracting. No problem, simply append the specific one that needs to be examined, let’s use traefik as the example:

`1`	`docker-compose -f docker-compose.yml logs --tail=50 -f traefik`

And that’s about it for logs, unlike conventional systems there is not much “unicorn” configuration or at least it should be avoided as much as possible. Keeping the setup easy to replicate is a good thing, the container might restart due to failure and that should be no problem for our operations.

Backups

If there are not at least 2 copies of a file, it might as well not exist. Backups are very important yet often neglected. In this case there is no reason for that to be the case. With the above setup in mind, every piece of data required to replicate the setup is under one directory so all we need is to keep a copy of that on a different hard drive. Using a compressed tarball with preserved permissions or rsync, again preserving the permissions, should be enough for a home setup with a single node. Multi-node setups are not going to be covered here since that would land us in kubernetes territory which is vast enough to warrant its own writeup. What would a simple backup such as the one I suggest above look like then? The following commands are examples that you should tweak depending on your setup and not meant to be copy-pasted and used verbatim:

`1`	`rsync -Pauvr --progress /home/user/docker /mnt/externaldrive/docker-bak-$(date +'%F')`

and

`1`	`tar czvf /mnt/externaldrive/docker-bak-$(date +'%F') /home/user/docker`

Registry

Connecting to dockerhub as well as having an account there can bothersome to impossible in air-gapped setups and having to go to the internet every time you want an image is annoying. Good news, we can run our own registry and cache public images as well as push our own images there. This will require a tiny amount of setup on the clients but nothing that will take more than a few seconds.

Local image storage

First let’s see how we can run a local docker registry using a raw docker command:

`1`	`docker run -d -p 5000:5000 -v ./registry:/var/lib/registry registry:2`

With the above setup, we’ll have a persistent registry running on port 5000 of the host that is running it. For the client setup I’m going to assume everything is on the same system so I will use localhost for the registry address but in reality you’ll be running it on a remote host so feel free to replace localhost with the IP or hostname of the host that the registry is running on in the following examples. On the client’s side create the file /etc/docker/daemon.json (it doesn’t exist by default) and insert the following into it:

{
	"insecure-registries" : [
		"localhost:5000"
	]
}

Don’t worry about the “insecure” part, that’s because it’s not using https. In order to test this out, try pushing an image to it and then pulling it:

docker pull nginx:1.19.2-alpine
docker tag nginx:1.19.2-alpine localhost:5000/ngxalp
docker push localhost:5000/ngxalp
docker image remove nginx:1.19.2-alpine
docker image remove localhost:5000/ngxalp
docker pull localhost:5000/ngxalp

And there we have it, our very own local dockerhub. That’s not where the story ends though. I promised we could also cache images and that’s what we’re going to get into next.

Pull-through cache

This one requires a tiny bit more configuration but still nothing extravagant. Start by editing /etc/docker/registry/config.yml (the registry subdirectory as well as the config.yml file don’t exist by default so you’ll have to create them first) and inserting the following in it:

1
2

proxy:
  remoteurl: https://registry-1.docker.io

and afterwards add an extra option in /etc/docker/daemon.json so the file looks like the one below:

{
	"insecure-registries" : [
		"localhost:5000"
	],
	"registry-mirrors": [
		"http://localhost:5000"
	]
}

Docker

Thu, 04 Jun 2020 09:15:23 +0300

Preamble

Docker is quite popular and has a lot of benefits if used appropriately. This tutorial will hopefully help readers become more familiar with it. You snooze, you lose so let’s get into it.

Prerequisites

MUST:
- Have Linux installed
- Have docker installed
- Internet connection to download images
- Some Linux knowledge
OPTIONAL:
- Dockerhub account to push images to

Concepts and Architecture

Images and Containers

What are images, what are containers and how are they different? Images are a snapshot of a system while containers are a running instance of an image. For example, the nginx docker image has all the necessary bits installed to run nginx. When we start that image, there is now an nginx container running.

To see it action, we can run
docker image ls
to see all docker images on our system. To download a new one, also referred to as pulling an image, we can run docker pull nginx
or if a specific version is required,
docker pull nginx:1.17.10

Images are also immutable meaning they don’t keep any changes you make to them. If we were to go into an ubuntu container, run apt update && apt -y full-upgrade then restart the container, the updates would be lost. To demonstrate it, we can run
docker run --rm -i -t ubuntu
then when we see the shell prompt change, run
touch testfile && ls
followed up by exit. Running
docker run --rm -i -t ubuntu
again followed up by ls shows that the file named testfile does not exist there anymore. The interactive shell won’t really come up again until we get to debugging. Unlike virtual machines, containers are not meant to be used interactively.

Some notes so far:
- The --rm removes the container when the docker command exits (not necessary here but good for testing so we don’t fill up our system with unneeded containers)
- The -i -t gives us an interactive terminal to execute commands in this case (this is not available on every image, for example postgres and nginx show logs
  - In the case of nginx and postgres, even without (-it) they capture the terminal with logging so we use -d to run them in detached mode
  - The --name option gives a (hopefully) human-readable name to the container, especially useful when used with -d
- docker pulls the image we specified (in this case the ubuntu one) if it’s not on the system yet when we use docker run
- There is a special image named scratch if you want to build things from the lowest level allowable

Containers can be started and stopped but it’s more complex than that as is evident from our experimentation and notes this far. We’ll return to using nginx now since most images are going to be centered around the included application. Using
docker run -d --name ngx-alp nginx:alpine
we start an alpine-based nginx container running in detached mode.
After checking the output of
docker container ls
specifically the NAMES column, we can see that it did indeed start and was assigned the desired name. A quick
docker stop ngx-alp
will make it disappear from docker container ls but not from everywhere. If we try to run
docker run -d --name ngx-alp nginx:alpine
then docker will return an error since there is a container with that name but in stopped state. We can confirm that using
docker container ls --all
and then choose to start it again using
docker start ngx-alp
or remove it using
docker rm ngx-alp
Remember, we didn’t use --rm so the container did not get automatically removed after we stopped it. You might have figured it out already but the containers are given random unique names as well as a unique ID, both of which can be used to address them when we want to stop, start or remove them.

Ports

Many applications communicate over ports so how do we deal with that communication and move further along with our nginx example. The port required for a basic “this works” page to load from nginx is 80. However, if you were to run docker run nginx and try to curl http://localhost:80
it would not work. For an analogy with more conventional setups, think of it as port forwarding being required. Port 80 inside the container needs to be mapped to a port on the system in order to become accessible which is controlled by the -p option. I will use distinct ports to make the example more clear so here we go, run docker run -d -p --name ngx 3000:80 nginx
(which will use ``nginx:latest) and then run curl http://localhost:3000 This should return a bit of HTML and internal CSS to indicate that the default nginx page is reachable. We see that port 3000 outside of the container is mapped to port 80 inside of the container. To make sure, we can trydocker run -d -p –name ngx2 4000:80 nginx and thencurl http://localhost:4000 to see that it works and trydocker run -d -p –name ngx2 3000:80 nginx`
to check that it won’t allow us to start it since port 3000 is already used by another container.

Networking

From the get-go, docker has a bridge network that all containers connect to by default but don’t have the perks of name resolution like user-defined bridge networks do. What is a bridge network though and are there other types of networks?
We’ll go through them one by one and explain what they’re useful for.

Bridge

First, bridge networks. By utilizing NAT, in a similar way that a router does, they are able to have containers communicate over them (or not for security reasons). Each container connected to a bridge network gets its own IP address and there are iptables rules added to block or allow traffic between networks and containers (or ports as we saw in the previous section). While the default bridge network that docker creates is mostly fine for testing and messing around, user-defined networks have a few advantages that make them suitable for more proper use such as:
- DNS resolution to make containers able to communicate using names and not IPs which could change - Isolation since a container has to be explicitly added to them - Adding and removing a container can be done on the fly (without starting and stopping) - Configurability such as using a larger MTU and in general tweaking them for the use case - Sharing environment variables - Have effectively all ports exposed between them - Not having to use the deprecated --link flag
So it’s safe to say that using user-defined ones is worth it. How to go about it then? Time to find out.
In order to create a network we just have to run docker network create bridge-net or
docker network create --driver bridge bridge-net
and to delete it we use
docker network rm bridge-net
but how do we use it?
For this, we’ll need two containers. Let’s pick alpine since it includes the ping command. The flag to specify what network to attach the container to is --network so the full commands are as follows

1
2

docker run -dit --name alpine1 --network bridge-net alpine:latest
docker run -dit --name alpine2 --network bridge-net alpine:latest

The above will run two containers in detached mode and enable the interactive terminal. We can connect to that terminal,
docker attach alpine1
after which we get a prompt inside it. Let’s test out that name resolution by pinging it 3 times
ping -c 3 alpine2
which should work wonderfully. This means our containers can talk to eachother using their names while also having randomly assigned addresses from docker’s subnet. In case we forget the network’s details, it is possible to use docker network list
to find the network’s name followed by docker inspect bridge-net and get the network’s details in JSON format.

Macvlan

When integration with the network that the host is connected to is desired, we can use macvlan. Despite VLAN being a part of the name, using them is an option rather than a requirement. Let’s start with the possibly more familiar mode.

Bridge mode

In this mode, the network is bridged to a physical interface on the host and it integrates with the underlying network.

To see it in action, (I’ll assume a fairly standard home network scheme) we can look at

$ ip r
default via 192.168.1.1 dev eth0 metric 2
172.16.0.0/16 dev virbr0 proto kernel scope link src 172.16.0.1 linkdown
172.17.0.0/16 dev docker0 proto kernel scope link src 172.17.0.1 linkdown
172.18.0.0/16 dev br-b0ed5d210b62 proto kernel scope link src 172.18.0.1
192.168.1.0/24 dev eth0 proto kernel scope link src 192.168.1.2

to find our interface’s name, eth0 in this case and then create the network docker network create -d macvlan --subnet=192.168.1.0/24 --gateway=192.168.1.1 -o parent=eth0 macvlan-net
Connecting containers to it is done the same way we previously used. For example, docker run -dit --name alpine-on-macvlan --network macvlan-net alpine:latest

802.1q mode

I’m not going to go too in-depth about this mode since the amount of people with level 2 or level 3 managed switches is limited but it deserves at least a brief mention. If you’ve worked with VLANS on linux, you know that new interfaces are created, usually in the format the name of the physical parent followed by a dot . and then the VLAN number. To create a network linked to VLAN 31 on the eth0 interface, we use the same command as before but with a VLAN interface instead like so docker network create -d macvlan --subnet=192.168.1.0/24 --gateway=192.168.1.1 -o parent=eth0.31 macvlan31-net

Storage

So far we have not looked into how we work with storing data.
In the beginning it was stated and demonstrated that any changes made do not persist. How do people use containers to run file servers and databases then? The answer is bind mounts and volumes. Bind mounts map a specified directory on the host to one inside the container. Volumes on the other hand are managed through docker and are a bit more isolated from the host’s functionality. Every time we ran a container, an anonymous volume was created. Instead, we could have created a named volume using docker volume create ngx-vol
docker run --name ngx-with-vol -p 3000:80 --mount source=ngx-vol,target=/usr/share/nginx/html nginx
The volumes are under /var/lib/docker/volumes in case you were wondering. Volumes can be shared between two containers and be mounted read-only but we won’t be going into that right now. With bind mounts, it looks a bit different since we need to pick a directory on the host. If the directory doesn’t exist it will be created for us by docker. Let’s try it using
docker run --name ngx-with-bind-mount -p 3000:80 -v /tmp/ngx:/usr/share/nginx/html nginx
which will mount /tmp/ngx from the host to /usr/share/nginx/html in the container. This gives us an error if we try to curl http://localhost:3000
because the bind mounted host directory doesn’t get filled with the contents of the container’s target directory. There is an alternative syntax for this using the --mount option which is as follows
docker run -d --rm --name ngx-w-alt-bind-mount -p 3000:80 --mount type=bind,source=/tmp/nginx,target=/usr/share/nginx/html nginx
and will not create the directory on the host if it doesn’t exist. That’s the main gist about storage when it comes to docker. The thing most often found in the wild is bind mounts with the -v syntax and named volumes.

Installing

There are multiple ways to install docker-compose. From your distributions repositories, from third-party repositories, from the realease binary, from source, from pip but by far my favorite is as a docker container. Take a look over here if you’re interested, otherwise choose the way you prefer to get it installed to your system. After that, we’re ready to write some YAML.

Usage

Taking advantage of docker-compose is mainly by writing a file that describes how you want your services set up. Just make sure to pay attention to indentation because YAML is very picky about that (be prepared to give the spacebar a proper workout). What images will we work with?

Building Images

All the talk about using docker is good but with kubernetes dominating the industry as far as orchestration, docker finds its home as a way to build images and as a container runtime. How do you build an image then? It all starts with a Dockerfile.

Dockerfile

Similar to a Makefile but used for docker containers instead, the Dockerfile describes how to build your image. The first statement is FROM which specifies which base image to use. Other things you need is at least a little bit of familiarity with the tooling used by the project so you can discern what errors mean. Don’t be intimidated by that though, we’ll be going through it step by step.

Single-stage example build

For our starting example, we’ll use nginx and the following simple index.html:

<!DOCTYPE html>
<html>
	<head>
		<title>First Docker Image</title>
	</head>
	<body>
		<h1>It exists and it works.</h1>
	</body>
</html>

So we create a new file named Dockerfile and put the following in it

`1`	`FROM nginx:1.17.10-alpine`

We could bind-mount our files but shipping them inside the image is we’d need if this was a website we were packing so let’s do it. I’m making the assumption that index.html is in the current working directory

1
2

FROM nginx:1.17.10-alpine
COPY ./index.html /usr/share/nginx/html/

Without a port exposed, it won’t be accessible even if we bind ports to it so let’s do that next

1
2
3

FROM nginx:1.17.10-alpine
COPY ./index.html /usr/share/nginx/html/
EXPOSE 80

The final thing we should put in there is what command will be ran when the container starts. Running as a daemon is not desired since it will be in the foreground so we turn that off.

FROM nginx:1.17.10-alpine
COPY ./index.html /usr/share/nginx/html/
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Now for building the image we can run a simple
docker build -f Dockerfile .
to do the job. The -f specifies what file to use to build the image and . signifies the current working directory as the build context. We don’t necessarily have to specify the file every time, if it is named Dockerfile it will be used automatically.

That’s not fancy enough though. We should probably give it a name and a tag (otherwise it will be tagged with :latest) docker build -t first-site:0.0.1 .
Running the old faithful
docker image ls
should reflect that our custom image was built and tagged appropriately.

Congratulations, you just built your first docker image. But things are never this simple, right? We’re not always going to be working with websites let alone ones that have less than 10 lines of HTML. Let’s try something a bit more realistic. What about…a microservice written in golang exposing an api centered around a list of coffees?

Multi-stage golang example build

I am going to be using a microservice written by following a tutorial for demonstration. Ignore the included dockerfile, our main focus now is to understand the steps required to make images. After cloning the project and entering its directory, delete the included Dockerfile (it’s not as correct as the one we’re going to make anyway) and make an empty one. Just the same as before, we’re going to start with a FROM statement.

`1`	`FROM golang:1.14.2`

Picking version 1.14.2 since that is the latest at the time of writing and the code has been tested to work with it. Next, we’re going to go into the $GOPATH directory, in a subdirectory named src and then in a subdirectory with our project’s name. Note that we use /go/src/microsrv since $GOPATH is resolved to /go in this image.

1
2

FROM golang:1.14.2
WORKDIR /go/src/microsrv

We could have used the RUN statement and done RUN cd $GOPATH/src/microsrv but the WORKDIR command works at the Dockerfile level meaning that all subsequent commands will use it and it also creates the directory in case it doesn’t exist already. After that, it’s time to copy over the project files using COPY

1
2
3

FROM golang:1.14.2
WORKDIR /go/src/microsrv
COPY . .

this copies the contents of our current working directory outside of the container (project’s root) into the current working directory inside the container ($GOPATH/src/microsrv) Following that, we run the command to download all the required dependencies and source code but not build or install the project (that’s due to using -d). Here the RUNstatement is used which executes the command after it inside the container.

FROM golang:1.14.2
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...

Of course in the end we want to build and install the project so let’s do that

FROM golang:1.14.2
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...

Right after that is exposing the port, 9090 in this case

FROM golang:1.14.2
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...
EXPOSE 9090

The last piece missing is the command to be executed

FROM golang:1.14.2
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...
EXPOSE 9090
CMD ["microsrv"]

On to building the image now
docker build -t coffee-api:0.0.1 . and then running and testing it docker run --rm -d --name coffee-api -p 9090:9090 coffee-api:0.0.1 curl http://localhost:9090/products
which should return a JSON-formatted object of all the coffees and their public-facing details. This is all fine and dandy but if we check docker image ls we see that the resulting image is about 1GB in size which just won’t fly. We have to optimize but how? One way is to think of what’s needed in compile-time compared to run-time. The entire language is not required after the project has been built and not much if any operating-system level tools are required other than for debugging.

To achive this separation we can use multi-stage builds. The first step is taking out runtime-specific things out of the build stage. What port gets exposed and what command is ran when the container starts is not in the build stage’s scope so let’s remove those.

FROM golang:1.14.2
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...

Time to build the second stage. First we’ll use an alias for the first stage in order to be able to copy stuff from it.

FROM golang:1.14.2 as build
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...

With that done, let’s define the second stage inside the same file. We’ll use busybox, a very small image that has just enough to be usable for our case. Since the default image uses glibc as its C library, we’ll specify that tag since busybox doesn’t use it by default.

FROM golang:1.14.2 as build
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...

FROM busybox:glibc

Here is where the alias comes in handy when copying the resulting binary (located at $GOPATH/bin/microsrv) from the first stage

FROM golang:1.14.2 as build
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...

FROM busybox:glibc
COPY --from=build /go/bin/microsrv /

And finally we add the two lines that were removed

FROM golang:1.14.2 as build
WORKDIR /go/src/microsrv
COPY . .
RUN go get -d -v ./...
RUN go install -v ./...

FROM busybox:glibc
COPY --from=build /go/bin/microsrv /
EXPOSE 9090
CMD ["/microsrv"]

All that’s left now is to build (I incremented the version number so the image doesn’t steal the previous one’s tagged name but normally you want the docker image version to match the version of the application) docker build -t coffee-api:0.0.2 . then run and test
docker run --rm -d --name coffee-api -p 9090:9090 coffee-api:0.0.1 curl http://localhost:9090/products

If everything went according to plan, a JSON object with the coffees was returned to you and you’ve built your first multi-stage docker image (which you should remember to stop using docker stop coffee-api). We’re not done yet though, maybe it’s time we throw our old pal nginx back into the mix and move from the backend to the frontend.

Multi-stage reactjs example build

Now that our backend is all packed up, time to see how we’d go about doing the same thing with the frontend. This time we have to interact with nodejs during the build but it’s not required for runtime. I think you get an idea of what’s to come so let’s not hesitate.

The project I’ll be using for the following demonstration is a simple one-page counter application. Same as the previous example, we’ll clone it, change into its directory and delete the included Dockerfile since we’ll be remaking it from scratch. As I mentioned, it’s good to know the project’s tooling, in this case we need node and npm for building the application but not for running it. We’ll start with a FROM statement to grab the node image but pre-emptively optimize by going with the alpine flavour. The size comparison between the regular version is as follows and should explain why this is a better choice.

1
2
3

$ docker images | grep node
node                             alpine              0854fcfc1637        2 days ago          117MB
node                             latest              a511eb5c14ec        2 days ago          941MB

Coming in at over 8 times the size of the alpine one, the main image is massive and doesn’t include anything we need and won’t get otherwise. Starting with our Dockerfile then, we pick the latest (at the time of writing) node image based on the latest alpine version and alias it to build since it will be our build stage

`1`	`FROM node:14.1.0-alpine3.11 as build`

We then change our current working directory to /app and move all of our project’s freshly cloned files in there

1
2
3

FROM node:14.1.0-alpine3.11 as build
WORKDIR /app
COPY . .

Now on to getting everything installed and ready for the build. Since it’s a reactjs website and the scripts that will be run (as defined in package.json) are from the react-scripts package (which needs to be installed globally) we will opt for installing that first before the usual npm install. Here is the Dockerfile up until now

FROM node:14.1.0-alpine3.11 as build
WORKDIR /app
COPY . .
RUN npm install --global react-scripts
RUN npm install

To finish up the build stage one last command is required in order to generate the files that nginx will serve

FROM node:14.1.0-alpine3.11 as build
WORKDIR /app
COPY . .
RUN npm install --global react-scripts
RUN npm install
RUN npm run build

There we go then. The resulting files will be inside the container in the /app/build directory. No instructions for exposing any ports or the starting command we specified since that’s for the runtime stage. Speaking of which, you might have already guessed what the rest of the Dockerfile will look like. Start with an nginx alpine image, copy over only the necessary files to it from the build stage, open up port 80 and start nginx in foreground mode. Here is the final result

FROM node:14.1.0-alpine3.11 as build
WORKDIR /app
COPY . .
RUN npm install --global react-scripts
RUN npm install
RUN npm run build

FROM nginx:1.17.10-alpine
COPY --from=build /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

After we’re done with that, we should actually build the image and give it a descriptive tag
docker build -t reactjs-counters:0.0.1 .
followed up by starting it in order to test docker run --rm -d --name reactjs-counters -p 80:80 reactjs-counters:0.0.1 and then visit
http://localhost
in your browser of choice to see if it works.

Publishing Images

We’ve made our image and sharing is caring so how do we make it available to the world and where are images stored? The go-to place for getting images is dockerhub, a public docker registry. Docker registries are where images are stored and distributed from. You can also run your own if you wish but that’s for another time. Right now, we have two images built and ready to be shipped. Well…almost. We could certainly upload them as they are and then try to pull them but we’d find that we need to specify a tag. That happens because they’re not tagged as :latest which is the default tag. One step at a time though.

DockerHub

First, you should make an account if you don’t have one already by going over on the dockerhub website and signing up. Next up, run docker login in a terminal to, you guessed it, log in. This will allow you to push images to your account. I already got mine so we’re ready to start.

Tagging

Since we just finished making our reactjs-based image, let’s use it here too. Previously we only tagged it as reactjs-counters:0.0.1 but we need something more now. The format of the image name should be username/image:tag. There at least 2 ways to go about this. Either rebuild the image and tag it differently or tag the existing one. I’ll go over both of them.

First, let’s look at the “I wish I’d known sooner” method. As we know, images have a unique identifier. This is under the IMAGE ID column in docker image ls output. A single image can be tagged with different names. So here is the way we’d build it with multiple tags, one of them being the properly versioned one and the other one being latest (don’t forget to substitute username with your actual username):
docker build -t username/reactjs-counters:0.0.1 -t username/reactjs-counters:latest .
And there we have it. Simple enough, ain’t it? But how about tagging an already existing image? Someone might not fancy rebuilding theirs.

That’s what the docker tag command is for. All we have to do is find the image ID from the output of docker image ls and then tag it twice. Here we go then (assuming this is the image ID 7755c1923b8a):

1
2

docker tag 7755c1923b8a username/reactjs-counters:0.0.1
docker tag 7755c1923b8a username/reactjs-counters:latest

Pushing

All that’s left is to docker push the image of our choice and make it available so other people can docker pull it.

1
2

docker push username/reactjs-counters:0.0.1
docker push username/reactjs-counters:latest

And that’s it!
We have successfully taken an application, written a Dockerfile for it, built an image for it and published it to DockerHub!

Outro

Hopefully you’ve learned something useful about docker after reading this, I had fun writing it and looking into things that had faded from my memory. Docker is an interesting technology that can be leveraged in many ways to improve development and production workflows everywhere from a single board computer to a fleet of servers in a datacenter. Let me know what you thought about it and I hope you have a good rest of your day.

Docker on inherent site

Docker Multi-Binary Images

Problems in deploying distributed applications

Lightbulb moment

How do

Dockerfile

Kubernetes deployment manifests

Conclusion

Beyond Docker

Preamble

Prerequisites

Docker-compose

Installation

First Use

Writing the docker-compose file

Running the application

Healthchecks

LAN-only setup with reverse proxy

Reverse Proxies

Writing the docker-compose.yml

Logs

Backups

Registry

Local image storage

Pull-through cache

Docker

Preamble

Prerequisites

Concepts and Architecture

Images and Containers

Tags

Ports

Networking

Bridge

Macvlan

Bridge mode

802.1q mode

Storage

Installing

Usage

Building Images

Dockerfile

Single-stage example build

Multi-stage golang example build

Multi-stage reactjs example build

Publishing Images

DockerHub

Tagging

Pushing

Outro