The Start of a Blog

APFS is case-insensitive by default 😉

2023-12-17T00:00:00+00:00

The Symptom

Recently I encountered an issue when building an Android project on our Jenkins CI server. The Gradle build would error out because of many duplicate symbols - but when checking the actual project structure and files those duplicate symbols were nowhere to be found. I spend countless hours on this issue and pulled in several colleagues, but to no avail. Eventually after several days of off and on debugging and countless Google queries, I noticed that the capitalization of the package path for the files that were erroring out differed from what I could see locally, but I was perplexed - how could this be?

Though I had been a macOS user and Apple platforms developer for quite some years at that point, whether APFS was case sensitive or insensitive had never occurred to me. I knew that this was a characteristic filesystems had but I never had a reason to think about it until now.

The Problem

Turns out APFS is case-insensitive by default! For example, this means that the following two paths appear identical to macOS and the OS (and apps/programs) cannot differentiate between them:

/path/To/Some/Dir
/path/to/some/dir

The customary development machine on my team are Macs, which of course all ship with APFS. However Jenkins was running on a OS running on ext4, which is a case-sensitive filesystem by default. At some point someone had moved some packages around, in the process renaming some directories and introducing the issue.

The Fix

There’s two things one can do in this case. The first is to take an approach like suggested in this StackOverflow answer and configure git as follows: git config core.ignorecase false

The alternative is to make a new case-sensitive APFS volume, clone your repo there, and resolve the issue.

Tips

To prevent issues like this in the future, projects should have clear and adhered to naming guidelines. In our project, we had some packages that varied in capitalization, for example com.mycompany.myapp.main.Common.models. For Java and/or Kotlin projects, I’d recommend to not have any capitalization in packages names at all.

Conclusion

I spent way too much time on this bug. In the end however, I learned a bit more about filesystems and that naming conventions are more than just for readability & maintainability (amongst others) - but could also break your project 😉

390 Duke Chain and Sprocket Swap

2022-04-14T00:00:00+00:00

Chain maintenance is one of the key regular maintenance items for every rider out there (well those of us with a chain-driven bike 😀). A complete chain swap however is done more infrequently, and some riders leave that to their professional mechanic. That’s fine and good, but once you understand the procedure and have some tools even people with two left hands like me can do it!

General procedure

Here’s the main steps:

Loosen front sprocket nut
Break the original chain
Remove the original chain
Replace the front sprocket
Remove the rear wheel
Replace the rear sprocket
Mount rear wheel
Cut new chain to length
Attach new chain
Attach master link
Adjust chain to spec

So quite a few steps to be sure!

Pre-requisites & tools

You’ll definitively need some tools for this job - a Dremel and chain tool are highly recommended. Here’s a list of stuff that I used:

Rear stand
Socket wrench (+ appropriate sockets - check your manual/repair guide or eyeball what you need)
Torque wrench
Medium strength thread locker
New chain
New front and rear sprocket (optional but highly recommended!)
Long-life grease
Dremel with metal cutting attachment
Chain Break/Press/Rivet tool (mine is from Motion Pro)

Understanding modern sealed chains

You’ve most likely heard of O-ring, X-ring, and various other *-ring type chains - odds are your bike has one of these modern kinds of chains. The great benefit of these “sealed” type chains is that the factory-installed lubricant is sealed in by the o/x/z rings, meaning that they take less maintenance than unsealed type chains. The drawback is that sealed chains are more expensive.

In the above figure of a master link, observe that lubricant has been applied to the x-rings as well as the pins. On standard factory links this is the same, but you won’t see the body of the pins since there is a roller above them. The same will be true for the master link as soon as we’ve inserted it into place.

1) Loosen front sprocket nut

This step will differ from bike to bike. Some have a gigantic nut that will need to be loosened with a large breaker bar (if you’re unlucky). It’s important to loosen the front sprocket nut before removing the chain as we will use the chain to prevent the sprocket from turning. On the 390 Duke I got a little lucky though and the front sprocket is fastened by a clip held in place to the sprocket by two bolts which are not torqued down a lot. Regardless if your bike has a large front nut or a clip like mine does, a trick to prevent the front sprocket from rotating is to hold down the rear brake with some force - which prevents the rear wheel from turning an in turn also prevents the front sprocket from turning. It should be possible to do this by reaching around the bike with one hand, but if you need to use a breaker bar or impact wrench then having a buddy for this step is good.

On the Duke one simply has to remove the two bolts on either side of the shaft as shown above, slightly rotate the retaining bracket and it out.

2) Breaking the original chain

It’s very helpful to have a chain tool and a Dremel. To help the chain breaker do its work you can use a Dremel with a metal cutting attachment in order to grind down the head of the pin to press.

Note that in most cases the chain breaking tool also needs to be assembled depending on the desired function (check the instructions for your tool). The Motion Pro tool I used comes pre-assembled in the “Break” configuration as seen in the gallery above. The core idea is that, using sheer force, we will push a pin out and through the chain allowing it to be separated. The grinding down from the previous step will help the chain breaking tool do its work.

