I own a bike. It’s not an expensive bike, but in terms of functionality I genuinely think it’s the pinnacle of human mobility and freedom. It takes up little space, gets me around quickly, keeps me fit, and runs on calories — arguably the most abundant fuel on the planet. It’s a simple machine, yet hard to imagine life without. Put on a pair of studded tires and you can ride it 365 days a year, in almost any weather. The one mechanical service I couldn’t fix myself cost me 500 kroner.

A human tendency I’ve become increasingly aware of is what I like to call “comfort creep,” or hedonic adaptation. The idea is simple: once we get used to a certain level of comfort, that level quietly becomes the baseline. Going below it doesn’t feel neutral — it feels like loss. We start taking comfort for granted, and worse, we begin tying it to our identity and sense of self-worth. Suddenly even small sacrifices — like not choosing the “Pro” model of the new iPhone — feel like a subtle status drop. And just like that, we justify spending money on things we don’t really need, all to preserve a slightly inflated sense of well-being. Once other people start noticing or commenting on your nice things, the whole “keeping up with the Joneses” mechanism kicks in, and the spiral of comparison accelerates.

Things get even more interesting when you bring in René Girard’s theory of “mimetic desire.” The core idea is unsettlingly simple: our desires are not entirely our own. We learn what to want by watching what others want. We don’t just desire objects — we desire them because someone else has marked them as desirable. That sets off a subtle but powerful cycle of imitation, comparison, and consumption. Your next-door neighbor goes to a five-star restaurant, and suddenly you find yourself craving the same experience.

It helps explain why celebrities and influencers have such an impact on consumer behavior. They don’t just advertise products; they model desire itself. Before we know it, we’re not buying something because we need it, but because it fits into a hierarchy of wanting we never consciously signed up for.

But back to the story.

Mindful of comfort creep, I’ve never felt the urge to buy an expensive car. My first car was a 2000 Honda Civic hatchback. Japanese reliability, almost no features. It did one thing well: got me from A to B. In 2018 my girlfriend crashed it right before we were going on holiday, and we got a rental while it was being repaired — a 2015 Ford Fiesta. Modest by any standard, but compared to the Civic it felt like stepping into the future. Heated seats. CarPlay. Civilization.

That small jump in comfort felt enormous. And that’s the point. Even minor upgrades recalibrate our baseline. What once felt luxurious becomes normal almost overnight. Keeping the bar low is, in a way, a hack: if your baseline is modest, even small improvements feel like abundance.

The same thing happened with phones. My 2020 iPhone SE — the cheapest model — served me faithfully for six years, until newer iOS updates slowed it down to near unusable levels. I had an old iPhone 12 Pro lying around and switched. On paper, a big upgrade. In practice? Within weeks it just felt normal.

A couple of years ago I read the book "Jakten på den grønne lykken" by Bjørn Stærk. He argues that we are born as evolved apes, but increasingly act like giants — maximizing our resources and capabilities, taking up more space, consuming far beyond our needs. We’ve become extraordinarily comfortable, but in the process created problems we don't really have.

Me being privileged enough to ride my bike year-round feels like a quiet protest against that. It’s a reminder that we can get by with less — and that sometimes less really is more.

What scares me isn’t luxury. It’s how quickly it becomes normal.

Over the years I have read a lot of articles and blog posts on note-taking and knowledge management. I'm an avid reader, and one of my first blog posts was about how I organize my reading lists. That post is 11 years old now, and I like to think I've grown a bit since then (intellectually, that is), but I can confirm that the Trello board described in that old mind-fart of a post is still in use today.

One thing that keeps popping up is the importance of having a system to capture and organize what you learn. Without such a system, knowledge is easily forgotten or lost in the chaos of everyday life. Over the years I have tried various ways of capturing notes from the books I read. It might be true that the best books you read will change the way you think and act in the world without you writing a single note or quote down, but let's be real: those books are few and far between. Most of the time, if you want to remember what you read, you have to write something down and return to it later to refresh your memory.

Handwriting: Great for Memory, Terrible for Retrieval

The first couple of years I used good old notebooks extensively, and to some degree still do. The science is quite clear here: if you want to remember something, writing it down by hand is the best way to do it. The problem with notebooks—apart from being hard to organize and search through later—is that reviewing a book you just read becomes a time-consuming exercise in hunting for squiggly lines and pencil highlights, then transcribing them into a notebook, only to never look at them again. Don't get me wrong, I had lots of nice dates with myself at cafes, writing down notes from books I had just read, but the return on investment was low—and there is frankly not enough time in the day for that (throw in a love for endurance sports and there you have it).

The killer "system"

It's no surprise then that I have gravitated towards digital book knowledge systems over the years, but instead of shoehorning my notes into a generic note-taking app like [fill in your favorite app here that will be gone in 2 years], I have built my own simple solution around Markdown files stored in a Git repository, plus a few small extraction scripts. Throw in a tiny backend for serving them, and there we are. It's simple, it's flexible, it's plain text, and it will outlive most apps out there. The basic building block is this Markdown template:

# Book Title

<![]()>

### Metadata

- Author:
- Full Title:
- Category: #books

### Highlights

-

That's the target template. About 99% of the source material comes from four main sources:

• Amazon Kindle
• Apple Books
• Physical books
• Manual transcription directly into Markdown files

Kindle highlights are by far the easiest to capture.

Whenever I highlight something on my Kindle device or in the Kindle app, it is automatically synced to my Amazon account. When I'm done reading, I send the notes to myself via email using the "Export Notes" feature in the Kindle device or app. The exported notes come in a simple HTML format that is easy to parse. I have a small script that extracts the highlights and formats them into the Markdown template above.

A similar process is used for Apple Books highlights, although the export step is a bit more manual.

The trick is to select all highlights and tap "Share". The easiest approach is to share them to yourself via email to get a standardized format. Again, a small script does the same job as for the Kindle notes.

The last piece of the puzzle is physical books. This is how I read most books, and for a long time manual transcription was the only way to capture notes from them. Thankfully Apple solved this for me in iOS 15 with the introduction of Live Text in photos:

Now I just open the camera app on my phone, select the text in the book, and copy and paste it into the Markdown format I keep in the Notes app. From there it's just formatting and adding metadata. Voilà—note captured.

Random Wisdom on Demand

All my book notes are stored in a public GitHub repository. This makes it easy to search through them later, and if I want to look something up quickly, the GitHub Markdown viewer does a great job.

What I've found to be the real killer feature is the random lookup script I wrote a while back. It's a simple backend that keeps all the notes in memory, with an API endpoint that picks a random highlight from the entire collection and shows it to me. Hit refresh and a new note is selected. It's a great way to be reminded of what I've read over time—and with habitual use it might just help me internalize some of the knowledge I've captured. Or how about some random wisdom to start a new terminal session? curl and bash to the rescue:

randomBookNote() {  
    curl -s https://app.amosti.net/reading/api/notes/random \
        | jq -r '.note + " - " + .authors[0] + ", " + .title'
}

The system and content are open source and available on GitHub.

