Matthew Roach

Static Site(s) with Kamal

2024-10-08T00:00:00Z

Kamal is an open source tool created by 37signals as part thier cloud exit. That as per their tag line allows you to Deploy web apps anywhere. Quite the statement! But, they also say;

Originally built for Rails apps, Kamal will work with any type of web app that can be containerized.

As you may of noticed they use the term web app. This is great if you have a web app to deploy, but what if you only have a static website to deploy. Is Kamal of no use? You maybe right in thinking its not the tool for you, but you'd be wrong. Kamal is a wrapper around docker, and if you can containerize your static website you can use Kamal to deploy it.

Is Kamal overkill for a static site - possibly. But remember Kamal allows you to deploy anywhere, and which Kamal 2 you can host multiple sites on a single server. You can remove the need to use services like Netlify, Vercel and the host of other services out there. Now don't get me wrong, these services are very easy to use and great for hosting static sites, they have some great developer experience (DX) around them to connect various services together to make deployments happen at the click of a button or with seamless automation.

Moving from one of these services to uisng Kamal does require more work upfront and a different mindset. You are trading a third party hosting your website to hosting your website on your own server.

I used the following steps to deploy a very basic static site, you can see here - https://staticaml.tealeaves.dev.

Prerequisites

A domain name and ability to change DNS records
- Recommend using Cloudflare with SSL termination
A server, using Hetzner Cloud server at €4.55. Be sure to set up SSH access via public/private key
- You'll need the IP address to the server for Kamal config.
A container registry account, Docker Hub offers 1 free private repository.
- You'll need to set up a personal access token for docker hub access
A static website to deploy - source should be within a git repository.
Docker installed on your machine
Ruby installed on your local machine (not a requirement to use Kamal, but is how I'll explain using Kamal)

For the remainder of this post I am going to assume you already have a static website to deploy, this allows us to focus on setting up Kamal and containerizing the static site.

Containerizing the static site

As per the Kamal website, it will work with any type of web app that can be containerized. Before we get into setting up Kamal we first need containerize our static site. For a static site to be deployed we need to use a web server. There are a number of web servers available, we are going to use nginx.

For the next part I am assuming within your repository you have your static site files within a src directory. Having all the site files within a sub directory will make things a little easier.

In the root of your static site repository create a Dockerfile with the following

FROM nginx
COPY ./src /usr/share/nginx/html

EXPOSE 80

A very basic and minimal docker container.

FROM nginx - Tells docker to use the nginx image
COPY ./src /usr/share/nginx/html - Copies our static site files into the webserver directory nginx serves files from
EXPOSE 80 - Describe which ports your application is listening on

Setting up Kamal

In the root of your repository

Create a .ruby-version file with ruby version - echo "ruby-3.2.2" >> .ruby-version
Create a Gemfile file - bundle init
Install kamal - bundle add kamal
Initialize kamal - kamal init

You will now have two new folders added to your repository .kamal and config. Within the config folder there will be a file deploy.yml. This file is where all the configuration settings are set, you will be updating this file with your own settings.

Update config/deploy.yml with correct values based on your own accounts.

service - a unique name of your application
image - The container image as per docker hub - {docker-username}/{service}
servers.web - The IP address to the server you want to deploy to
proxy.ssl - Set this to false as we are using Cloudflare to handle SSL
proxy.host - The URL of the site - e.g. my-static-site.com
registry.username - Your docker hub username
env - Update env config to make the environment variable KAMAL_REGISTRY_PASSWORD available to container

# Name of your application. Used to uniquely configure containers.
service: staticaml

# Name of the container image.
image: matthewroach/staticaml

# Deploy to these servers.
servers:
  web:
    - 123.456.78.987

# Set ssl: false if using something like Cloudflare to terminate SSL (but keep host!).
proxy:
  ssl: false
  host: my-static-site.com

# Credentials for your image host.
# Default to using docker hub.
registry:
  username: matthewroach
  password:
    - KAMAL_REGISTRY_PASSWORD

# Configure builder setup.
builder:
  arch: arm64

# Inject ENV variables into containers (secrets come from .kamal/secrets).
env:
  secret:
    - KAMAL_REGISTRY_PASSWORD

For the environment variable KAMAL_REGISTRY_PASSWORD we need this to be set as an environment variable. To do this we can use .env file to set the secret in. Make sure you add the file to your gitigore to avoid having your secret in git.

Create a .env file with key KAMAL_REGISTRY_PASSWORD and the value being your docker hub personal access token

KAMAL_REGISTRY_PASSWORD="{DOCKER PERSONAL ACCESS TOKEN}"

To get the environment variable available to Kamal config we need to update the config/deploy.yml file to load the environment file using dotenv - add the following to the first line of config/deploy.yml

<% require "dotenv"; Dotenv.load(".env") %>

Be sure to commit all your changes, and then we are ready to deploy our site

Kamal Health Check

As part of the Kamal tooling it requires a health check endpoint (which can be configured), by default it uses /up URL of your site to check if things are health.

Be sure to add a route to your static site. Simply add an index.html file that is served at my-static-site.com/up

Deploying Site

For the first deployment we run kamal setup from the root of our repository. Kamal will do its thing now, running through a number of docker steps, and setting up your server with a proxy and your static site.

For following deployments you'll need to make changes and be sure to commit them with git, and then you can run kamal deploy.

My demo site deployed using Kamal - https://staticaml.tealeaves.dev.

I've already used the same steps on a number of my other static sites to deploy them, and with Kamal 2 I am able to deploy them all to a single server.

2021

2021-12-31T00:00:00Z

Well, a global pandemic

Not much changed from 2020. At times it felt like things were getting better, but as we all know that was short lived. Three vacinations received in 2021, how many will there be in 2022?

Some items that happened in what felt like a blur of a year, in no particular order -

👨‍💻 Started off the year by switching jobs after the move last year not working out as I expected
🚴 Bought a new road bike and enjoyed the early spring sun, even got Pamela out on the open roads a couple of times, even when there was no cake involved
🏖 Enjoyed a family holiday to Edinburgh that included my parents
🚘 Switched to an electric car, first a Vauxhall Corsa-e, then to an Volkswagen ID.3
🎉 Now a parent to a teenager
🏑 My son started playing field hockey for the men’s 2nd team
🏑 I started playing hockey again, after playing it when I was younger (20+ years ago). Been amazing being able to play alongside my son, and watch how fast he is progressing.
👩‍🎓 My wife finished her studies and started a new job with her qualifications

2022 - who knows what’s going to happen…

A Themeable Design System

2021-12-09T00:00:00Z

I've been involved with design systems for a good number of years. Even before design systems, there where styleguides. Remember those?

Design Systems, Styleguides, pattern libraries, etc. They are all great tools/systems and having created and consumed a variety of these systems over the years I've recently come up against a problem where the "traditional" systems where not flexible enough.

If you go look at any of the big tech companies desgin system(s) they have published you'll notice they are all aimed at the companies usage, which is great. If you are building an integration on top of shopify using their design system polaris to maintain consistency from your integration to shopify's application is great.

Even some big names provide "themes" on top of their systems. If the company has a few identities you are able to use the correct theme for the relevant company.

These are all great, but -

What if you wanted to provide as much flexibility as possible?

What if you didn't know who was going to using the system?

What if you wanted the ability for the system to be flexible enough to apply a companies own style to it?

These are just a few of the questions I was faced with answering recently. How can we provide a core set of components, that are ultimately fully customisable at the core? But also provide an "out-of-the-box" theme.

Based on these questions and more, I came up with following solution which I am going to walk you through.

Technology

For the solution as it is to be used in part of an exisiting ecosystem. The technology stack wasn't completely open. React was a hard requirment, the styling was a bit more open - it was either going to be a CSS-in-JS approach or CSS. I opted for CSS, but with Sass as the integration layer, and the end result being a standalone CSS file.

System Overview

The system is broken down to three parts

Theme
Components
Blocks

The core of the system is a set of components, think of these as the core. The components would be used as the building elements of blocks, example of such components -

Paragraph
Image
Caption
Date
Link

These components are very presentational, and are a means to provide a consistent interface to commonly used components of the system. The components are not limited to outputting text, images, etc, a component can also be a layout component.

Blocks are used within the system to provide an entry point and exit point. The entry point being the internal system, and the exit point being the published page. A block is a composed component of functionality that is made up primarily of components. An example of a block would be

Promo Item
List of articles
Search Results list

Theme the theme is what brings it all together and holds the styling information. The theme is a collection of Sass maps that hold the CSS properties and values for a component, a block and also the ability for component within a block to be styled.

System Breakdown

Components

To understand how it all fits together and what is involved at each level, I am going to run through a basic example.

The paragraph component looks as follows

import React from "react";
import PropTypes from "prop-types";

const Paragraph = ({ children }) => <p className="c-paragraph">{children}</p>;

Paragraph.propTypes = {
	children: PropTypes.string.isRequired,
};

export default Paragraph;

Very simple and basic React component that takes children and output wraps that in a p tag, where we apply a class of c-paragraph.

The class applied to the component is exposed via a Sass file which looks as follows

.c-paragraph {
	@include component-properties("paragraph");
}

This would the bare minimum for a component Sass file. It looks a little bare, and not doing anything at the moment. This is because the styling will come from the theme. We are using a mixin provided by the system that would output the CSS properties and values for a paragraph

Blocks

As mentioned earlier, blocks are composed of components. An very simple block could look like

import React from "react";
import PropTypes from "prop-types";

import { Paragraph } from "components";

const FakeStory = {
	description:
		"One of the highest paved roads in Europe, this mountain pass makes for a thrilling road trip into the misty mountains above the Adriatic and Ionian seas.",
};

const Promo = () => (
	<div className="b-promo">
		<Paragraph>{FakeStory.description}</Paragraph>
	</div>
);

export default Promo;

As you can see it's very basic. The promo block is only using a single component in this example, but it could use any number of the core components if needed. The block has a wrapping div with a class b-promo this is then exposed via a block Sass file to allow styling of the block but also components inside a block.

The Sass file for a block is as follows

.b-promo {
	@include block-components("promo");

	@include block-properties("promo");
}

Similar to components, we are making use of mixins to load in the promo block styles, but also load in the styles for components within a block. How the component styles work will be explained below as part of the theme.

Theme

The theme is where the styling is controlled for a component, a block and for components within a block.

The theme is utilising Sass to extend the capabilites of CSS by providing some mixins and better variable management. The output from the Sass files is a CSS file that is utilising CSS Variables. The primary reason to use Sass is the power it provides with being able to doing looping and provide functions (mixins).

Within the theme there are multiple Sass maps, following the design token approach it's broken down into four distinct areas

Global
Alias
Components
Blocks

Global

Global tokens are sets of tokens that are the core to the system. Color pallettes, font sizing, font weight, spacing, etc. Each token in the global tokens map is output as a CSS Variable prefixed with --global-.

$global: (
	"gray-50": rgb(218 218 218)
);

is then converted into the following CSS

:root {
	--global-gray-50: rgb(218 218 218);
}

Alias

Alias tokens are technically still global tokens, but provide the ability to have a friendly name attached to a given global token. For example, primary-color would be an alias token, and the value of that token would reference a global token. Each token in the alias map is output as a CSS variable - these are not prefixed at all.

$alias: (
	"primary-color": rgb(100 100 100)
);

is then converted into the following CSS

:root {
	--primary-color: rgb(100 100 100);
}

Components

Component and block tokens are a little different to the global and alias set up, as these are nested Sass maps that follow the CSS property, and value set up.

For components the nested Sass map is structured with the first key inside the map being a component name. If you remember from before there is a Sass mix that looks up the component tokens by name. Meaning the component name will need to match that which is set in the components .scss file.

$tokens: (
	components: (
		"paragraph": ()
	)
);

Then inside the paragraph map we have the ability to use CSS properties and values just as if you were writing CSS, allowing you do something like

'paragraph': (
	'font-size': 16px,
	'font-weight': bold,
),

If we bring back the code from above of how we write the Sass for the paragraph component we can see how they work together

.c-paragraph {
	@include component-properties("paragraph");
}

With the above code and the above example the generated CSS would be

.c-paragraph {
	font-size: 16px;
	font-weight: bold;
}

Obviously that's not great to use hard coded values as the value items in these maps as you loose the power of the token system. Knowing how the previous global and alias tokens are converted you can reference those as the values

'paragraph': (
	'font-size': var(--global-font-size-200),
	'font-weight': var(--global-font-weight-700),
),

this would then make use of the CSS variable in the outputting CSS as follows

:root {
	--c-paragraph-font-size: var(--global-font-size-200);
	--c-paragraph-font-weight: var(--global-font-weight-700);
}

.c-paragraph {
	font-size: var(--c-paragraph-font-size);
	font-weight: var(--c-paragraph-font-weight);
}

Blocks

The blocks part of the theme works in a similar way to components the @include block-properties('promo'); Sass mixing does pretty much the same as the component-properties version, the only difference is it's looking for the named item within the blocks map.

$tokens: (
	blocks: (
		"promo": ()
	)
);

The added ability you have within a block is the ability to change the style of a component differently to that of the base components styling. As we mentioned before blocks are composed of components, this means by default and using the CSS cascade all components will have the same styling when used within a block. But what if you want to make the paragraph component within the promo block to be styled slightly different? Say we wanted to increase the font-size thats where the Sass mixin @include block-components('promo'); comes in.

Given we have the need to update the paragraph font size within a promo block the blocks map has the ability for us to define component styles for a given block.

$tokens: (
	blocks: (
		'promo: (
			'components': (
				'paragraph': (
					'font-size': 18px,
				),
			),
		),
	),
);

