Writing a Dockerfile for catscii

Now that our service is production-ready, it’s time to deploy it somewhere.

There’s a lot of ways to approach this: what we are going to do, though, is build a docker image. Or, I should say, an OCI image.

This is still a series about Nix, but again: because the best way to see the benefits of Nix is to do it without Nix first, we’ll use only Docker’s tooling to build the image.

Docker has its own docs about that. Many times I’ve followed all the instructions, only to realize near the very end that they actually have a convenience script.

Cool Bear's Hot Tip

There’s also docker packages in the Ubuntu repositories, but it tends to lag behind official releases by quite a bit, so we won’t bother with it.

From VS Code’s integrated terminal, we can run the convenience script:

Once that’s done, we can follow the Linux post-install steps:

Cool Bear's Hot Tip

As mentioned in the Docker docs, The docker group grants root-level privileges to the user. For details on how this impacts security in your system, see Docker Daemon Attack Surface.

After that, we can reboot the virtual machine, or, until we do, we can make sure we run newgrp docker in any terminal we want to use docker in.

That should allow us to run docker images.

All good, time to write a Dockerfile!

We’ve developed our service on Ubuntu, and we can use it as a base for our image, too.

I forget, what version of Ubuntu are we using again?

Ah well, we can use lsb_release to find out:

But if we didn’t have it (since it doesn’t ship in all distributions by default), we could just read the contents of /etc/os-release:

So, let’s create a Dockerfile in the root of our repository, and… try to install Rust in there, for a start:

Note, if you encounter an error related to rustup not being able to choose a version of cargo during the cargo build –release step, you might need to ensure that the rustup cache is available during the rustup installation. Modify the rustup installation command in your Dockerfile as follows:

This ensures that the rustup cache is mounted, potentially resolving the issue.

Cool Bear's Hot Tip

set -eux allows running multiple commands in a single RUN statement (which then counts as a single layer), while printing all commands (-x), erroring if a variable we use isn’t bound (-u), and failing if one of the commands fail (-e).

And try to build it:

No, wait, abort! (Seriously, hit Ctrl-C). It’s transferring hundreds of megabytes to the Docker daemon, something’s wrong.

But… we don’t have hundreds of megabytes of source code?

No we don’t. But we have a few gigabytes of artifacts in target/:

Oh wow. Debug info is heavy! target/debug/ is 2.6G just by itself.

Yeah. Some of it is just due to iterating though — doing cargo clean && cargo build brings it down to “just” 1.8G, but yes, debug info is heavy.

Anyway we don’t want that target directory to be part of Docker’s build context, so, much like we ignore it in .gitignore, we can ignore it in .dockerignore:

Ah but of course. The base ubuntu:20.04 image doesn’t have curl.

Well, no matter, let’s install it:

Ah yes. The ubuntu docker image doesn’t actually have APT repository information: that’s been culled to reduce the image size. So we have to run “apt update”.

Cool Bear's Hot Tip

“apt” is a different (more modern) command than “apt-get”, and the former warns to “use with caution in scripts”, since its output isn’t stable. But we’re not parsing the output of either command, so it’s fine.

Let’s amend our Dockerfile to:

This time, we get this:

So now, in that docker image, we have rustc!

Which is good and bad. It’s good, because we need rustc to build our service, but it’s bad, because we don’t need rustc at runtime. We’ll get to that later.

First let’s get the service building at all:

Cool Bear's Hot Tip

The ADD command can also copy stuff from the “build context” to the “builder”, but Docker documentation recommends against that.

The COPY command has somewhat surprising behavior when passed directories. The following:

COPY src Cargo.toml Cargo.lock ./

…doesn’t create a src/ directory in the builder. It copies the contents of the src folder there. Hence the two separate COPY invocations.

So, again there’s two problems here. The long-term problem is that when compiling, cargo needs to fetch the crates.io index. And because of the way the Dockerfile is set up, it’ll have to do so from scratch every time.

Also, at the time of this writing, sparse registries are not the default (even though they work pretty well already), so in concrete terms, that means cloning a large Git repository every time.

But we’ll get to that later: the main problem is that we’re getting an error: it says it can’t find the cc linker.

Fine then, let’s try installing gcc at the same time we install curl:

Because the layer we’re changing is at the very beginning of our Dockerfile, it’s going to do everything again, including installing rustup, cloning the crates.io registry, etc.

Hope you have a fast internet connection!

Cool Bear's Hot Tip

The fact that we’re playing “Docker golf” right now (because there’s so many things to get right) explains why there’s a bit of a copy-paste culture around Dockerfiles.

If you have a Dockerfile that works, it’s tempting to copy it for other projects, and the end result is large files, with a lot of parts that nobody’s quite sure why.

I’ve had time to check all my messages and it’s still downloading gcc and friends. I guess I’ll cancel the build and show you a little APT tip: APT has “recommended” and “suggested” packages. By default, it installs the “recommended” packages, which in this case, is a lot of packages.

We can disable that behavior with --no-install-recommends:

Cool Bear's Hot Tip