Various chain tools will have different components, but the principle is the same - the user will use a wrench to slowly turn an extractor bolt which will then force an extractor pin to push with a lot of force on a single pin on the chain, slowly forcing it out.

⚠️Before using the chain tool, read the manufacturer’s instructions⚠️

Using the chain tool requires patience and a lot of alignment double checking. Generally if you have to use an excessive amount of force check if you’ve aligned everything correctly. When breaking the chain you will feel a large initial resistance which will then spontaneously get significantly easier - this is a sign that the head of the pin has been broken and that the pin is in the process of being pushed through. This will still take some effort, but it will be a consistent effort. However there are a few things to pay attention to as you mount the tool on the chain:

ensure that the extractor pin is recessed a few millimeters into the body bolt before tightening onto chain
the anvil block has a little cutout where the other side of the pin fits into
the body bolt should clamp hand tight onto the chain
double check that the anvil block and body bolt align correctly with the chain pin

Once you’ve checked that, start rotating the extractor bolt and slowly push the pin out!

It’s helpful to remove the tool once in the beginning just to check if the extraction is progressing smoothly.

3) Removing the original chain

Once the pin is extracted completely, you can simply remove the chain by pulling slowly on one end. It’ll look something like the below, note the extracted pin and o-rings.

4) Replacing the front sprocket

Now that the chain is off, we can replace the front sprocket. As mentioned previously, the steps here will vary from bike to bike. On the 390 Duke, there are two small bolts that hold a retaining clip in place which needs to be rotated slightly. Only after being rotated will the “teeth” on the retaining clip align in a way that the clip can be pulled out. Once that’s done the front sprocket can simply be pulled off.

This is also a great opportunity to compare the old and worn front sprocket with your brand new one. Wear will be more easily seen on front sprockets as there are fewer teeth than the rear sprocket - where the wear and tear is more spread out. It should make sense now why the general recommendation is to replace chain and sprockets as a set - using a new chain on a worn sprocket will stress the chain more as it is forced into an existing wear pattern.

Replace sprockets and chains as a set!

It is also an excellent opportunity to clean around the chain guard and front sprocket!

5) Removing the rear wheel

The exact steps for this vary from bike to bike, but in general it involves the following:

Raising the bike with a rear stand
(Possibly) removing the rear wheel speed sensor
Removing the chain adjusters
Pushing the wheel forward and removing the chain (if not already removed)
While holding the wheel, removing the spindle/axle
Pulling out the rear wheel

Once the wheel is removed you’ll have a bunch of bolts and other things lying around. A good trick to keep everything organized the way it was is to re-attach the spindle, adjusters, and nuts without the rear wheel.

6) Replacing the rear sprocket

Replacing the rear sprocket is a relatively straightforward affair. It’s a matter of removing the existing bolts holding the old sprocket in place, swapping out the sprocket, and tightening the bolts down to the proper torque.

Tighten the sprocket bolts in a star pattern

Check your owner’s or service manual if the sprocket bolts require threadlocker

Quick Note on the star pattern

The “star pattern” is a way to tighten down sets of fasteners to ensure even torque and flatness of the item that’s being tightened against the surface it’s being tightened on. The process varies depending on how many fasteners are arranged on the item to be torqued down, but the general idea is to always go “across” when moving to the next fastener to tighten. Another core idea is to not immediately torque a fastener down to spec before moving on to the next, but to tighten gradually making multiple passes over each fastener in turn.

7) Mount the rear wheel

Re-mounting the rear wheel can be a bit tricky. It’s heavy and special attention needs to be paid so that the rear brake disk smoothly fits between the brake pads again. Again, read up on the instructions for your specific motorcycle. Generally there might be some spacers that need greasing, and the spindle/axle itself should be greased throughout (just making sure to avoid the threading on one end of the spindle). I use generic long-life waterproof grease. It’s also advisable to remove any grime you see.

The rough steps are as follows:

Grease any and all parts that need greasing (spindle, spacers, etc.)
Attach any spacers to the wheel
Lift the wheel, making sure that the brake disk smoothly slides between the brake pads. This will take some effort - the wheel is heavy!
Mount the chain adjustment/alignment mechanism (along with any washers) on one end of the spindle
Push the spindle through the swing arm and wheel, until it pokes through the other side of the swing arm
Attach the other side’s chain adjustment/alignment mechanism
Hand tighten the spindle with its nut - the chain still needs to be mounted and adjusted!
Mount the rear wheel speed sensor

If you have trouble lifting the wheel - get a buddy or slide some planks of wood underneath for support

8) Trimming the new chain to length

Chains come in standard lengths, like 112 links, 118, etc. Depending on your sprocket setup and motorcycle you might require a chain that’s different than the usual link counts. This naturally necessitates that the new chain be cut to length - a procedure identical to breaking the old chain.

However this is truly a “measure twice, cut once” situation as there isn’t a way to undo trimming the chain - I’ve never heard of someone lengthening chain by trying to use multiple master links 😂. To count the length of the chain, count each link individually. Unless you are also changing the sprocket tooth count the link count will be the same. You also might find it helpful to lay the old and new chain out next to each other so you can see exactly how many links to remove. Note however that the old chain, even with the same link count, will be slightly longer due to having stretched over its lifetime.