To break down the nested map it can be a little easier read from the inside out. What the map is saying is for the paragraph component inside a block set the font-size to 18px. How this is translated to CSS is by using the power of CSS variables, as previously mentioned we are outputting to CSS variables at all times meaning that we are able redfined the paragraph font size CSS variable within the promo block CSS.

Reminder of how the block Sass file is

.b-promo {
	@include block-components("promo");

	@include block-properties("promo");
}

Based on the above example of setting the paragraph font-size to 18px within a promo block the CSS would be output as

.b-promo {
	--c-paragraph-font-size: 18px;
}

Working Examples

Code is available on GitHub - Theme Component Repo

It's all demo'd via storybook which is published - Theme Components Storybook

JAMStack URL Shortener with Netlify, 11ty and GitHub

2021-02-07T00:00:00Z

Why...

I wanted a place where I can "bookmark" things I come across on the internet. Either for reading later, sharing or to keep a record of it for future reference.

For the sharing part I wanted to a way to use a shortened style link

Also, I want to own all this data. Along with not having to maintain a web application.

What if I could do all this with static site generation tool 11ty, and Netlify?

How...

Well turns out it's very possible, and much easier than you might think.

Broken down into the following parts

Netlify to host the site and handle the URL redirection
Eleventy to handle the website output and redirect file
GitHub issues as a UI to add items
GitHub actions to handle adding the content from the issue to the site

