Chameth.com - posts like understanding-docker-volume-mounts, utility-user-stories but not finding-an-awkward-bug-with-claude-code, why-you-should-be-using-https

On the utility of user stories

2021-10-16T00:00:00Z

User stories are a staple of most agile methodologies. You’d be hard-pressed to find an experienced software developer that’s not come across them at some point in their career. In case you haven’t, they look something like this:

As a frequent customer,
I want to be able to browse my previous orders,
So that I can quickly re-order products.

They provide a persona (in this case “a frequent customer”), a goal (“browse my previous orders”) and a reason (“so that I can quickly re-order products”). This fictitious user story would probably rank among one of the better ones I’ve seen. More typically you end up with something like:

As a user,
I want to be able to login,
So that I can browse while logged in.

This doesn’t really provide a persona or any proper reasoning. It’s just a straight-forward task pretending to be a user story. If this is written in an issue then it provides no extra information over one that simply says “Allow users to login”. In fact, because it’s expressed so awkwardly I’d argue that it’s worse.

This kind of task-disguised-as-a-user-story problem becomes more obvious when people try to write technical tasks in the same way:

As a developer,
I want to refactor the JobFactory,
So that I can work with it more efficiently in the future.

This just says “Refactor the JobFactory”. If you wrote that in a ticket you’d probably feel bad for not describing it very well, but somehow when it’s dressed up as a user story it feels more valuable.

Does the user really want that?

One thing that really irks me about user stories is that it lets you twist your business objectives into sounding like they’re the user’s idea: the story becomes a post-hoc justification for a task you decided was required.

Say you’re making a mobile app for an online book store, and your team for whatever reason has a target of increasing the number of users who view the daily book-of-the-day offer. Maybe you do some interviews and users tell you they forget to check in each day to see what the offer is. How can you funnel more users there?

As a mobile app user,
I want to receive a push notification whenever a new book-of-the-day is available,
So that I have the chance to buy the book.

Some users probably do want such a thing, but I’d argue the vast majority of them do not. Imagine if every app on your phone alerted you whenever there was a new deal, or popped up a dialog whenever you went near a physical shop they had vouchers for…

Obviously in the cold reality of capitalism businesses make money by doing things not strictly in the interests of users¹. When written up like this it becomes so painfully disingenuous, though. Despite writing a user story that starts with the words “As a user”, you’re not really putting yourself in the user’s shoes.

Who even is the user?

One of the big benefits of user stories comes from using personas to describe users. It’s also one of the things that’s rarely actually done, at least in my experience. Looking at Google Trends you can see the rise of searches for “user story” as agile slowly takes over the world, but the movement in searches about personas is very slight:

Graph showing relative search frequency for user stories against user personas

A lot of the time stories are just written with “As a user”, or have some adjectives tacked on to the start (“as a mobile user”, “as a logged-in user”). The best I’ve ever seen in the wild was specifying the class of user like in the example at the start: “as a frequent customer”, or “as a visually impaired user”.

The problem with using these classes is it requires you to come up with them when you’re writing the story. Maybe one day you think about visually impaired users, but the next you don’t. Maybe Bob thinks about certain classes of users, but Alice concentrates on different ones.

The ideal way to solve this is to come up with personas that all the team understand. For example:

Kiera is addicted to books. She reads across genres, and often buys books to gift to her friends and family. She has piles and piles of books to read, but that doesn’t stop her ordering more if she sees a good deal. She likes receiving new books almost as much as reading them, and opts for the fastest delivery available.
Sharon is a slow, methodical reader. She buys one book at a time when she’s close to finishing her current one, and gifts or resells her old books. She almost exclusively reads Science Fiction, and will generally read complete series from start to finish. She’s short-sighted and often struggles when using mobile phones or computers.

You’d probably want 2-4 personas that collectively represent most facets of your userbase. They can be a lot more fleshed out than these - if you search for example user personas you’ll find many beautifully presented examples that have complete backgrounds including hobbies, education levels, and so on. Even with this minimal level of detail, though, I’d argue they’re more useful than just writing things in a standard user story form.