It’s helpful to have a stable platform when trimming the new chain. It is possible to do it off the bike of course, but I chose to mount the new chain and then trim it to the correct length.

9) Mount new chain

If you haven’t done so in the previous step - now is the time to do it. It’s as simple as feeding the chain through the front sprocket and laying it out on the rear sprocket like so:

10) Attach master link

This is where the process gets more interesting and a little more difficult. But before that, let’s go on a quick tangent and talk about the two types of master links.

Rivet vs. clip type master links

Right now our new chain has two ends that need to mated together to form an endless chain. This can be done with two kinds of so-called “master links” - rivet and clip type links. Clip type links are easier to use and feature a clip that will slide over the two chain pins preventing the side plate from coming off. Rivet type master links need to be riveted - that is the head of the pins on one end will be pressed out a little bit (kind of like a small mushroom) so they are wider at the end, ensuring that the side plate cannot come off.

Rivet type links are strongly recommended as once properly installed basically cannot come off. If the clip of a clip-type master links is removed (ex. because a rock strike), it’s possible that the side plate comes off while riding. This could result in the chain quite violently being ejected down the road behind you.

Pressing

No matter if you chose to use a clip type or rivet type master link, the first few steps are the same - starting with the pressing of the side plate onto the master link. Here’s the steps:

Thoroughly grease the master link pins and o-rings with (the likely provided) grease. This grease will be sealed in for the life of the chain.
Slide the first pair of greased o-rings onto the pins of the master link
Attach the master link to the chain, connecting the two ends
Mount the greased second pair of o-rings onto the master link
Mount the side plate making sure it is aligned well with the pins
Press the side plate using a chain press tool

The last step (6) is the tricky one. There are some things to pay attention to:

Double-check that the side plate is aligned properly with the pins
Press the side plate bit by bit, checking your progress as you go
As the pin emerge through the side plate, check that your chain tool is not interfering

⚠️ And perhaps most importantly: ⚠️

Know the expected width of a link in the chain and only press the master link to meet that width

A too tight master link will be no good as it will have more bending resistance, leading to more heat, wear, and premature failure. Ideally use a precise caliper to measure other links on the chain and only press the side plate enough so the width is within a few tenths of a millimeter of the other links. The closer, the better. Remove your press tool often to check the width.

The pressing will take some effort - if you’re not making progress double check alignment of your tool before applying more force

Metal expands - heat up the side plate to make the pressing effort easier!

Check the alignment of the o-rings on the opposite side of the master link. It should look even.

Riveting

Unlike clip-type master links, where the process pretty much ends at the last step, we have one more thing to do. Riveting is essentially expanding the tips of the pins so that the side plate cannot come off. The master link pins have a dimple that we’ll expand using our tool, which is going to take persistent force.

Once again, it’s very handy to have a caliper. A good rule of thumb is to expand the pins until they are about the same width as the factory riveted ones on the other link on the chain. I switched between the two pins, slowly expanding and measuring each in turn.

It’s also important to check that the chain tool is properly aligned - some chain tools have a dimple on the other side of the riveting press that fits around the factory rivet on the other side of the master link.

11) Chain adjustment & alignment

Congratulations, you’re almost done! The final step of course is adjusting the wheel and chain - you’ll want to ensure using the built-in chain adjusters or a chain alignment tool that the rear wheel is aligned with the front, as well that there is adequate chain slack. Chain slack will differ from bike to bike but it’s always better to have a slightly more loose chain rather than a too tight chain. Some more things to remember:

As the swing arm compresses, chain slack will reduce (ex. when going over bumps)
Check chain slack at multiple points along the chain - some spots may be tighter than others!
A chain alignment tool can come in handy. I like this one
Tighten/loosen the chain adjusters one quarter rotation at a time

Finally, tighten the chain adjusters and torque the spindle/axle nut.

Conclusion

…And that’s it! Lube the chain and in the next thousand miles check chain slack more often than usual - new chains stretch a little bit early on.

This procedure likely took me several times the amount of time it would take a professional mechanic, but I gained a lot of understanding on how motorcycle chains work. I also now have more confidence in tackling something a little bigger than just oil and filter changes.

The most important thing here is to approach everything slowly and read the directions for your tools and service manual for your motorcycle. If something takes more force than you’re expecting, double check what you’re doing before applying even more force.

The biggest thing I noticed when going from my old and worn chain to the new one is just how much quieter it was. The old chain, even shortly after lubing, made quite a bit of noise. The new chain is significantly quieter even 300 miles after the last lube.

Setting up Automatic Build & Deploy of a Jekyll Blog

2020-08-22T00:00:00+00:00

In the previous post I demonstrated how to set up a spellcheck & lint action for a Jekyll powered site. The final piece in our GitHub actions automation puzzle is to build & deploy the site without having to do anything manually. The goal is to create the following actions:

On every pull request, run a jekyll build to assert that the site can be build successfully ✅
On every push to master, run jekyll build to produce the static site 📦
On every push to master, deploy the site using SSH 🚀
On every push to master, purge the Cloudflare cache 💨

Just as before, I will be using GitHub actions.

Assumptions