The example notes from this article are taken from the following books:

• Beyond the Mountain — Steve House
• Training for the Uphill Athlete — Steve House, Scott Johnston, and Kilian Jornet
• Everybody Loves Our Town - Mark Yarm
• The Psychology of Money — Morgan Housel

The awesome_bot name comes from the "awesome pages" that are rather popular on GitHub. If you don't know about Awesome, it's usually collections of links with "awesome" tools, resources, libraries etc. for a specific topic or ecosystem. Examples are awesome-dotnet, awesome-react, awesome-ai-awesomeness or awesome-ci - the list is endless. Needless to say, these pages contain lots and lots of links, hence the need for validating the aliveness of these links.

If you are into Ruby and gems, awesome_bot can be installed with gem:

gem install awesome_bot  

I prefer the container approach, and dkhamsing/awesome_bot image can be used.

An example execution of awesome_bot might look like this:

$ docker run --rm -v $(pwd):/mnt -t andmos/awesome-bot -f **/*.csv --allow-redirect --allow 429
> Checking links in misc/Roasteries.csv
> Will allow errors: 429
> Will allow redirects
Links to check: 14  
  01. https://www.kaffebrenneriet.no/
  02. https://www.timwendelboe.no/
  03. https://sh.no/
  04. https://www.kaffa.no/
  05. https://www.srw.no/
  06. https://www.fjellbrent.no/
  07. https://jacobsensvart.no/
  08. https://www.facebook.com/stormkaffe
  09. https://www.pala.no/
  10. https://www.langorakaffe.no/
  11. https://inderoy.coffee/
  12. https://bonneribyen.no/
  13. https://www.facebook.com/brentkaffe/
  14. https://senjaroasters.com/
Checking URLs: ✓✓✓✓✓✓✓→✓✓✓✓✓✓  
No issues :-)  

In this example we check links from CSV files and use the flags --allow-redirect to, well, allow redirects (which throws errors if not given) and --allow 429 to whitelist the "Too many requests" status code.

If something is off with a link, like a 404, awesome_bot will throw an exit-code and show issues in the report:

$ docker run --rm -v $(pwd):/mnt andmos/awesome-bot -f *.md
> Checking links in README.md
Links to check: 1  
  1. https://www.an.no/some/dead/link
Checking URLs: x

Issues :-(  
> Links
  1. [L1] 404 https://www.an.no/some/dead/link
> Dupes
  None ✓

Wrote results to ab-results-README.md.json  
Wrote filtered results to ab-results-README.md-filtered.json  
Wrote markdown table results to ab-results-README.md-markdown-table.json  

awesome_bot can be automated to run scheduled with you favorite CI system - here is a GitHub Actions example:

name: Verify Links  
on:  
  pull_request:
  workflow_dispatch:
  schedule:
    - cron:  '0 13 * * 1'
jobs:  
  Awesome-bot:
    name: Run Awesome-bot
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Verify Links
        run: |
          docker run --rm -v $(pwd):/mnt andmos/awesome-bot -f *.md --allow-redirect --allow 429 --allow-ssl --white-list "nasdaq.com,researchgate.net"

The setup is simple, we have some Azure resources we want to create, so there is no way around Infrastructure as Code and, by our choice, the battle-proven Terraform from Hashicorp.

Since the code lives up on Github, we want to automate the steps involved with the Terraform code and work with a standard pull request workflow.
This includes:

• Lint and format the code.
• Run validation.
• Create the plan to be executed.
• Post the changes as a pull request comment and review the changes.
• If all is good and approved, apply the changes on merge.

or visualized:

Thankfully this is not a new subject to explore. There are tons of examples on how to work with Terraform and Github Actions, including an excellent post from Hashicorp on how to write this workflow.

Upon reading this post and writing out the code, we nearly got what we wanted.

The generated pull request post with the plan itself looks like this with the standard example:

A couple of things we didn't fancy here. First off, the plan itself is hidden away behind the drop-down menu, making it easy to miss if you're not careful - and you should be - Terraform is unforgiving if some resources are deleted by an error.

Second, the plan has no color highlighting, making it a bit hard to read. It appears just as a wall of text where details might be missed.

And third, the post itself should contain the brief summary of what is actually going to happen without reading the actual plan. I'm talking about this part:

Plan: 0 to add, 1 to change, 1 to destroy.  

After some more searching we found another excelent post by Andrew Walker who introduces enhanced formatting on the terraform plan output with the use of diff.
diff is a nice syntax to color highlight changes in files, just as Github's pull request view has. In a nutshell, diff has the following coding:

Great to highlight what will be created, deleted or changed when a terraform plan is executed.

After some inspiration from our friend Andrew and some more tinkering, we came out with an output we were quite happy with:

The overview itself is much cleaner with less stuff. The checks are still there, but with emojis instead of the text. The summary is also on the top of the comment.

The plan itself shows like this:

The observant Terraform author will notice something here. The symbol for "update in place" should be ~, not !. This is a little trick we did to get the orange color for in-place changes, not just additions and destroyed resources.

So far we are quite happy with this layout.

The following gist contains the workflow. Hopefully it will be of inspiration to others down the road.

As last year, this is my contribution to the advent calendar we do over at Bekk. Hope you like it!

Testing, testing

"Testing shows the presence, not the absence of bugs." - Edsger W. Dijkstra

As professional software developers, writing automated tests has become second nature to what we do. The exact amount of tests, amount of code-coverage, unit vs. integration vs. integrated test etc. may still be up for debate, but the industry as a whole seems to have settled on the practice of automated tests as a way to ensure the viability of a codebase over time. The Extreme Programming methodology of the late 1990's even went as far as citing "Code without tests may not be released".
Even with the general consensus among developers that automated testing is something we should do, it's still an open choice: one can actively choose to not to write tests as well.

Dave Farley wrote a blog post some years ago about how we should use techniques from classical science and engineering and apply them to software development to make the field "a real engineering field, not just a pretend-to-be", and to archive this, testing is essential. To be frank, in how many other engineering fields is testing of the things created optional?

Used correctly, automated testing is a great way to implement the essence of science, to falsify the hypothesis about the code.

Every programming language or ecosystem that's worth taking seriously has a testing library, or sometimes whole frameworks created for them. For C# and dotnet xunit has become somewhat of a standard, in Java and JVM land JUnit has been around for a long time, and for JavaScript, both frontend and backend, testing with Jest has seen a lot of traction.

Writing our unit, integration or integrated tests in the same language as the production code and keeping the tests close is the de facto standard.

But aren't we forgetting something? Our systems do not stop at the application code level. To be able to build and deploy our code, chances are we have some build scripts and deployment pipelines, or some good old "glue scripts" keeping it all together. To do most of this heavy lifting most of us still depend on the good old shell scripts, most notably written in the old work-horse Bourne Again Shell, or Bash.

If anything, chances are slim that Bash is going away anytime soon, and scripts written for the shell deserves tests of it's own.
The shell is also often forgotten as an environment to test systems from in of itself. There are lots of CLI's that can be used to test different aspect of our systems, and there is no rule proclaiming that integration or load tests need to be written or hosted by the same codebase as our application.

It's time to introduce shell testing with bats.

Introducing shell testing with Bats

bats is a TAP, or "Test Anything Protocol" compliant testing framework for Bash. It provides a simple way to verify that the *NIX programs you write behave as expected. The initial public release of bats was done back in 2011 by Sam Stephenson, but the project was archived and put in a read-only state in 2016. As of 2017, the current actively maintained fork, know as bats-core has been looked after by the bats-core organization, and the project is still under active development.

To show how writing tests with bats work, let's write some black-box test verifying a REST-API with curl.
Our "system under test", or "SUT", is the The Star Wars API. This will show how bats work, and show one of it's use cases.

We begin with a test to make sure Luke Skywalker is the first entity of the /people endpoint.
As we will see, tests are set up like most other testing frameworks, here following the "arrange act assert" pattern.

#!/usr/bin/env bats

@test "GET: /people first person entity is Luke Skywalker" { # The first line contains the test-annotation and a name / explanation of the function to be tested.
    #Arrange
    local EXPECTED_PERSON="Luke Skywalker"
    local ACTUAL_PERSON
    #Act
    ACTUAL_PERSON="$(curl -s https://swapi.dev/api/people/1/ |jq '.name' --raw-output)" # Here we do our call to the Star Wars API with curl and parse the JSON with jq
    # Assert
    [ "${ACTUAL_PERSON}" == "${EXPECTED_PERSON}" ] # The assert is a normal Bash test, where we check the actual person against what we expect.
}

To run the test, use the bats command:

$ bats tests/star-wars-api.bats 
star-wars-api.bats  
 ✓ GET: /people first person entity is Luke Skywalker

1 tests, 0 failures  

We can expand on this and check if the /planets endpoint contains Naboo:

@test "GET: /planets contains 'Naboo'" {
    local EXPECTED_PLANET="Naboo"
    local ACTUAL_PLANET 

    ACTUAL_PLANET="$(curl -s https://swapi.dev/api/planets/ | EXPECTED_PLANET="$EXPECTED_PLANET" jq '.results[] | select(.name == env.EXPECTED_PLANET).name' --raw-output)"

    [ "${ACTUAL_PLANET}" == "${EXPECTED_PLANET}" ]
}

The two tests are now run together:

$ bats tests/star-wars-api.bats 
star-wars-api.bats  
 ✓ GET: /people first person entity is Luke Skywalker
 ✓ GET: /planets contains 'Naboo'

2 tests, 0 failures  

Great. Those examples show the overview of bats. For more ideas on how to use bats for integration tests, Zach Holman has a great blog post with that topic in mind.

Next, let's spice it up with some Test Driver Development (TDD) on some actual shell scripts.

Using TDD in our shell scripts for fun and profit

Let's begin simple: We want a function to extract the author from a markdown file containing book notes, but want the job to exit if no argument (I.e. a file) is given. This being TDD, we want a failing test explaining the logic we want before we actually write som code.

In this example, we will see the keyword run, which is used to run a function, as well as the $status and $lines variables provided by bats. The overview of bats variables can be found here.

#!/usr/bin/env bats

function setup(){  
    source ./extract-booknotes.sh # The setup method sources in the script we want to test.
}

function teardown(){  
  echo $result # The teardown method returns the "$result" variable from bats itself. This helps with debugging failing tests.
}

@test "extract_author no argument" { # The first line contains the test-annotation and a name / explanation of the function to be tested.
    run get_author  # The `run` keyword comes from bats and is for triggering functions or script.

    [ "${status}" -eq 1 ] # The $status variable contains the return code from the functions or scripts being tested, 
    [ "${lines[0]}" == "Missing argument file" ] # While the $lines variable is an array of strings from the functions or script we want to test.
}

When run against an empty file, this test will (not surprisingly) fail:

#!/usr/bin/env bash

function get_author(){

}

$ bats tests/extract-booknotes.bats 
extract-booknotes.bats  
 ✗ extract_author no argument
   (from function `setup' in test file tests/extract-booknotes.bats, line 4)
     `source ./extract-booknotes.sh ' failed with status 2
   ./extract-booknotes.sh: line 9: syntax error near unexpected token `}'


1 test, 1 failure  

And if we fill in the code:

#!/usr/bin/env bash

function get_author(){  
    local FILE="$1"
    if [[ -z $FILE ]]; then 
        echo "Missing argument file"
        exit 1
    fi
}

And run the tests again:

$ bats tests/extract-booknotes.bats 
extract-booknotes.bats  
 ✓ extract_author no argument

1 test, 0 failures  

We get some green tests.

Cool. Now for the functionality. We want to extract the author from the markdown notes file:

### Metadata

- Author: Kilian Jornet
- Full Title: Above the Clouds: How I Carved My Own Path to the Top of the World
- Category: #books

Again, let's start with the test:

@test "extract_author with 'Above The Clouds' file as argument" {
    run get_author BookNotes/Above.The.Clouds.md

    [ "${status}" -eq 0 ]
    [ "${lines[0]}" == "Kilian Jornet" ]
}

And that test will fail since we don't have updated our code:

$ bats tests/extract-booknotes.bats 
extract-booknotes.bats  
 ✓ extract_author no argument
 ✗ extract_author with 'Above The Clouds' file as argument
   (in test file tests/extract-booknotes.bats, line 20)
     `[ "${lines[0]}" == "Kilian Jornet" ]' failed


2 tests, 1 failure  

Cool. Now let's do some regex-matching, an operation that's good to have tests for:

function get_author(){  
    local FILE="$1"
    if [[ -z $FILE ]]; then 
        echo "Missing argument file"
        exit 1
    fi
    local AUTHOR
    AUTHOR=$(grep -oP '(?<=Author:\s)(\w+).*' "$FILE") # <--- This one right here. I'm not comfortable with regex spread around, so a test for this is quite nice.
    echo "$AUTHOR"
}

Note: For this pice of code, the GNU version of grep is used. It might not work as expected on macOS with BSD grep.

With this pice of code in place, the test should be green:

$ bats tests/extract-booknotes.bats 
extract-booknotes.bats  
 ✓ extract_author no argument
 ✓ extract_author with 'Above The Clouds' file as argument

2 tests, 0 failures  

And indeed it is.

Don't believe the tests? Let' try the method ourself:

$ source extract-booknotes.sh
$ get_author BookNotes/BookNotes/Above.The.Clouds.md 
Kilian Jornet  

Don't you know it, it works! Tests don't lie.

How about the title? We have the author, but not the title? That's kind of backwards.
Let's begin by specifying how the function should look, again from our tests:

@test "extract_title no argument" {
    run get_title

    [ "${status}" -eq 1 ]
    [ "${lines[0]}" == "Missing argument file" ]
}

Same as before, no file should give output and exit code 1. No code written yet, no green test.

With that in place we can focus on extracting the title from the file. As always, the test first:

@test "extract_title with 'Above The Clouds' file as argument" {
    run get_title BookNotes/Above.The.Clouds.md

    [ "${status}" -eq 0 ]
    [ "${lines[0]}" == "Above the Clouds: How I Carved My Own Path to the Top of the World" ]
}

How do you think running this test will go? That's a no. We don't have any code yet.

Let's break out that regex to match the title from the markdown:

function get_title(){  
    local FILE="$1"
    if [[ -z $FILE ]]; then 
        echo "Missing argument file"
        exit 1
    fi
    local TITLE
    TITLE=$(grep -oP '(?<=Full Title:\s)(\w+).*' "$FILE")
    echo "$TITLE"
}

With this line in place, the tests go green:

$ bats tests/extract-booknotes.bats 
extract-booknotes.bats  
 ✓ extract_author no argument
 ✓ extract_author with 'Above The Clouds' file as argument
 ✓ extract_title no argument
 ✓ extract_title with 'Above The Clouds' file as argument

4 tests, 0 failures  

NICE. But wait. What about refactoring? Isn't that a part of TDD?

Yes indeed. The observant reader may have seen that the two functions have something in common: both take in an argument of a file name for parsing, and both do the parsing based on regex expressions. If no argument is given, return error exit code and a message saying "Missing Argument file".

Let's begin by extracting the input validation from the get_author and get_title functions and call it _file_exists. This function will be more generalized and standalone. As always, the functions behavior is first described with tests, which makes for great documentation of the function.

# The behavior should be the same for no arguments, exitcode 1 and 'Missing Argument file' as output:
@test "_file_exists with no argument" {
    run _file_exists

    [ "${status}" -eq 1 ]
    [ "${lines[0]}" == "Missing argument file" ]
}

# Since the function validating the input file now can be extracted from the book notes parser, it can check the script itself:
@test "_file_exists with 'extract-booknotes.sh' file as argument" {
    run _file_exists extract-booknotes.sh

    [ "${status}" -eq 0 ]
    [ "${lines[0]}" == "extract-booknotes.sh" ]
}

Then we can extract the input check directly from the functions:

function _file_exists(){  
    local FILE="$1"
    if [[ -z $FILE ]]; then 
        echo "Missing argument file"
        return 1
    fi
    echo "$FILE"
}

Now here we could also extend the _file_exists code with a branch handling an argument of the name of a non-existing file, but to stay strictly in line with TDD we should only add enough production code for the tests to to pass, which we have done with the extracted snippet.

The refactored get_author function now looks like this:

function get_author(){  
    FILE=$(_file_exists "$1") # <--- Here we run the input through the validation function
    if [ $? -eq 1 ]; then  # <--- And then check the return code from the function
        echo "$FILE" # <--- Before we return the output from the validation if it fails
        exit 1 # <--- Then, exit.
    fi
    local AUTHOR
    AUTHOR=$(grep -oP '(?<=Author:\s)(\w+).*' "$FILE")
    echo "$AUTHOR"
}

How about the tests?

$ bats tests/extract-booknotes.bats 
extract-booknotes.bats  
 ✓ extract_author no argument
 ✓ extract_author with 'Above The Clouds' file as argument
 ✓ extract_title no argument
 ✓ extract_title with 'Above The Clouds' file as argument
 ✓ _file_exists with no argument
 ✓ _file_exists with 'extract-booknotes.sh' file as argument

6 tests, 0 failures  

Did the code get any better or clearer? More dynamic and with a better abstraction. Thanks to the tests the refactoring could be made safer with guardrails.

Conclusion

In this post we have seen how our shell scripts also can have automated tests thanks to bats.
Hopefully this will motivate you to extend your thinking about tests to also include the pieces outside the application code.

As a colleague of mine said: "Every pice of code in the repository that is necessary to bring value to the customer is critical, and should thus also be tested. If we think we have a bug in the deployment pipeline, we don't guess. We test and prove.

All code examples from this post can be found in this Git repository.

I wrote a blog post about this setup and my technique with regards to reading, which, upon re-reading, I see that both my technique for reading and writing-skills has improve, so that's that.

In 2017 Atlassian acquired Trello, and safe to say, thing are starting to become more "enterprisey" over there.

I figured I won't be staying with Trello forever, and the amount of sunk-cost I have compounded in my simple reading list is astonishing. After some grooming, the backlog has currently 242 items and my done list has 450 entries.

What can I say, I like to read.

Some years ago I began my humble planning for moving away from Trello by writing a wrapper API service for the reading list,
using the Trello API itself as repository layer, so the switch to some other service could be easier. Maybe this API will act on top of something like SQLite or Firebase, who knows. To make sure I always had a copy of the data from Trello, I wrote a small bash-script with some curl calls and set up a cronjob. Now cronjobs are messy, I need to remember that I have it running, correct it if it runs into some error, and - after all - back up the data that comes from it.

Searching for a better solution than bash and cronjobs, the next step on this pet project of mine came February 2021, when GitHub releases a cool project called Flat-Data.

In the projects own words:

Flat Data is a GitHub action which makes it easy to fetch data and commit it to your repository as flatfiles. The action is intended to be run on a schedule, retrieving data from any supported target and creating a commit if there is any change to the fetched data.

So in a nutshell, Flat-Data allows us to set up a simple GitHub Action, point it at some data source (like an API or SQL database), query the data, run some processing on it, and have it checked in to Git. A great tool for the data scientists I would
imagine, or for a guy who just want to back up his reading list from an over-engineered API layer on top of Trello.

It's easy to get started. All we need is a repository and a GitHub Action.
My repo is ReadingList-Data and contains a few files: backlog.json, done.json, reading.json and postprocess.js.

The GitHub Action itself using Flat-Data looks like this:

Every Monday afternoon this action runs, fetches the current status from the reading list API, runs it through the post-processor
script (a simple Deno script that only formats the JSON) and creates commits with the changes. It could not be simpler.

As a bonus the commit history works as a great timeline to see when a book was added to the backlog or I was done reading it.

This is a quite simple and banal use case for Flat-Data, but hopefully it will inspire someone out there.

This is a cross-post of my contribution to this year's advent calendar we do over at Bekk. Hope you like it!

Introduction

Setting up reliable environments for our software is tricky.
The task has kept developers and sysadmins up at night for decades. Making environments and packages truly reproducible and reliable for more than a few weeks before regression sets in, is surely no easy task. In this post, we'll see how we can set up truly deterministic, reproducible and even ephemeral environments with the help of a clever set of tools called Nix, so we can sleep better, knowing our systems can be installed from literary scratch and be guaranteed the same binary packages down to the lowest dependencies.

What's in a name?

Let's face it, "Nix" has a quite ambiguous name that can reference a lot of things, so first, let's get the naming out of the way.

When people hear "Nix", they might think about "*nix", or the commonly spoken variant (without the asterix) "nix", the short name the industry has adopted for systems based on good old UNIX. Linux is "nix", macOS is "nix", BSD is "nix" - and in a way, "Nix" is also... well, "nix." Confused? Yeah.

Nix, in our context, refers to three things: the Nix Expression Language, a pure, lazy, functional language. This language makes up the foundational building blocks of the Nix package manager, which can be installed on any "*nix" system (like Linux or macOS) or as it's own unique Linux distro, NixOS. So a language, a package manager and even a distro. What's this all about?

What makes Nix so special?

With the naming out of the way, what makes Nix so special? What does it have to offer that apt, yum, or brew don't have?

First off, it's cross platform. The Nix Package Manager can run on the most common Linux systems, as well as macOS, but that is true for many package managers these days, and is not it's main advantage.

What makes Nix special is how it manages packages and dependencies. Nix guarantees reproducible packages, which means that all steps involved in building a package can be run again and again with the same outcome, and if any of the variables in the dependency chain change (all the way down to low-level packages like libc), it will result in a new version of this package, that can be installed side-by-side with the old version. This is possible thanks to the nature of the functional Nix language. From the docs:

Nix is a purely functional package manager. This means that it treats packages like values in purely functional programming languages such as Haskell — they are built by functions that don’t have side-effects, and they never change after they have been built.

Nix stores packages in the Nix store, usually the directory /nix/store, where each package has its own unique subdirectory such as

/nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1

where b6gvzjyb2pg0… is a unique identifier for the package that captures all its dependencies (it’s a cryptographic hash of the package’s build dependency graph). This enables many powerful features.

In more practical terms, this is accomplished by generating hash values of all dependencies going in to the package build, as well as the outcome of the build itself.

Kicking the tires

Let's look at an example package called hello.
The Nix-script responsible for building the package can be found in the nixpkgs-github repo
(all packages are essentially built and installed from these scripts) and it looks like this:

We begin by installing it to the user's environment:

As we can see, a lot of things was required for a simple program that prints out Hello, World!.

One might look at this list and think "Hey, i see curl on there - curl is already installed on my machine, why do I need it again, and won't multiple versions of the same package wreck-havoc on my machine?"

To address the first comment, this neat little trick is what makes Nix-packages self-contained and immune to what else might be installed on the system.
Other package managers, like apt or brew are often heavily dependent on there existing one version of a package or it's transitive dependency.
This is why installing packages on different systems can lead to quite different results, and why a package update can break a system.
With Nix, all package dependencies comes bundled and are stored in their own hashed directories.
The model Nix follows is that every transitive dependency must be defined in a Nix-expression that can be built itself, thus supplying a dependency chain of "build instructions" all the way to the lowest parts.
If one lower-level dependency change, the main package can not be seen as the same exact version as we had before, and will be installed side-by-side with the old version, completely isolated.
This nifty feature is why Nix and NixOS has become a favorite among developers and system administrators alike, it makes for highly robust and deterministic systems, easy to update or rollback.

To address the concern of multiple versions of curl, let's take a look at what we have on our PATH after the install of hello:

$ which curl
/usr/bin/curl

curl being a transitive dependency for hello does not place it on our PATH, the version of curl provided by macOS is still in place.

If we install curl as a top level package, the story would be different:

To keep score of what version of a Nix-package is currently being used, Nix takes leverage of symlinks:

If we regret installing curl via Nix or something broke, Nix keeps track of the users environment in
Generations, making it easy to rollback the system:

Creating reproducible development environments with nix-shell

Another powerful tool provided with Nix, is nix-shell. Software teams have always been struggling with the famous "works on my machine" syndrome, where a build or piece of code works as expected on one machine, but not on another.
Creating reproducible development environments has been the holy grail for many, and tools like Packer and Vagrant takes the virtual machine way to solve this, by building VM images that can have tool pre-installed or installed via provisioning systems like Ansible.

Another way to solve this is with containers, typically with Docker and Docker-Compose.
Both virtual machines and container technology has pros and cons, but the mayor drawback is that it is quite hard to make truly reproducible environments.
Both are great for freezing a setup in time (like a VM image or a container image), but are hardly deterministic.
A badly written Dockerfile can produce different results when built on two different systems.

As a side note, it is possible to build reproducible and small Docker images with Nix.

nix-shell on the other hand leverages the power of Nix to build local, reproducible, isolated and ephemeral shell-environments.

Let's say we want python3 but don't want to install it user/system-wide. It is possible to use nix-shell to provide an on-demand shell with just python3:

As we can see, no python3 package was installed on the system, but with nix-shell we are able to download the package with all dependencies and make it available in a local nix-shell.
When exiting the shell, no version of python3 is available on path.

With the Nix language, it is possible to write declarations for these shells that can be shared among the development team.
Let's say the team is maintaining a Java application, deployed on Kubernetes, and want a setup that just works™ on all systems:

This script can be stored in the root of the Java-project and added to version control. When a developer wants the environment, a simple command will provide it:

As we can se, the selected packages and dependencies are all installed.

To clean up old nix-shell sessions, we can simply run

$ nix-collect-garbage

Conclusion

This post has been a brief intro to Nix and what at can provide in terms of reproducible, isolated systems. It is possible to do so much more than just install pre-built packages. I would recommend How Shopify Uses Nix for further inspiration on how to build and deliver software using Nix, as well as checking out the home-manager project for managing user environments.

Interested in building your first Nix package? See the excellent nix-tutorials website and start hacking!

Last year I wrote about how to set up a local reverse proxy with nginx and mkcert via Docker-Compose.
Being able to spin up a local, production-like reverse proxy to use while developing is great, but why stop there?

Sooner or later the need for a database to store the applications data will emerge, and with any data structure, the need for change - adding, updating or deleting elements of the structure is needed. In other words, the need for migrations.

Back in the day, a usual practice for a team depending on a database (depending on the complexity of the application and maturity of the team), was to share a database instance for development. Setting up a local database can be tricky, and up until 2017 Microsoft's SQL Server was only available on the Windows platform, requiring a VM for local development for *nix users. The single, shared instance strategy is also quite limiting for teams working in parallel on tasks requiring database and / or application code changes. A developer testing a database change on a single branch can easily break the main branch when a single instance is used.

In 2017 Microsoft release SQL Server 2017 (and now 2019) with Linux support, and with it, thankfully, Docker support.

A clean instance of MS SQL 2019 can be added to a docker-compose setup as easily as this:

With docker-compose, every developer on a team can have their own version of the database.

Running migrations with FluentMigrator

The next step is bootstrapping the structure of the database. For .NET, Entity Framework or FluentMigrator are popular choices. Let's focus on FluentMigrator.

A common pattern for handling migrations is creating a dedicated .NET csproj file where the migrations live. Let's call it MyApp.Migrations.
After writing some migrations, the easiest way of running them is via the FluentMigrator dotnet tool dotnet-fm. With dotnet-fm, running migrations is as easy as

dotnet-fm migrate --processor SqlServer2016 --assembly MyApp.Migrations.dll --connection "Data Source=myConnectionString"`  

Bootstrapping the database with Docker-Compose

Now we have a docker-compose containing an MS SQL instance, and we have a csproj file containing some database migrations. To save us from having to run the migrations manually, the process of bootstrapping the development environment can be automated by containerizing the process running the migrations. For this, we create a Dockerfile that compiles the migration project, grabs the dotnet-fm tool for running FluentMigrator and wraps it up with an entrypoint for running.

The Dockerfile:

Some things to notice here.

The FluentMigrator library (installed with NuGet) and the dotnet-fm tool needs to be the same version, so the sed command on line 7 grabs the version-string from the csproj file and uses it to install the correct version of dotnet-fm tool on line 9.

On line 12 a little shell-script called wait-for is cloned. https://github.com/eficode/wait-for.git is used to wrap the execution of dotnet-fm and wait for the database the become available. This is a neat trick to handle the timing issues that can occur when running via docker-compose, where the migrations can be executed before the database is ready.

The Dockerfile is multi-stage, so the compiled library, dotnet-fm binary and wait-for script is copied to a dotnet runtime image. The netcat package installed on line 17 is a runtime dependency for wait-for.

With the Dockerfile in place, the final docker-compose.yaml file:

The whole thing spins up with docker-compose up. When db is ready, the migrations will be run and bootstraps the database.

Bekk Christmas, 264 tech articles in 24 days, each day of the advent calendar.

One of the categories was thecloud.christmas, so it felt natural to me to contribute here.

So here it it, from the 13th of December, my post about Kubernetes, ArgoCD, K3s and k3d. Enjoy Take Argo CD for a spin with K3s
and k3d!

When developing modern web application or services, the Twelve-factor app taught us that our services

is completely self-contained and does not rely on runtime injection of a webserver into the execution environment to create a web-facing service. The web app exports HTTP as a service by binding to a port, and listening to requests coming in on that port.

What this means is that our apps written with modern frameworks (like ASP.NET Core) should provide their own web-servers, exposing a HTTP port, and not require anything in front for hosting, like IIS or Apache HTTPD. For local development, you should be able to run the app without any third-party component requirements for hosting, and the app should be reachable on http://localhost:5000/ as an example.

Now hosting the app directly in this way in a production setting is something you don't want to do for obvious reasons, since the infrastructure-layer of the app would grow thick, and the developer must code in all sort of hardening, routing etc, not to mention the security concerns - that self-hosted HTTP server would be exposed all on it's own as an attack-vector. When running in production, a component suitable for the reverse-proxy role should be responsible for binding a public-facing hostname to the app(s), as well as do HTTPS termination - the app itself should focus on what it does best, the business logic (this is why it exists in the first place), while a component like nginx or HAProxy should handle hostname binding, HTTPS and load-balance incoming requests.

Modern platforms like Kubernetes or OpenShift offers routes that gives the app an external-reachable hostname, and load-balances the application when running on different nodes, as well as provide HTTPS termination up-front. For small solutions not needing a container orchestrator, plain old nginx in front works great.

All modern application should be hosted with SSL and HTTPS. Thanks to projects like Let's Encrypt, trusted SSL certificates can be obtained for free, and the world is now, slowly but surely, moving to HTTPS as default. This does not mean that our application's first meeting with HTTPS should be in a staging or production environment, it should also ble possible to develop and test locally with HTTPS as default. Thanks to modern tools, running a local reverse-proxy with a valid HTTPS certificate is quite straight forward.

Local reverse-proxy with SSL termination

Let's say we have a single application, MyService, that is written with ASP NET, running with Kestrel. The app has no code for HTTPS-redirects, and knows nothing about any SSL certificate or setup, it only talks HTTP on port 80. The application is destined for a life in a container orchestrator of some kind, so it has a Dockerfile. To be able to run the MyService application via HTTPS in an environment similar but not equal to, let's say Kubernets, we need to run it behind a reverse-proxy when testing locally. We also need some sort of SSL certificate. Earlier in the post I mentioned Let's Encrypt that offers free certificates, but to be able to leverage it, a public-facing hostname is needed. For local development, a self-signed certificate is plenty. Now the road down self-signed certificates can be quite dirty and lead to many half-working solutions and "not-trusted" warnings in the browser. One easy solution is using a great tool called mkcert. mkcert is a simple CLI that registers a trusted CA on your machine, both in the local certificate store and in all installed browsers, and can generate certificates from this CA.

To install mkcert with brew:

$ brew install mkcert

Before installing the mkcert CA and generating a certificate:

Please note, this CA and certificates generated from it is for local purposes only.

Next up, let's configure nginx to work as a reverse-proxy with SSL termination:

This configuration will tell nginx to listen on localhost, port 5000 with the generated certificate from mkcert. Requests to / is then forwarded to the app, listening on plain old HTTP on port 80.

The whole thing is then tied together with docker-compose:

Now run the whole thing with

$ docker-compose up

Navigating to https://localhost:5000/ reveals a nice HTTPS symbol:

Note

Unless nginx is used as reverse-proxy in the live environment, this solution will not be excactly on parity with staging or production, but the mechanisms and practices should be similar. As a rule of thumb, the Twelve-Factor app talks about the importance of dev/prod parity.

Why invest more time in setting up the complicated hosting and scheduling platform than it took to write that 500 lines single-container web service?

Don't fear, watchtower is here.

Watchtower is a single process container that runs on your system and polls a container registry (private or public, like Dockerhub) at given intervals to check for new versions of the base image on the running container(s) you want to update. If it detects a new image, Watchtower stores the parameters used to start the running container, like startup argument and environment variables, pulls down the new image, stops the running container, and starts it up again, with the same parameters, but with the new image. Easy as that. This simplifies the deployment process, and the only automation needed is a CI pipeline that builds the service's container image and pushes it to the registry when code is committed. Here is an example from my simple ReadingList API:

In .travis.yml:

On push to master, if the build and test steps are successful, the image is tagged as latest and pushed to DockerHub. Nothing more to it.

Now on my private Linode server the ReadingList API has been started once with the correct env-variables, so it's running as intended. Then Watchtower comes in:

docker run -d --name watchtower  -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower readinglist  

Watchtower is now running and has access to docker.sock to be able to start and stop container.

When a change to ReadingList is merged and new image pushed, watchtower kicks in and replaces the running container with a new, updated version:

docker logs watchtower  
time="2019-10-30T13:06:39Z" level=info msg="Found new andmos/readinglist:latest image (sha256:803aa566d2dd53f3ec774406f6bd8e20cb4e926006cdc1012dc663e206fbc9dc)"  
time="2019-10-30T13:06:40Z" level=info msg="Stopping /readinglist (45ceaaa2de930b22424438d1f2d078796feead127b0ab578c0ff8ac14dc8630e) with SIGTERM"  
time="2019-10-30T13:06:41Z" level=info msg="Creating /readinglist"  
time="2019-10-30T13:13:38Z" level=info msg="Waiting for running update to be finished..."  

And thats it. Be mindful, this approach has limitations. When managing larger multi-container systems in production something like Kubernetes and a more thorough setup is recommended, but for the casual, single container hobby project Watchtower works just fine.

Github Actions is a welcomed edition to the (still) growing world of CI/CD tools. Since Actions is Github's own tool, it integrates more closely to your repo and the Github Workflow, with actions to automate tasks around issues, pull-requests, releases etc. Writing a task that regularly, say, check issues and mark them as stalled if it hasn't been any activity for some time has, would mean leveraging the Github API when running in other tools, while abstractions for these kinds of integrations are present directly in Github Actions. That makes their "workflow" semantics more comprehensive than just plain CI/CD capabilities.

Extendability is at the core of Github Actions. All workflows consists of one to many actions, and these actions can be run natively or via containers. Referencing a third party actions is as easy as knowing the action's github namespace.

In this example the workflow Tests will trigger on git push, run on macOS, Ubuntu and Windows, checkout code with the action actions/checkout, and install Python via actions/setup-python and is a third party action: dschep/install-poetry-action. Since these actions directly reference living repositories, specifing a release or branch (dschep/install-poetry-action@v1.2) will save you from some unpleasant discoveries.

To speed up the build, these actions can be run directly from DockerHub:

Uscase: Upload artifacts to Azure Blob Storage

Github Actions is still in it's early days, so there are not actions for everything just yet. The other day I needed a workflow to build and publish an Electron App to MacOS and Linux, with the artifacts stored in Azure Blob Storage. In Azure Blob Storage we have two containers, one for dev and one for release, so the app can be tested before released out to the world. Here is the workflow:

So this workflow will only trigger on push to the dev branch.
actions/setup-node@master installs node on version 12.10, and electron-builder is used to package and sign (the macOS) app. Here we also see secrets in play, ${{ secrets.BASE_64_CERT }} holds an encryptet signing certificate.

Finally, I could not find a suitable action for uploading to Azure Blob Storage directly, but going via azure/actions/login worked great to auth against Azure and give access to the az CLI. All that is needed is generating Azure Service Principal to give the workflow access to just the Blob Storage Containers, store them as a secret and we are good to go. For a great intro to using dotnet core with Github Actions, check out Runar's post.

Micro-mobility has gotten a lot of hype over the last couple of years. In many cities all over the world rentable city bikes, cargo bikes and electrical scooters has popped out and seriously changed the way people move, and it doesn't look like you can spell "smart city" without micro-mobility. The consulting company McKinsey is estimating that the value of the micro-mobility market will reach a value of $200 billion to $300 billion in the United States in 2030. What gives micro-mobility systems advantage is the accessability and digital-first approach providers have taken. Most bikeshare systems are activated via smartphones, and the bikes themselves are IoT devices producing data for the providers or the public to explore. To make micro-mobility more useful interoperability is important, and many standards have surfaced. One of these is the General Bikeshare Feed Specification (GBFS).

General Bikeshare Feed Specification (GBFS) and use cases

GBFS is an open data standard for bikeshare systems developed by North American Bikeshare Association. GBFS provides info about the system itself, including real-time data like available stations, capacity, available bikes and locks etc. This API can be freely used to build 3rd party systems or apps. How about a dashboard that shows your closest station and local weather forecast, or Amazon Echo skill to check for available bikes?
The GBFS systems overiew currently contains 228 providers using GBFS.

A search for GBFS on github topics shows a lot of project integrating with the standard, including my GBFS Bikeshare client for dotnet. This client is a great starting point for exploring several exiting concepts: serverless and function as a service.

Serverless, function as a service and OpenFaaS

Serverless architecture comes as a result of the rising popularity of cloud computing, where providers like Google, Microsoft and Amazon have raised the abstraction level when deploying software. At the infrastructure as a service (IaaS) level you have to mange VMs, the platform as a service (PaaS) level want your binaries or containers, while the function as a service (FaaS) provider needs one thing: your code. The runtime, scalability etc. Is taken care of by the cloud vendor.

FaaS can be looked at as breaking up the microservice pattern into smaller pieces. Examples of functions can be transforming input data and store it in a database, resize images, handle messages on a queue or, to stay in the micro-mobility domain, check the availability status on a bikeshare station.

The biggest criticism directed at serverless and FaaS is vendor lock-in. Amazon has Lambda, Microsoft has Azure Functions, and Google has Cloud Functions. Since these platforms require plain code to run, some platform specific boilerplate or project types are needed for each platform, thus not contributing to portability between vendors.

So vendor lock-in is one thing, but I would also like the possibility to run a serverless FaaS solution on that old VMWare cluster in the basement, the Mac mini rack or on the Raspberry Pi spotted in the wild. Luckily, OpenFaaS is here to help. OpenFaaS is a framework that leverages container technology to run functions in containers on top of orchestrators like Docker Swarm and Kubernetes. This breaks the FaaS architecture free from the cloud vendors, providing the freedom to deploy serverless application in any environment offering a container orchestrator.

The OpenFaaS architecture.

Baby's first GBFS bikeshare functions

So let's put OpenFaaS to work and build some GBFS powered bikeshare functions.

For development purposes, running OpenFaaS via Docker Swarm is a good approach.
The installation of OpenFaaS and initialization of a Swarm cluster is straight forward.

My preferred language is C# and dotnet core, so to write the dotnet function a template is needed.
Github user burtonr has written a nice dotnet template with Kestrel and async support, perfect for high performance HTTP functions. To fetch the template:

$ faas-cli template pull https://github.com/burtonr/csharp-kestrel-template

Next, let's have a look at what a typical function might look like. The GBFS systems list is currently in CSV format, but I prefer to abstract it away and offer it as JSON via HTTP endpoint.

To create a new OpenFaaS function:

$ faas-cli new --lang csharp-kestrel gbfs-systems-function
Function created in folder: gbfs-systems-function  
Stack file written: gbfs-systems-function.yml  

As the output shows, a folder for the function and stack file are now created, next to the template.

$ tree
.
├── gbfs-systems-function
│   ├── FunctionHandler.cs
│   └── FunctionHandler.csproj
├── gbfs-systems-function.yml
└── template
    └── csharp-kestrel
        ├── Dockerfile
        ├── Program.cs
        ├── Startup.cs
        ├── function
        │   ├── FunctionHandler.cs
        │   └── FunctionHandler.csproj
        ├── root.csproj
        └── template.yml

To write the function, gbfs-systems-function/FunctionHandler.cs is edited. Here is the full function:

The Handle method is entrypoint for the function. In this case the input is not validated, but upon triggering the function parses the systems.csv file and serializes it as JSON.

To build and deploy the function, take a look at the stack file:

Notice the image: tag. Since OpenFaaS runs functions in Docker containers, this is the name of the container image that is created, and is the artifact of the build.

To build, deploy and trigger the function:

$ faas-cli build -f gbfs-systems-function.yml
$ faas-cli deploy -f gbfs-systems-function.yml

$ echo "" |faas-cli invoke gbfs-systems-function # or via Curl
$ curl -d "" localhost:8080/function/gbfs-systems-function

The two last commands will return JSON straight from the new function.

To push the image to Docker hub:

$ faas-cli push -f gbfs-systems-function.yml

Building a GBFS powered Slack bot

So that example function was rather simple. Let's make something more useful: A Slack bot for showing available bikes and locks at bikeshare stations. Right off the bat this seems like a nice use case for multiple functions, since a function should optimally do only one thing. So for the bot we need a bikeshare-function that takes the name of a bikeshare systems station as input, and return the number of available bikes and locks for this station as output.

Not much code needed here neither:

To link the function ta a GBFS system, the GBFS discovery URL must be exposed to the function via environment variable in the stack file.

When deployed, the bikeshare-function can be invoked:

$ curl -d "skansen" localhost:8080/function/bikeshare-function
{"Name":"Skansen","BikesAvailable":19,"LocksAvailable":2}

The next function is the Slack bot itself. The bot will trigger on mentions and call the bikeshare-function with a bikeshare station name. For creating Slack apps, see the documentation.

As expected, under 100 lines of code here too:

Now there are a couple of things to notice here.
For the bot to be able to call the bikeshare-function, it needs to know where the OpenFaaS API gateway is. When running via Docker Swarm this address defaults to http://gateway:8080/, but it is recommended to make this address customizable, as it may vary from environment to environment and other orchestrators.

The next thing to notice is secrets. The bot needs a OAUTH token when connecting to Slack, and this token should be kept secret. OpenFaaS integrates with Swarm and Kubernetes secrets, both reachable from openfaas-cli:

$ faas-cli secret create secret-api-key \
  --from-file=slackToken.txt

The token is then written to a file inside the container that must be read up:

var botToken = File.ReadAllText(@"/var/openfaas/secrets/bikeBotSlackToken");  

The final stack file:

To initialize the Slack bot:

$ curl -d "" localhost:8080/function/bikeshare-slack-function
Bot initializing  

The bot is now online and can be asked for station status:

Conclusion

It is exiting times for micro-mobility and the city of the future. For solutions like bikeshare systems to reach it's potential and help cities become more accessible, integration with other smart city systems is almost a requirement. Thanks to open standards like GBFS and the serverless paradigm, creating new application leveraging and combining data is only a couple of code lines away. Frameworks like OpenFaaS helps democratize serverless and FaaS, giving developers tools to run functions where and how they want.

Finally, all code for this post can be found on Github..

The one thing I missed when moving away from full-framework and Visual Studio to VSCode and dotnet core, was simple code coverage.

Given the easy tooling dotnet provides, with dotnet build, dotnet test and dotnet publish, I looked for something that integrated nicely with these commands without adding to much complexity to the code project itself. After som googling, I stumbled over Scott Hanselman's blogpost about a cool little project called Coverlet. Coverlet was just what I was looking for:

Coverlet is a cross platform code coverage library for .NET Core, with support for line, branch and method coverage.

coverlet can be installed as a dotnet tool with

dotnet tool install --global coverlet.console  

to make it globally available, providing it's own CLI tool running directly at the test assemblies.

The strategy I have settled on is using the coverlet.msbuild package that can be added to your test projects with

dotnet add package coverlet.msbuild  

When using the coverlet.msbuild package, no extra setup is needed, and coverlet integrates directly with dotnet test with some extra parameters,

dotnet test /p:CollectCoverage=true /p:Threshold=80 /p:ThresholdType=line /p:CoverletOutputFormat=opencover  

The clue here is /p:CollectCoverage=true, the parameter that enables collection of code coverage. if no other option is specified, the coverage will be reported to the console when the tests are finished running:

+-----------------+--------+--------+--------+
| Module          | Line   | Branch | Method |
+-----------------+--------+--------+--------+
| BikeshareClient | 93.2%  | 94.6%  | 85.7%  |
+-----------------+--------+--------+--------+

Now the other parameters specified in the example is /p:Threshold=80 and /p:ThresholdType=line. So if the code coverage drops below 80%, the build breaks here, while /p:CoverletOutputFormat=opencover writes a report in the opencover format.

Multi-stage Dockerfile

For most new projects, I have found myself using a simple Dockerfile along with some CI/CD tool like Travis, AppVeyor or Azure Pipelines. This approach helps keeping the builds simple, as large Dockerfiles are harder to work with. The sole purpose of Docker is to keep things reproducible no mather the environment it builds and runs images in, so migrating from one CI provider to another is hardly any work. Building locally will always match the result on the CI system.

But, let's say build using multi-stage Dockerfiles. In a multi-stage build, we separate the SDK, build and test tools in one image, while copying the resulting artifacts to another image, more suitable for production runtimes. The rule is, have a small production image containing just what is needed for running your artifacts. Just one problem: How do we take care of that coverage.opencover.xml file? We don't what to transfer that file to the production image to grab hold of it, code coverage results don't belong in a production image.

Thankfully, Docker stores layers that can be brought up after building the image.
Here is our example multi-stage Dockerfile:

In short, we build, test and publish the app with the microsoft/dotnet:2.2-sdk base image, before copying over the binaries to the microsoft/dotnet:2.2-aspnetcore-runtime image.

To use coverlet and extract code coverage, this line does the trick:

RUN dotnet test /p:CollectCoverage=true /p:Include="[BikeDashboard*]*" /p:CoverletOutputFormat=opencover  

Notice the label on line 3:

LABEL test=true  

With the label, it is possible to look up the id of the docker build layer containing the code coverage file, create a container from that image layer and use docker copy to grab hold of the coverage XML. Take a look:

export id=$(docker images --filter "label=test=true" -q | head -1)  
docker create --name testcontainer $id  
docker cp testcontainer:/app/TestBikedashboard/coverage.opencover.xml .  

Wrapping it up with Travis and codecov.io

So now we have a simple build chain with a multi-stage Dockerfile and code coverage generation. As a last feature, the coverage report can be used by code coverage analyzers like codecov.io. codecov.io integrates with Github, and can automatically analyze incoming pull-request and break a build if coverage drops by merging the PR. Quite nifty.

Integrating codecov.io with CI systems like Travis is done with a one-liner, thanks to the provided upload-script. When using Travis, not even a token is required.

.travis example file:

I like to think of markup languages as code, and most code deserves a good style guide. Markdownlint is a good alternative.

markdownlint provides a nice set of standard rules when writing markdown, like:

• Heading levels should only increment by one level at a time
• Lists should be surrounded by blank lines
• First line in file should be a top level heading
• No empty links
• No trailing spaces
• No multiple consecutive blank lines

just to name a few. It also ensures consistency in headers, like

My Heading  
===

vs.

# My Heading

Another smart rule is ensuring language description when writing code blocks.
The VSCode extension shows a squiggle when a code block is missing a language description:

If some rules don't fit your style or project, they can be override with a .markdownlint.json file:

{
    "MD013": false, // Disable line length rule.  
    "MD024": false // Allow Multiple headings with the same content.
}

The easiest way to start using markdownlint is to install the extension for VSCode or Atom (RIP Atom), or integrated with builds using Grunt, Github Actions etc. My preferred way is directly with the markdownlint-cli.

For my Coffee recipes I use a simple container with Github Actions:

If any rules are broken, it breaks the build.