And the output of all this is my own URL shortner/bookmark "application" - https://roach.link

Netlfiy

For the Netlify part it's very straight forward. The provide a way to host a site, and also a mechanism for handling redirects. Setting up a site is pretty straight forward from their UI with a few customisable options. For the redirect part as long as you have a _redirects file in the directory you want to serve your site from they take care of the rest. The also allow you have use a netlify.toml file.

Eleventy (11ty)

For the 11ty part I went for a very similar set up to my personal site (this site) set up. Each link would be a markdown file inside a posts directory that looks like this

---
title: "Matthew Roach"
date: "2021-01-24"
permalink: "b/view/"
link: "https://matthewroach.me"
tags: ["personal", "blog"]
---

Personal website of Matthew Roach

The frontmatter data is where the majority of the needed data is housed. You may notice the permalink seems a little odd why is it b/view? The b part is the URL shortner unique ID, and the view part is used to build the output for each post to be roach.link/b/view allowing you to view the individual bookmark item (single view page still work in progress).

Hang on.. You said unique ID... That's going to be fun to maintain I hear you ask. Well it would be if you were trying to do it by hand. But I am not, I am using an npm package called bijective-link-shortener to increment them each time. Which is handled with GitHub as you'll see later.

Redirect file

Without the ability to do redirection a URL shortner isn't much use, and as previously mentioned Netlfiy allows you to do redirects if you provide either a _redirects or netlify.toml file in the root of the published site. And with 11ty this is made super simple to generate, as with 11ty you can configure it to output the input file to any output file (give or take), by setting the permalink to be the output.