As of the time of writing, my blog is hosted on a web server controlled entirely by me. This means that deploying the site is as easy as copying files over SSH. Your setup may vary (and mine will certainly change as well - I always have plans for improvement 😀). You don’t have to do it the same way I do, here are some alternative ways to host a Jekyll site:

Amazon S3 (probably the cheapest for low traffic blogs)
GitHub Pages (low entry barrier, very solid GitHub integration)
Other platforms

For me this blog is more of a fun learning experience so I will go the 100% manual way. Of course manual does not mean repetitive, the goal still is to automate as much as possible. I just also want to write as much automation myself as is worthwhile 😛

Let’s get to it!

Build Action

The goal of this workflow is to build the Jekyll site, just to see if it’s successful or not. We will take care of the actual deployment in a later action, only to be performed when pushing to the master branch. However it is still worthwhile to run a jekyll build to ensure that the site can be built, and that Jekyll does not error out. This way we can ensure that code that is merged to staging or master will actually result in a site that at least compiles 😛

Let’s take a look at the code:

name: Build

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  pull_request:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  jekyll:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Build
      uses: SebasWild/jekyll-build-action@445d650279c45fd66c59ddd38620ddb30fceaedf

Just like the last lint action, this one is pretty simple. Originally I was using Jerry van Leeuwen’s jekyll-build-action, but I got some errors downloading the Ruby gems the site requires, so I forked the repository and modified the base docker image it used from the latest version of Jekyll to Jekyll 3.

Deploy Action

Arguable the most complex action (comparatively) for my blog is the deploy action, since it runs through several steps:

Run jekyll build
SSH into the server & copy the generated files
Purge Cloudflare cache

This action took a bit of tweaking to get right, especially narrowing down the parameters required to correctly rsync all the files over to the server. Here’s the code:

name: Deploy

on:
  push:
    branches: [ master ]

jobs:
  jekyll:
    name: Build and deploy Jekyll Site
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Build
      uses: SebasWild/jekyll-build-action@445d650279c45fd66c59ddd38620ddb30fceaedf

    - name: Deploy to Server
      uses: easingthemes/ssh-deploy@v2.1.1
      env:
        SSH_PRIVATE_KEY: $
        ARGS: "-rzv --delete --delete-excluded --chmod=g+rwx"
        SOURCE: "./_site/"
        REMOTE_HOST: $
        REMOTE_USER: $
        TARGET: $

    - name: Purge Cloudflare Cache
      uses: jakejarvis/cloudflare-purge-action@v0.3.0
      env:
        CLOUDFLARE_ZONE: $
        CLOUDFLARE_TOKEN: $

Copy phase

The first two workflow steps are the same as for the aforementioned build action - after that it gets more interesting. I use Dragan Filipović’s ssh-deploy which uses NodeJS to ssh and rsync the built jekyll site files to my server. Notable here is the use of secrets - you definitively do not want to expose vital things like SSH keys to your server by having them in the code.

Instead of username/password authentication, it’s generally always recommended to use SSH keys (with a passphrase protected private key) with your server refusing password logons. This way you can only log on if you posses your private key and the server knows your public key. It can also be more convenient than username + password logon on since private keys do not necessarily have to be encrypted with a passphrase, so you could log on without typing anything in at all.

I make use of the above by storing such a private key in a GitHub secret - this SSH key allows the build action to log on to the server using a limited account with access only to the directory where the static files reside. Secrets are maintained on a per repository basis, and are basically key-value pairs. Once set, values cannot be read again, only overwritten. When the workflow is run, this SSH key is filled in to the environment variable SSH_PRIVATE_KEY.

Updating a GitHub secret

The ARGS environment variable is the meat of the deployment workflow. It uses rsync, and in ARGS you can define the options to be passed to the rsync command, in this case:

-r recurse into directories
-z to compress files during the transfer
-v for verbose output for easier debugging
--delete to remove extraneous files in the destination directory (❗️important❗️)
--delete-excluded to also remove excluded files in the destination directory
--chmod=g+rwx to change permissions on the transferred files

The --delete options are important, as we want to make sure that the destination directory on our web server contains only the files that jekyll build produced. If the previous version of the site for example contained some content that is now removed, we do not want that to stick around. The --chmod option might vary for your setup - but for me this was necessary as I wanted the group that technical user is part of also to have write access to the site contents.

The rest of the environment variables are easier to understand. SOURCE defines the directory where the files to copy are - in this case the results of a jekyll build are (as is usual) placed in the _site directory. The REMOTE_HOST defines the host where to deploy files to - e.g. swild.dev. REMOTE_USER is the username with which to use SSH, and REMOTE_TARGET is the destination directory to rsync files to.

Cloudflare Purge Cache

This blog is proxied by Cloudflare, simply to speed the site up a little bit. The server hosting this site is also seriously underpowered, with a 2010-era processor (single core!) and a measly 2GB of RAM. While it does not take a lot of resources to host a static website (and it’s not like this blog gets many views…), Cloudflare is perfect for ensuring fast load times even when the user is far away from where you host the site.