This tip is Ubuntu-specific. Other distributions have other package managers that work differently. But Ubuntu is a typical enough server-side target that it’s not that surprising that this series focuses on it.

Note that at this point, because we’ve built the image a bunch of times, Docker is using a bunch of disk space for nothing: since we’ve changed the first layer, we’re not going to be re-using anything in cache.

We can reclaim that space with docker system prune:

And even more space with --all, or -a for short (which deletes all unused images, not just dangling ones):

Now, a lot fewer packages are installed, but it fails again with:

This occurs because we’re using curl to download the rustup installer over HTTPS, and in order to verify the certificate, curl must consult a “root certificate bundle”.

There’s such a bundle in Ubuntu’s ca-certificates package, but it’s not a hard dependency of curl, merely a recommendation.

So… let’s add it:

At this point, it gets as far as downloading the latest rust stable using rustup-init, but.. we should probably be able to cache that, right? It doesn’t sound right to have to download that every time we change an earlier layer.

BuildKit, the newer Docker builder backend, lets us mount some folders as “cache”.

This is a “newer” Docker feature, so we’ll need to opt into it within our Dockerfile with a load-bearing comment. Here’s our full updated Dockerfile:

Running this doesn’t work:

Because, at least on the version of docker we installed into our Linux VM, BuildKit isn’t enabled by default.

We can override this globally, or every time we run docker build:

Note, if you are running Docker 23.0.6 you can omit DOCKER_BUILDKIT=1

Well… that’s also caused by --no-install-recommends. Did you know GCC has a runtime component? And that it’s not a direct dependency of the gcc package on Ubuntu, but rather a “recommendation”? Yeah.

More golfing!

Our next error is…

There’s two problems here: we don’t have pkg-config and we don’t have the OpenSSL development package.

We could be golfing all day, let me fast forward to this point:

One of the reasons this is taking forever for me, by the way, is because it’s grabbing everything from archive.ubuntu.com. It seems like they’re doing DNS load balancing, but your luck may vary WILDLY from one run to the other.

Lucky run (landed somewhere in the UK):

Unlucky run (landed in Boston Massachusetts, USA):

These are all just Apache servers by the way:

Well, at least they’re dogfooding.

Anyway, with the last changes, our application builds!

It, however, doesn’t run:

That seems.. suspicious, let’s start a shell inside the container to look around:

Wasn’t /target in a cache-mount?

Oh. Right 🙃 That explains why it doesn’t actually end up in the final image.

It’s also a bit annoying to have to specify the command we want to run, so we can just set a default in the Dockerfile:

Oh hey! It runs! Let’s pass it a few environment variables. They’re already in our local environment, due to our .envrc / direnv setup, so we can just mention them by name:

And now it listens on some port! Unfortunately:

• That port is only accessible from within the Docker container right now
• Doing “Ctrl-C” to kill the container doesn’t work.

So first off, let’s kill our running container:

If you look up “Ctrl-C docker not worky send help” online, you’ll find tons of advice that doesn’t work.

Ctrl+C from a Linux shell, sends the “INT” (interrupt) signal, and the default handler for that exits the process. It certainly works outside the container:

The explanation lies in the Docker docs:

A process running as PID 1 inside a container is treated specially by Linux: it ignores any signal with the default action. As a result, the process will not terminate on SIGINT or SIGTERM unless it is coded to do so.

Docker run reference

We could add an explicit handler for SIGINT with something like ctrlc, and it’d work. Or we could simply have another process as PID 1, like /bin/sh:

But because I feel bad even suggesting it, let’s implement “the proper way” instead.

Not only will we handle SIGINT, we’ll also make it so it does graceful shutdown, which means it’ll finish handling in-flight requests before stopping.

We don’t actually need the ctrlc crate, because tokio provides an asynchronous way to deal with signals.

The end of our main function becomes:

That’s all it takes!

Let’s not forget to rebuild the app:

And then we can run it, publishing port 8080 so we can actually reach it:

And then, from another terminal (CmdOrCtrl+Shift+Backtick in VS Code, or a plus button somewhere to the top-right of the Terminal pane), we can reach it:

And, thanks to VS Code’s automated port forwarding functionality, we can even access it in a local browser!

Cool Bear's Hot Tip

Sometimes VS Code’s automated port forwarding will get in an inconsistent state (especially if your host computer’s gone to sleep a couple times and it had to reconnect to the VM over SSH).

Using the “Reload Window” command from the command palette (“F1” to open) usually sorts this out.

So, mission accomplished?

Not really. We want to run this in production!

Comment on /r/fasterthanlime

Here's another article just for you:

A terminal case of Linux

Sep 24, 2021

29 min #rust · #linux

Has this ever happened to you?

You want to look at a JSON file in your terminal, so you pipe it into jq so you can look at it with colors and stuff.

Cool Bear's Hot Tip

That’s a useless use of cat.

…oh hey cool bear. No warm-up today huh.

Sure, fine, okay, I’ll read the darn man page for jq… okay it takes a “filter” and then some files. And the filter we want is.. . which, just like files, means “the current thing”:

Read more