Given all the bookmarks are all going to be individual files in a folder I set up a new collection in the .eleventy.js config file named allLinks and reversed the collection so the newest would come first.

With a file named _redirects.11ty.js in my src directory I can consume the allLinks collection and make 11ty render out the links in a format needed for Netlify. The _redirects.11ty.js looks as follows

class Redirects {
	data() {
		return {
			permalink: "netlify.toml",
		};
	}

	render(data) {
		return data.collections.allLinks
			.map(
				(l) =>
					`
[[redirects]]
	from = "${l.url.split("/")[1]}" // permalink is in format {shortLink}/view
	to = "${l.data.link}"`
			)
			.join("");
	}
}

module.exports = Redirects;

Broken down the file is looping over the allLinks collection, and setting up the Netlify redirect file in the format they require by using the permalink data (first part) and the link from each posts frontmatter data. As as the permalink of this file is set to netlify.toml it will create that file based on the render method.

The output file looks as follows

[[redirects]]
	from = "b"
	to = "https://matthewroach.me"

GitHub

GitHub is where I am hosted the source code and then have Netlify linked to the repo to build the site and publish on each commit to the main branch.

Issues

But GitHub is also the primary way I add new data to the site. Rather than having to create a new file and fill in all the frontmater data, and do a host of git commands I wanted a way I could actually use this "application" with minimal effort. Turns out GitHub issues is a ~~great~~ perfectly acceptable way to be the UI for adding new bookmarks... That is if you are willing to make a small adjustment.