To ensure that everyone sees the same site content, we should purge the Cloudflare cache after a successful deployment so that for the first subsequent loads after Cloudflare will fetch the latest files from our origin web server. This can easily be done in the Cloudflare console, but it’s a lot more convenient to do via API 🤙

For this I use Jake Jarvis’s cloudflare-purge-action. It’s configuration is simple, although it requires some additional configuration on the Cloudflare side.

CLOUDFLARE_ZONE is the zone ID of your domain. This can be seen on the sidebar of the domain overview page, under the “API” header.

While it’s possible to use your global API key, it’s recommended that you set up a restricted token, one that is locked to just the zones that you specify. You can create such a token by navigating to your Cloudflare profile then navigating to the “API Tokens” and tapping “Create Token”. Configuration will vary for you, but generally you want to do something like the following:

Note that the API token only has permissions to clear the cache for a very specific zone. That way if the key was compromised, all an attacker could do with the key is to clear the cache 😀

Results

After a not-so-insignificant time debugging permissions issues with the deployment workflow, I now have a pretty solid CI/CD pipeline. The checks & actions implemented above allow me to work on the site from anywhere and any device (barring local preview, which requires Docker), and a simple push to master triggers a release deployment. Pretty cool, right? 👍

Setting up Jekyll Spellcheck & Linting using GitHub Actions

2020-08-21T00:00:00+00:00

It’s easy to make typos - even if you’re proofreading. For VS Code, there are some handy spellcheck extensions - I like to use Code Spell Checker, but it’s good to have an additional check at the pull request step. I might be editing on a device where I do not have an integrated spell checker, for example. This is where the spellcheck action comes into play.

The same goes for maintaining good style when writing Markdown. It’s super common to use Linters when writing in an actual programming language, and at least according to my own experience this isn’t so common when using a markup language like Markdown. In a traditional programming language, linters are useful to enforce a consistent code style. In the case of Jekyll, it’s just a small additional check to ensure that we’re writing proper Markdown 😀

Spellcheck Action

For my GitHub Spellcheck workflow, I am using Robert Jordan’s spellcheck-github-actions.

Source

You can configure your workflows in the .github/workflows directory in your repository. They’re written in YAML. Let’s take a look at the code, then break it down 📝

# .github/workflows/check_spelling.yml

name: Spellcheck
on:
  pull_request:
    paths:
    - '**.js'
    - '**.txt'
    - '**.html'
    - '**.md'
jobs:
  spelling:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Check Spelling
      uses: rojopolis/spellcheck-github-actions@v0.5.0

The first few lines of the workflow specify its name and the events that trigger it:

/// ...
# The name of your workflow. If you omit it, the file name will be used instead.
name: Spellcheck
# The name of the event that triggers the workflow.
# This can be a single event, an array, or other advanced usage (refer to the docs).
# Ex. pull_request, push
on:
  # The spellcheck workflow should trigger when a pull request is opened.
  # After all we want this to be a check/voter on if our PR can be merged.
  pull_request:
    # We restrict the running of the workflow -
    # only run when Markdown files are changed.
    paths:
    - '**.md'
/// ...

The next section configures the jobs & steps per job to run. Jobs run in parallel by default, and in this case we only have one.

# A workflow can be made up of more than one job, running in parallel by default.
# In our case, we just have a spellcheck job
jobs:
  spelling:
    # The machine the job runs on. In this case, the latest version of ubuntu.
    runs-on: ubuntu-latest
    # The sequence of steps to perform.
    # A step can do anything from running commands to performing actions in your repository.
    steps:
    # Specifies the action to run as as a step.
    # This could be an action defined in your repository, from the marketplace, or even a Docker image.
    # The checkout action checks out our repository so the spellcheck can access it
    - uses: actions/checkout@v2
    # The name setting determines what the GitHub UI shows
    - name: Check Spelling
      # We use rojopolis's spellcheck action, pinned to tag 0.5.0
      uses: rojopolis/spellcheck-github-actions@v0.5.0

Note that above, we specify that we want to use the spellcheck-github-actions pinned to version 0.5.0, rather than something like @master where you’d potentially get an update down the line that breaks your build. As an aside however, check out this really thought-provoking article on using other’s actions with your own code (and more importantly, secrets).

However we’re not done yet. The next section describes how to configure the spellcheck action.

Configuration

Under the hood, spelling-github-actions uses PySpelling, which can be customized using a configuration file - typically called .spellcheck.yml. Notice the . prefix making it a hidden file. This is convenient as such a configuration file is typically “set and forget”. The excellent docs can be found here.

Mine looks like this:

matrix:
- name: Markdown
  aspell:
    lang: en
  dictionary:
    wordlists:
    - .wordlist.txt
    encoding: utf-8
  pipeline:
  - pyspelling.filters.markdown:
  - pyspelling.filters.html:
    comments: false
    ignores:
    - code
    - pre
  sources:
  - '**/*.md'
  default_encoding: utf-8

My configuration file is changed very little over the default that comes with the spellcheck action - pretty much the only thing that I’ve added is a custom whitelist of words. I’ve found that PySpelling produces a lot of false positives, especially with acronyms.