Thinking back to the story about push notifications, writing it to use one of these two personas forces you to think about the trade-offs involved. Kiera probably would like a notification, but it would annoy and possibly confuse Sharon. This then leads you down the path of considering how to accommodate both types of user — maybe adding it as an option, or doing some fancy machine learning, etc. The conversation is now focused around the users, rather than steamrolling over them to reach a business objective.

You’re holding it wrong

The problems I’ve described are not a problem with user stories per se, but rather common issues with how they’re used. But there’s only so many times you can tell people they’re holding a tool wrong before you have to accept that maybe the tool was badly designed.

Considering features from the perspective of multiple personas is the single best thing you can possibly do to ensure you’re providing value to your users. You don’t even need to write things in the typical user story style to benefit from this.

Tacking “As a user,” to the start of all your JIRA tickets isn’t being agile, and isn’t good for users, even if it lets you tick a box somewhere. In some cases this lip-service to users is actively detrimental to them. We should be valuing users and personas over stilted templates and check-box exercises (remind you of anything?).

As a user, I want to pay more money for the things that I buy, so that the company’s CEO can afford to go to space. ↩︎

Understanding Docker volume mounts

2019-04-01T00:00:00Z

The Docker project logo

One thing that always confuses me with Docker is how exactly mounting volumes behaves. At a basic level it’s fairly straight forward: you declare a volume in a Dockerfile, and then either explicitly mount something there or docker automatically creates an anonymous volume for you. Done. But it turns out there’s quite a few edge cases…

Changing ownership of the folder

Perhaps the most common operation done on a Docker volume other than simply mounting it is trying to change the ownership of the directory. If your Docker process runs as a certain user you probably want the directory to be writable by that user.

At first we might try something like:

FROM alpine
RUN adduser -D -u 1113 test123
USER test123
VOLUME /testing

But changing the user doesn’t seem to have any effect on the volume. Why? Checking the docs for the USER instruction shows that only affects certain future operations — namely RUN, CMD, and ENTRYPOINT. It doesn’t affect the VOLUME instruction; if it did, you’d probably just get a permission denied error unless the user you switch to had privileges to create mount points.

OK, so instead we might try using the good old chown command:

FROM alpine
RUN adduser -D -u 1113 test123
VOLUME /testing
RUN chown test123 /testing

But again, the directory is just owned by root at runtime. Back to the docs, this time for the VOLUME instruction and towards the bottom is this little tidbit:

Changing the volume from within the Dockerfile: If any build steps change the data within the volume after it has been declared, those changes will be discarded.

As soon as Docker hits the VOLUME instruction the directory becomes a mount point, and anything we do to the temporary volume mounted there is discarded during the build process. So we have to change the ownership before the instruction, which may seem a little counter-intuitive:

FROM alpine
RUN adduser -D -u 1113 test123
RUN mkdir /testing && chown test123 /testing
VOLUME /testing

Now when the container runs, the /testing directory is owned by the test123 user. It’s not quite over, yet, though. This works if we let Docker create a volume automatically for us, or if we create a named volume and mount that; if we try and mount a host directory, though, it falls flat:

$ docker run --rm -it -v "$PWD/testing:/testing" testing ls -al /testing
total 8
drwxr-xr-x    2 1000     1000          4096 Apr  1 19:39 .
drwxr-xr-x    1 root     root          4096 Apr  1 20:44 ..

Docker handles mounting host directories differently to mounting volumes, even though the syntax is basically the same. Host directories are bind mounted directly into the container, so the permissions and ownership are the same as the directory on your host. The only way to fix them are to either change the permissions on the host, or have the container change them at runtime (assuming it has sufficient privileges).

One final wrinkle in all this happens when you use the same volume in multiple containers. Here we have two images built from the Dockerfile above, one with userid 1113 and one with userid 1114:

$ docker volume create testing
testing

$ docker run --rm -it -v testing:/testing testing1113 ls -nal /testing
total 8
drwxr-xr-x    2 1113     0             4096 Apr  1 19:49 .
drwxr-xr-x    1 0        0             4096 Apr  1 20:51 ..

$ docker run --rm -it -v testing:/testing testing1114 ls -nal /testing
total 8
drwxr-xr-x    2 1114     0             4096 Apr  1 20:47 .
drwxr-xr-x    1 0        0             4096 Apr  1 20:52 ..