So, GitHub issues provides all but one of the interface items I needed. This is how I mapped the GitHub issue UI to the frontmatter data

Issue Comment = The post body
Labels = Tags
Title = Title and link

Title = title and link? That seems odd. Well turns out the issue UI doesn't really have a field or place I could enter the URL for the item I want to bookmark. So I went with the format of making the title as follows:

Matthew Roach Blog::https://matthewroach.me

The two colons has no meaning other than for when the GitHub action runs and splits the title using title.split('::') to parse it into two parts. The first part is the Title of the Site, and the second is then used in the link frontmatter data field.

Actions

GitHub actions is the glue that makes all the previous steps work together. Without actions the process of adding bookmarks would be very manual. Actions are a way for you to automate workflows from your GitHub repository. Based on an action you can configure an action to run and do "things". Those "things" are what makes this all possible.

As mentioned I am using GitHub issues as a UI to add new bookmarks. Broken down this works as follows

Issue
1. Add a new issue to my roach.link repository
2. Once I am happy with the description and tags
3. Mark the issue as closed
GitHub action runs on issue closed event
1. The action is triggered and starts its "steps"
2. Action checks out code, sets up node and makes the issue object available on an environment variable
3. Then a node command runs a script node new-item-from-issue.js 1. Within the script I have access to the issue object by doing JSON.parse(process.env.ISSUE_CONTEXT) 2. Script checks how many posts are currently in the posts folder, and using the package bijective-link-shortener gets the next short link value 3. Using the data from the issue object and the short link value from the previous step I use transformAndWriteToFile from the package json-to-frontmatter-markdown to create a new markdown file in the format noted above
4. Add and commit is then run from within the action to add the newly created file to the repo
Netlify is triggered due to a new commit on the main branch
1. Netlify runs its build steps I have configured
New version of site is live at https://roach.link
1. Homepage is updated
2. New redirect added - example: https://roach.link/b

VSCode focus between terminal and code

2021-01-30T00:00:00Z

I recently began to utilise the integrated terminal for VSCode more. And being a big fan of using my keyboard to switch around different parts is huge part of my work flows. One of my sticking points with the terminal in VSCode is by default you can not switch into and out of the terminal easily.

For example if I am editing some code, then need to switch to the terminal to run some commands, and then switch back to the code window. I got so used to using command + tab to switch windows. Wanting to try and use VSCode more it turns out this was a sticking point of my flow. With some digging and trial and error it turns out you can setting up a custom keybinding to handle this.

As there was already a default key binding to open a terminal, once opened you can not easily switch back. But with VSCode and key bindings you are able to use the when key to tell a key binding "when" something can be run. This allowed me to set the same key binding used to focus terminal as to focus back to the editor. Below is instructions and the key binding JSON to achieve this on a Mac.

Instructions for Mac

Code > Preferences > Keyboard Shortcuts
This opens a GUI for keyboard shortcuts - click on the tab "Keyboard Shortcuts", and an icon with a file and arrow will appear (title - Open Keyboard Shortcuts JSON)
Copy paste the below JSON into the file and save
Done

[
	{
		"key": "ctrl+`",
		"command": "workbench.action.terminal.focus"
	},
	{
		"key": "ctrl+`",
		"command": "workbench.action.focusActiveEditorGroup",
		"when": "terminalFocus"
	}
]

Another VSCode tip - VSCode zoom only font not whole editor.