Most of the configuration is pretty self-explanatory, what’s interesting though is the pipeline configuration. With the pyspelling.filters.markdown pipeline, the Markdown is converted into HTML. Subsequently the pyspelling.filters.html processes the HTML, filters out undesired tags, and then outputs the extracted text from the HTML tags to be spell checked.

The sources option allows us to filter what files we want to spellcheck. It’s configured to check all Markdown files, no matter how deeply they are nested in subdirectories.

Finally, the wordlist.txt is simply a text file containing a list of words that will be ignored during the spellcheck process. Each word is on a new line.

Spellcheck errors are reported in the ‘Checks’ tab.

Lint Action

Markdown is awesome for being able to create formatted documents using raw text, but it does have some syntax & formatting guidelines. Much like developers have linters to enforce code style practices, Markdown has this as well. For this I make use of Nick Osborn’s github-action-markdown-cli. In comparison to some of the other workflows this one is quite easy to configure:

# .github/workflows/check_spelling.yml

name: Lint
on:
  pull_request:
    paths:
    - '**.md'
jobs:
    markdownlint-cli:
        runs-on: ubuntu-latest
        steps:
        - uses: nosborn/github-action-markdown-cli@v1.1.1
          with:
            files: .

And that’s it for this one 😀

My Jekyll Workflow

2020-08-19T00:00:00+00:00

TL;DR Any text editor + some GitHub branches tied together with GitHub Actions

In the previous post, I described how to set up a local development environment for your Jekyll-powered site using Docker, including live reload. The jekyll serve command is really helpful here because it lets us easily spin up a local web server to test our site - but this isn’t meant for production. To do it properly, we need to use a fully featured web server. However, I wanted to do more than just that - I wanted an end to end development & deployment pipeline:

• A fully portable development environment (using Docker)	✅
• Hassle-free setup for the live site on a VPS/cloud server	✅
• Automated linting	✅
• Automated spellcheck	✅
• Automated site build & deploy to live web server	✅

Workflow

The diagram below shows how I work on the site and what happens at each stage of the process. In this post I will talk a little about each, but deep-dive posts on the individual GitHub Actions used will be reserved for some additional posts 👍

The diagram shows some key concepts important to me:

Write anywhere
Robust version control strategy
Robust automation

1. Write Anywhere

While I typically do development work on my Mac, one of my goals was to make working on the site as easy as possible, and with the least amount of setup involved. Ideally using just a text editor and git. Building the site as well as deployment should be done by the CI/CD pipeline - so that I could for example use something like an iPad on the go. Of course a Ruby or Docker environment is needed for previewing the site locally, but for simply writing content I wanted to be able to use a tablet or phone on the go as well.

On my iPad, I use the following apps to develop the site on the go:

Textastic - I like this text editor as it features syntax highlighting and easy integration with Working Copy as well as Files.app
Working Copy - Definitively not cheap, but a really good git client for iOS
Terminus - Great SSH client for iOS & Android. The free version suits my basic SSH needs quite well

Working on an iPad with an keyboard & trackpad (thanks iOS 13.5 😀)

On my Mac, my go-to editor of choice is VS Code. Here are some handy extensions that made working on the site easier for me:

GitLens - Adds a host of extra git features, such as per-line git blame in the file you’re currently editing
markdownlint - Integrates MarkdownLint right into the editor, highlighting violations as you edit
Draw.io Integration - Lets you edit draw.io files right in VS Code
Docker - Adds a slew of Docker integrations for editing Dockerfiles and managing containers

The draw.io (diagrams.net) extension for VS Code is pretty neat!

2. GitHub Workflow

A robust branching strategy is always a good thing in any repository. There’s tons of different approaches out there, but in general you want a strategy that allows you to work on features, bugfixes, and other things in isolation and without tripping over all the changes you are making in parallel. This means for example not pushing to master for everything but using feature branches. The strategy I’m following for the blog goes as follows:

master branch

master is always the current live version of the site. This way if there hotfixes that need to be made, I can branch off of master, fix the issue and open a pull request back into master. GitHub Action build & deploy the site on push to this branch.

staging branch

staging contains all the changes meant to go live in the next deploy. While I’m not using tags or versioning right now, staging serves as the branch to contain all the changes that I want to deploy to the site in one go.

feature branches

Drafts for new posts, site features, and really anything else besides hotfixes are made in their own feature branches, typically created off of staging. It’s good practice to have your feature branches be about one change, and one change only. Overcome the urge to work on multiple things in one feature branch. This might complicate the pull request once you’re done and make code review more difficult. This is not super applicable here as I am working on the site by myself, but is important when you are working in a team.

GitHub branch setup with feature branches, pull requests, and checks.

3. GitHub Actions

In August 2019, GitHub Actions gained CI/CD ability. What’s very cool about this is that if you want CI/CD for your project you no longer have to use a third party service. No more authorizing that third party to access your repositories - everything can now be done right within GitHub itself. This project was my first exposure to GitHub Actions and setting up some workflows.

For me, I wanted three main checks:

Check if the site builds with jekyll build
Check for linter violations using MarkdownLint
Check for spelling errors