$ docker run --rm -it -v testing:/testing testing1114 touch /testing/Hello

$ docker run --rm -it -v testing:/testing testing1113 ls -nal /testing
total 8
drwxr-xr-x    2 1114     0             4096 Apr  1 20:52 .
drwxr-xr-x    1 0        0             4096 Apr  1 20:53 ..
-rw-r--r--    1 0        0                0 Apr  1 20:52 Hello

$ docker run --rm -it -v testing:/testing testing1114 ls -nal /testing
total 8
drwxr-xr-x    2 1114     0             4096 Apr  1 20:52 .
drwxr-xr-x    1 0        0             4096 Apr  1 20:52 ..
-rw-r--r--    1 0        0                0 Apr  1 20:52 Hello

Can you see what’s going on? When the volume is empty, the ownership changes based on the mount point in the container. Once it has something in it, the ownership is fixed.

So Docker behaves differently with regard to permissions:

when the folder is mounted from the host vs a volume
when the volume is empty vs having content

Pre-populating mounts with files from the image

One of the more esoteric features of the way Docker handles volume mounts is that in some cases files from the image are copied over into the container. For example:

$ docker volume create testing
testing

$ docker run --rm -it -v testing:/etc testing sleep 1

$ docker run --rm -it -v testing:/tmp testing ls -al /tmp
total 184
drwxr-xr-x   15 root     root          4096 Apr  1 20:58 .
drwxr-xr-x    1 root     root          4096 Apr  1 20:59 ..
-rw-r--r--    1 root     root             4 Jun  7  2018 TZ
-rw-r--r--    1 root     root             6 Dec 20 21:31 alpine-release
...

The first container we run mounts the newly created testing volume at /etc. Docker copies all the existing files and folders into the volume; when we then run the second container with the volume mounted at /tmp, we can see all the files that were in the first container’s /etc.

As with permissions, this behaviour is anything but consistent. Say we switch from a volume to a host directory:

$ mkdir testing
$ docker run --rm -it -v "$PWD/testing:/usr/bin" testing sleep 1
$ ls -al testing
total 8
drwxr-xr-x 2 root  root  4096 Apr  1 22:05 .
drwxr-xr-x 3 chris chris 4096 Apr  1 22:05 ..

Nothing is copied in, and inside the container the folder will be empty. Based on our discoveries with permissions, it’s reasonable to assume the same will happen with a non-empty volume too:

$ docker volume create testing
testing

$ docker run --rm -it -v testing:/testing testing touch /testing/Hello

$ docker run --rm -it -v testing:/usr/bin testing sleep 1

$ docker run --rm -it -v testing:/tmp testing ls -al /tmp
total 8
drwxr-xr-x    2 root     root          4096 Apr  1 21:09 .
drwxr-xr-x    1 root     root          4096 Apr  1 21:09 ..
-rw-r--r--    1 root     root             0 Apr  1 21:08 Hello

So at least that’s consistent. If you’re very observant, though, you might notice I switched from /etc/ to /usr/bin in the examples. That’s because within the container /etc/ has some files bind-mounted into it, such as /etc/resolv.conf, and these do always result in files being created in the mounted volumes or folders:

$ mkdir testing
$ docker run --rm -it -v "$PWD/testing:/etc" testing sleep 1
$ ls -al testing
total 8
drwxr-xr-x 2 chris chris 4096 Apr  1 22:12 .
drwxr-xr-x 3 chris chris 4096 Apr  1 22:12 ..
-rwxr-xr-x 1 root  root     0 Apr  1 22:12 hostname
-rwxr-xr-x 1 root  root     0 Apr  1 22:12 hosts
-rwxr-xr-x 1 root  root     0 Apr  1 22:12 resolv.conf

Summary

Docker treats mounting host folders and mounting volumes differently. Don’t just assume that you can swap one for another and get the exact same behaviour.
Empty volumes will inherit permissions and files from the image they are mounted in; non-empty volumes and host folders will not.
Relying on Docker copying files into volumes is a very bad idea, as if you change those files in a future version of your image they will not be copied unless the volume is deleted and recreated.

I can’t find anywhere that these points are documented properly; if you know of anywhere, please drop me a message!