These checks (with the exception of the deploy action), will happen on every pull request. I also wanted the site to be deployed to production on push to master. All of the above checks as well as the deploy are implemented with individual workflows, and I will go into each in the posts to follow 👍

Checks run on every pull request, and are required to pass before merging.

Engine Noise? Might want to check your timing chain tensioner!

2020-07-19T00:00:00+00:00

TL;DR If you motorcycle engine starts making funny, loud ticking noises, you might want to check your timing chain tensioner.

I own a KTM 390 Duke that I love dearly. It’s light, has good power for its size, and is super fun to flick around in corners. Yet especially the earlier models (mine is a ‘16) do not - according to some people - have the best reputation when it comes to reliability. I’ve only put ~10k miles on my bike and up until now no real repairs were needed besides the usual oil changes, valve adjustments, etc.

Some weeks back as I was getting off the highway I started hearing what I at first thought was a faulty exhaust from the car in front of me. I was stopped at a light and what I was hearing sounded a lot like an exhaust leak - as if something had rattled loose and let some gases escape. After another few seconds of riding though it became obvious that this wasn’t coming from anyone around me, but from my bike. Luckily I was quite close to home and was able to quickly take a look.

Initial Troubleshooting

When you spend a lot of time doing something, whether it’d be motorcycle riding or really any other activity you get used to how things behave, sound, and feel. If something is off, you can realize it pretty quickly. After getting off the bike and putting my ear to the engine I could immediately tell that something was just not right - and to be quite frank it scared the hell out of me. I recorded what I was hearing so I could send it to a buddy of mine:

Looking at that video it sounds nothing like an exhaust leak - it’s quite obvious that there is a lot of ticking going on. In person however, it sounded a lot different. After verifying that the exhaust system did not seem to have any loose parts or stray holes there really were only two things left that I figure might be the culprit:

Out of spec valves
Super loose timing chain

The valves were adjusted somewhat recently, and so I decided to check out potential culprit #2 first.

Examining the Timing Chain Tensioner

As a prerequisite, make sure your engine is at top dead center. If this is not the case, you could risk the engine jumping timing.

On the 390 Duke, removing the tensioner is simple. Remove the screw marked in step 1, noting that there is an O-ring underneath. Then, remove the two screws marked in step 2. Finally, you can take out the tensioner and its gasket.

Once taken out, the tensioner looks like this:

Let’s look at its function a little more closely.

Replacing the Tensioner

The stock tensioner is an automatic, spring based tensioner. It features a little tensioning rod (pictured above) that exerts pressure on a guide rail inside the engine (not pictured) in order to tension the timing chain. The purpose of the timing chain is to synchronize the rotation of the camshaft with the crankshaft - making sure that valves open & close exactly when needed. A loose timing chain could result in jumped timing, which will cause the engine to not perform the precise sequence of events to complete a four-stroke combustion cycle, or worse grenade the engine.

The tensioner in the 390 Duke is essentially on or off - either the spring pushes the tensioner out, or the tensioner is “locked” all the way in. Proper operation can be verified with the tensioner still in the bike by doing the following:

With a flat-head screwdriver, turn the adjustor bolt (#2 - hard to see) clockwise (#3) until you can’t anymore. This is the lock point.
Remove the screwdriver. Note that the tensioner is now at its shortest length.
“Unlock” the tensioner by using the flat-head screwdriver to nudge the adjustor bolt counterclockwise (#4) ~ a quarter turn. You should feel pressure on your screwdriver as the spring engages.
Remove the screwdriver, and the spring will extend the tensioner until hit hits the timing chain guide - you’ll hear a small clack.

It is possible to over-extend the tensioner by rotating counterclockwise after its automatic spring-based tension!

In my case the issue quickly became obvious. In step 1 above, I noticed that there was no tension on my screwdriver at all the as spring had completely failed. As such, the timing chain was at its loosest setting - hence the noise. I ordered an OEM replacement and installed it like so:

Bring the tensioner to the locked position as described in step 1 above.
Place a gasket to sit between the engine and the tensioner.
Insert the tensioner, making sure to orient it correctly.
Mount and tighten the screws with the correct torque values.
Like in step 3. above, unlock the timing chain tensioner. You should faintly hear it impact the guide inside the engine.
Mount and tighten the cover screw along with its O-ring.

In my case, this immediately made the horrible noises I was hearing go away, and I knew I had found the root cause ✅

Final Thoughts

While the concept of timing chains & their tensioners is not motorcycle specific, the steps described in this post are. They are probably similar for other bikes, but I would always recommend following your owner’s manual. It is also very much worthwhile to get a repair manual for your motorcycle as those go much more in depth than an owner’s manual.

There are also manual timing chain tensioners. Instead of being spring powered, they are manually adjustable. Some people prefer those as they are simpler and more reliable.

Running Jekyll with Docker

2020-07-19T00:00:00+00:00

TL;DR I share how to create a highly portable jekyll development environment. git-clone your website repository and run docker-compose up 🚀

Motivation

Normally, Jekyll requires a full Ruby development environment. This isn’t hard to setup, and the steps are described here. This is fine and good, but I wanted a fully portable environment without having to install Ruby or Bundler. For this I thought Docker is a good solution. This way, the only thing that needs to be installed wherever I am working on the site is Docker itself.

Docker

Docker is a platform that uses virtualization to deliver software in packages called containers. These containers are significantly more lightweight than full-blown virtual machines, as OS-level virtualization is used.

docker-compose

docker-compose is a command-line utility to work with docker-compose.yml files. Docker compose can be used to quickly define and run multi-container Docker applications with a single command and configuration file. A docker-compose.yml file contains everything from image configuration, network configuration, and commands to run when the containers start.

Jekyll docker-compose

For my personal site, I want a local development environment that is highly portable - ideally as easy as git clone-ing the repository and running docker-compose up. That’s exactly what the docker-compose.yml file below does 👍.

version: '3'                        # docker-compose file format. Ex. 1, 2, or 3.
                                    # Different versions work with different versions of Docker, and support different features

services:                           # Configs for the various services, we just have one
  jekyll:
    image: jekyll/jekyll:latest     # Image name to pull from Docker Hub
    command: jekyll serve --livereload     # Command to run when the container starts
    ports:
      - 4000:4000                   # Map local port 4000 to port 4000 in the container
      - 35729:35729                 # We need to specify another port for the Jekyll 3.70+ live reload feature
    volumes:
      - ./src:/srv/jekyll           # Mount a volume so the container can access local data in the src directory

Let’s break down the compose file.

The services mapping is where we define our containers. In YAML, a mapping is basically a collection of key:value pairs. We can call each container what we’d like, and in this case we only have one - “jekyll”
The image entry tells Docker what image to use. We could roll our own with a Dockerfile, but there is a nice official Jekyll image available in Docker Hub that we can use.
With the command entry, we can override the default command in the image.
The ports sequence defines what ports to hook up from the container. The bundled web server in the image listens on port 4000, so we map this to our machine’s port 4000. We could choose a different one, ex: 3999:4000
The volumes sequence defines what persistent data to connect to the container and where to mount it. In this case, I have my Jekyll source files in the src subdirectory.

Let’s look at the command entry a little more closely. We can see that it passing some arguments to the jekyll command line tool:

serve builds your site and serves it locally using bundled web server.
--livereload is very cool, it reloads your browser window when you make changes to your source files. Very handy for development.

Livereload

Introduced with Jekyll 3.7.0, this feature will auto re-generate the pages corresponding with your edits, and trigger your browser window to refresh (should you be previewing the site). Without this, you would have to use the --watch option and manually refresh the browser page to get the latest changes - but that’s one more click and you have to switch focus to your browser 😛 One thing to note though, at least on Safari I’ve found that when the page refreshes there’s a good chance that you lose your scroll position.

Also note that this feature works by injecting a new JavaScript file, livereload.js. This file listens for messages on port 35729, and will refresh the page when Jekyll re-generates a file. This is why we have to specify an extra port in our compose file.

Workflow

Typically when working on the site, I will have an editor (VS Code for me), and a browser pointing to localhost:4000 side by side. Starting work on the site is as simple as running docker-compose up 👍

Closing Remarks

Note that jekyll serve is only meant for use for development purposes. The web server that it uses is not meant to handle multiple incoming requests, and should really not be used in production. For deployment, I’d recommend running jekyll build and using a proper web server like NGINX or Apache to serve the site. I’ll have another post about this soon 😀

Starting a Self-hosted Blog

2020-02-02T00:00:00+00:00

Testing

I’m a professional iOS developer - most of the web development world is unknown to me. I have done some small projects at work with SAPUI5, but I have to admin I was never really good at it. But, I think any good developer should know a little bit of everything, and that includes diving into some web development. A lot of developers also have blogs and personal sites hosted on places like Medium or GitHub pages. So, I wanted to get my feet wet - but rather than hosting on GitHub pages or writing posts on Medium, I wanted to self-host all the way.

I knew I wanted to start off with a static site using Jekyll. Jekyll caters super well to blogs, with tons of readily available themes and markdown-powered posting. It’s a good way for me to start my web learning journey 👍.

I also knew that I wanted to self-host. Something like GitHub pages is enticing, and super quick to set up. But by self-hosting, I can learn some more about setting up a web server, a good CI/CD pipeline, linting, and server hardening.

Overview

I spent some time planning what I wanted my web stack to look like, but as this project goes on odds are some of this will change 😀 As I figure out & create my site, I will write some blogs detailing the entire setup ✅

Key Components

Jekyll: Static website generator to be used for the content of the site.
Docker: Will run Jekyll & a web server in a container for easy local environment and production deployment.
Server: Probably a DigitalOcean droplet or cheap dedicated server.
CI/CD: GitHub actions to build, lint, and deploy the site automatically.
CDN: Cloudflare to provide a speedy site.

Step by Step Blog Series

Sneaky edit months later…

I explain how to run a local development environment: Running Jekyll with Docker
I describe my development GitHub & mobile development workflow: My Jekyll Workflow
Showing how to set up spellcheck and linting actions: Setting up Jekyll Spellcheck & Linting using GitHub Actions
Setting up automated build & deploy of a Jekyll site: Setting up Automatic Build & Deploy of a Jekyll Blog