We’ve all been there… We set up a new AWS account and new we have an MFA token and password to deal with. Do we use a physical security token (single point of failure)? If so where do we store it so that it’s accessible? If you have a 24×7 staffed NOC with a vault, this is a simple solve, but most places don’t have that. Especially in the SMB and startup spaces. So we go to a virtual MFA device. And now only one person has that on their phone (single point of failure again) or we need to share the key out (hacky) or store in in a vault of some kind (at least these are digital).

Well, here is one approach that I’ve actually used several times with surprising success. It has also withstood many audits. Does that mean it’s perfect? No. But it is an effective method, even it it’s a bit out there.

Prerequisites

1. An email provider that supports distribution lists. Ideally one that lets you manage those memberships dynamically based on security groups. I use Azure Entre (Active Directory) and Exchange Online (all via Office365) for this.

2. A place to securely store OTP keys, ideally tied to the same security group management tool as the email distribution lists. I like to use Bitwarden for this, but Hashicorp Vault and other tools support this as well.

Initial Setup

For every AWS account you create, you will use the DL as the email address for the account. Your root account might be DL-AWS-Root@example.com while your shared dev account might be DL-AWS-Dev@example.com. Naming things is hard, but defining this namespace early and trying to stick with it is important to your long-term sanity as accounts sprawl. What do you use for the password? The longest string of random characters that your password generator of choice will spit out, and that AWS will accept. I believe that that is currently 64 characters. Copy it to your clipboard, use it to log in, then overwrite your clipboard. You never want to remember it. Just get rid of it. It never existed. Poof! It’s gone forever into the ether…

Now bootstrap your account as normal, add your support plan if you want one, setting up any core roles that you need to assume that aren’t part of your account factory, and finally, set up your MFA token for the root account. Store that token in your vault, and control access to it. Now that the bootstrapping is complete, log out. And make sure that root password is gone, never to be a thorn in your side again. Beautiful isn’t it?

But how do I log back in?

Only certain people should ever use the root account. Generally, it’s a break glass kind of thing, and you want everyone to know it’s happening. Thankfully, you have an email distribution list set up for your password reset process. So any time someone tries to reset the password to log in, everyone on the list will know about the attempt. You also still have your second factor in a separate system. Then the individual logs in, and resets the password to another completely random string of 64 characters and purposely doesn’t remember it.

Problems with this approach

Though this approach is a bit out there, it does work, and it stands up to many security policies and controls frameworks. It’s still not perfect though.

• It relies on the people in the process to not save the new password. This can be mitigated by creating alerts for whenever the root account is accessed, which is already a best practice.

• It creates reliance on other systems, email and a vault, which have other administrators and attack surfaces. Granted, we have reliance on those systems anyway, but it’s still an extra hop. In a break glass scenario, we want fast access. We don’t want to wait for an email to go through.

• Though the OTP key is stored in a separate system, access to it is typically controlled by the same authentication and authorization framework. This doesn’t have to be the case, but it does dramatically reduce operational burden.

• It’s very counter-intuitive. We want to store important credentials, not forget them! As a result, this can take some time to work through the approvals process.

• Now that AWS supports Passkeys, you could also store those in a vault instead, though there may be issues with that approach that I am not aware of. This approach might be worth diving into, though. Especially since Bitwarden and the like supports passkey storage as well.

Wrapping up

Well, there it is. A surprisingly scaleable pattern for handling root credentials and tokens in a simple or complex AWS environment. What do you think? Is this approach out there? What other issues do you see with it? How do you manage your root credentials, and what issues do you have with your approach?

Components of a Pipe

Pipes, fundamentally, are very simple: they are a service that connects a source to a destination, allowing you to optionally filter and enrich the data as it flows through. It's built in a way that lets you compose items together easily, and add custom code where you need to. The real nice bit here is how many services it supports, from Kinesis Sources to destinations like API Gateway, EventBridge, and many things in between, Pipes can really simplify interconnections. New service are being added, so for an update list or sources and targets, see the AWS Documentation site.

Example Scenario

Let's take the following example: We have an existing Events API that collects event data from many external sources (web apps, mobile apps, etc). The API pushes to a Kinesis Stream to be handled by a series of backend processes. We want to tap that stream and push the events in it to an internal Event Bridge without disrupting the existing architecture so that we can generate metrics and further react to events dynamically.

Other Options

If we were able to change everything or build a new system from scratch, we could just leverage API Gateway's native capability to push directly to EventBridge (this is a great pattern, btw). However that is a lot of change, and in this scenario, we aren't allowed to disrupt things to that degree.

Before Pipes, you would likely attach Lambda to the existing Kinesis Stream and have it push messages to the target EventBridge Bus. This is a completely valid approach, but does have some complexities involved.

Enter AWS Pipes

Instead, let's use pipes to tap that stream and get our events to EventBridge completely serverlessly. And since we like IAC (and a challenge), let's do it in CDK with Typescript... Why? Well, that's what I use at work. Let me preface all of this by saying I'm relatively new to Typescript, so please let me know where I can improve the code.

CDK makes building infrastructure in AWS much simpler. There are many built in constructs that make common patterns available with a simple instantiation, and it enforces best practices like least-privilege out of the box. Check out the API Docs for more if you're not familiar. Unfortunately, Pipes is so new, that the support in CDK is limited... As of this writing, there are Alpha Packages (enrichments, sources, targets) that have the basics in place, and we can build the missing pieces on top of it.

Custom CDK Pipe Source

Lets start where all things begin; the source. There is an example SQS Source, and the documentation mentions how to create a source implementation, so let's dive in...

import * as cdk from "aws-cdk-lib";

/**
 * A Kinesis source for EventBridge Pipes
 *
 * @param stream The Kinesis stream to use as the source
 * @param kinesisStreamParameters The parameters for the Kinesis stream. Starting Position defaults to LATEST
 */
class KinesisSource implements pipes.ISource {
  sourceArn: string;
  sourceParameters: pipes.SourceParameters = {
    kinesisStreamParameters: {
      startingPosition: "LATEST", // I like sane defaults
    },
  };

  constructor(
    private readonly stream: kinesis.IStream,
    kinesisStreamParameters?: cdk.aws_pipes.CfnPipe.PipeSourceKinesisStreamParametersProperty
  ) {
    this.stream = stream;
    this.sourceArn = stream.streamArn;
    if (kinesisStreamParameters) {
      this.sourceParameters = { kinesisStreamParameters };
    }
  }
  // eslint-disable-next-line
  bind(_pipe: pipes.IPipe): pipes.SourceConfig {
    return {
      sourceParameters: this.sourceParameters,
    };
  }

  grantRead(pipeRole: cdk.aws_iam.IRole): void {
    this.stream.grantRead(pipeRole);
  }
}

This source uses the existing CfnPipe primitives to handle the properties, which makes the implementation relatively easy. There is only one required parameter, and that is the Starting Position. I assumed LATEST as a sane default, but this object allows us to override as needed.

Custom CDK Pipe Target

Just like the Source, we need a target.

import * as cdk from "aws-cdk-lib";

/**
 * An EventBridge target for EventBridge Pipes
 *
 * @param targetEventBridge The EventBridge event bus to use as the target
 * @param inputTransformation The input transformation to apply to the event
 */
class EventBridgeTarget implements pipes.ITarget {
  targetArn: string;
  private inputTransformation: pipes.InputTransformation | undefined;
  private targetParameters: cdk.aws_pipes.CfnPipe.PipeTargetEventBridgeEventBusParametersProperty | undefined;

  constructor(
    private readonly targetEventBridge: events.IEventBus,
    props: {
      inputTransformation?: pipes.InputTransformation;
      targetConfig?: CfnPipe.PipeTargetEventBridgeEventBusParametersProperty;
    } = {}
  ) {
    this.targetEventBridge = targetEventBridge;
    this.targetArn = targetEventBridge.eventBusArn;
    this.inputTransformation = props?.inputTransformation;
    this.targetParameters = props?.targetConfig;
  }

  bind(_pipe: pipes.Pipe): pipes.TargetConfig {
    return {
      targetParameters: {
        inputTemplate: this.inputTransformation?.bind(_pipe).inputTemplate,
        eventBridgeEventBusParameters: this.targetParameters,
      },
    };
  }

  grantPush(pipeRole: cdk.aws_iam.IRole): void {
    this.targetEventBridge.grantPutEventsTo(pipeRole);
  }
}

Again, we're leveraging the primitives from the underlying CDK alpha to generate our target. Targets support more options, so I handled them a little differently here. Note the bind function, where I return a targetParameters object. That is what corresponds to the CloudFormation target parameters object which is complex and is used by all pipe targets. I'm sure there's a nicer abstraction that could be used here, but I was more focused on getting it up and running that writing the next alpha target.

Using Our New Constructs

Using the above constructs, we are able to use the existing pipe from the alpha library to get a working pipe!

    // EventsMetricsBus is ppublic on the construct so that other stacks
    // can reference it for adding rules easily. 
    this.EventsMetricsBus = new events.EventBus(this, `${prefix}-eventBus`, {
      eventBusName: `${prefix}-eventBus`,
    });

    const sourceEventStream = kinesis.Stream.fromStreamArn(this, `${prefix}-sourceEventStream`, kinesisStreamArn);

    new eventsSchemas.CfnDiscoverer(this, `${prefix}-discoverer`, {
      sourceArn: this.EventsMetricsBus.eventBusArn,
      description: "Discoverer for event metrics bus",
    });

    const base64InputTransformer = pipes.InputTransformation.fromText(
      '{ "kinesisWrappedEvent": <$.data>, "originalEvent" : <aws.pipes.event> }'
    );

    const kinesisToEventBridgePipe = new pipes.Pipe(this, `${prefix}-kinesisToEventBridgePipe`, {
      pipeName: `${prefix}-kinesisToEventBridgePipe`,
      source: new KinesisSource(sourceEventStream),
      target: new EventBridgeTarget(this.EventsMetricsBus, {
        inputTransformation: base64InputTransformer,
        targetConfig: {
          source: sourceName,
          detailType: "$.partitionKey", // This will always be here as it is the partition key of the Kinesis record itself
        },
      }),
      logIncludeExecutionData: [pipes.IncludeExecutionData.ALL],
      logLevel: pipes.LogLevel.ERROR,
    });

Some notes on the above code...

• Killer Feature: The Input Transformer uses a feature of Pipes called Implicit Body Data Parsing. The Kinesis event data is base64 encoded. Pipes will automatically decode it and make it available. This means you can set your input for the EventBridge Bus to the decoded data, allowing for simple filtering. No enrichment required!

  • This would let us set the input to pipes to just be <$.data> and it would essentially keep our data the same as it was when it came into the API, completely hiding the plumbing of kinesis. I really like this for downstream developer clarity.

• I like to use ${prefix} in my CDK stacks. It allows for standard naming of resources throughout the stack.

• Using the source is easy. I pass in a kinesis stream from another stack and use it as the source of our KinesisSource.

• Killer Feature: The target config supports the same JSON path syntax as the Input Transformer! So we are able to take anything from the object and use it as the detail-type! See Dynamic Path Parameters in the docs. In this instance, our API Gateway sets the partition key to the event type, so our downstream events are now the same as the event name coming in to the API.

Conclusion

With these pieces in place, we have reached our goal! We can now react to our API Gateway events dynamically in our new EventBridge Bus. In our instance, we wanted to generate metrics on all the events in our system. This approach lets us do so cleanly, and without touching our existing process. As a bonus, we also got schema discovery of our events, which helped our team stay in sync to changes over time to our inbound events.

Thanks

Many thanks to my seniors who encoruaged me and provided guidance through this project (Alex, Brandon, and Matt, you guys are the best)!

The Material Safety Data Sheet for DampRid has the answer! The miracle crystals are primarily... Calcium Chloride... Basically, de-icing salt. The same de-icing salt that you can buy at big box stores in the winter for $1/lb or less.

I'm aware that I don't need to go big or go home. After all, the 4 lb bucket is good for 1,000 square feet, according to the manufacturer. Though I argue that they don't work quite that well due to air flow and all that, a couple of the smaller ones would probably work fine for a simple sailboat. So why look at rolling your own? Well, I like the idea of a larger reservoir. When I used the commercial ones, they would fill up quickly and needed to be checked every week or two. Although I like to think I will get to the boat frequently, I know that reality is often different. Plus, I like to tinker. So here's what I came up with...

Super Ultra Mega DampRid Alternative

Or SUMDRA, for short. Really rolls of the tongue, right? 😅 It's simply a 5 gallon bucket with a mesh sieve on top to hold the ice melt. This lets the user put in as much ice melt as they want, and have a large reservoir to catch all the moisture.

For this build, I used a Home Depot bucket (about $5) and a 600 micron plastic mesh ($27!!!) designed for 5 gallon bucket. Yes, the mesh was expensive. I couldn't find anything plastic that had fine enough holes for the small salt crystals. Next time, I might try cheese cloth or similar in a regular plastic colander, but for now, this is it. Just remember, these crystals are highly corrosive, so make sure whatever you get is plastic. I wouldn't even trust stainless in this situation.

As for the salt itself, the key is to look for one that is mostly Calcium Chloride. Normally, this wouldn't be a problem. However, right now we're in the middle of a heat wave and most stores don't stock ice melt in the summer. You should have seen the look on the guy's face when I asked...

Thankfully, in many cases, you can order it and have it shipped to the store for free. Use their websites to check availability and ingredients, but call ahead to confirm availability if they say there are some in stock. I know it may come as a surprise, but the internet lies, and availability is often mis-reported. I settled on Snow Joe 20 lb. 94% Pure Calcium Chloride Ice Melt Pellets. Be sure to read the details! One of the larger bags from the same manufacturer had a very similar label, but was mostly Sodium Chloride.

Results

So, how does it work? I have no idea! It's the middle of summer, and I'm waiting on my ice melt to get delivered. 😆 It should be in next week. I plan on throwing it in the bucket and moving everything to the boat after that. So stay tuned for updates!

Airflow

Unfortunately, the docks at the lake do not have power, so I will have to rely on passive ventilation for now. My plan is to get a Marinco Solar Powered Vent Fan to install in the front hatch. In order to ensure good flow, I'm considering adding a 4" stainless vent to the companionway door, but I want to confirm with someone more knowledgeable that that isn't a bad idea.

Additionally, for the winter, I plan on adding a dehumidifier to run 24/7, with a condensate pump to get all the water out of the boat. I just need to figure out a good way to get the hose out of the main compartment without letting more water in.

Cleaning

There will be a lot of cleaning involved. This boat seems to have sat closed for at least a season. I pulled all the soft goods out and it looks like the vinyl cabin cushions are salvageable. The others can likely be saved for a season or two, but ultimately I want to replace them.

For the interior cushions (corduroy & vinyl), I used a combination of vinegar, detergent, and OxiClean to de-mold and freshen them. I tried this on some throw pillows that were in the cabin and it worked perfectly, so I think it will work well on the larger covers as well. For the foam, I plan to use diluted vinegar and lots of sunshine to try and freshen them.

The exterior cushions are covered in vinyl. I did try a vinyl cleaner on them, but it wouldn't get out the stains from the mold/mildew, so I decided to use some bleach spray on them. I know this is generally not a thing you want to do to vinyl, but I think it is worth it once to establish a baseline. I did try this on one cushion and it had no negative effects and got most of the staining out. After this, I will stick to vinyl cleaner.

Replace the Mast Step

Thankfully, the mast step is a fairly inexpensive part. I ordered it from Catalina Direct as well as new bolts and sealant. They should get here in a week or two. I also got some flexible marine butyl tape and may end up using either or both. Still trying to decide. All in, it's 'bout another hundred...

What else?

Again, I'm far from an expert here. I joined and reached out to The Nockamixon Sail Club to see if anyone with experience would be willing to come by and do a once-over on the boat with me to see what I missed. Hopefully someone will volunteer. I've offered bribes in the form of Pastured Poultry and unskilled/skilled labor.

The Boat

I came across an ad on Facebook Marketplace for a 1988 Catalina Capri 22 sailboat with a wing keel, roller-furler, and gps/fish finder, and some other extras. Catalina makes solid boats, and the capri is one of them. This particular boat was about a half hour away right next to Lake Nockamixon, which was where I have a dry slip waiting, and needed a little bit of love. Her mast step got bent in an unfortunate accident, but everything else seemed to be in good condition... aside from that "classic" boat smell of course. So after a brief inspection, we agreed on a price and I bought her and brought her home. Her name is Cykada (for now), and she's now dry-docked on my RV pad.

The Immediate Plan

All great dreams start with a plan, so here is mine.

1. Get everything out of the boat that isn't bolted down ✅

2. Clean the ever-loving daylights out of it

3. Address airflow & moisture to prevent new mold issues

4. Replace the mast step

5. Figure out what other things she needs to be ready for actual sailing

That's it! At least, for now. I spent the evening yesterday getting all the generic stuff inside the boat out and sorted. She's spending today open with a fan trying to dry her out as much as possible. All the soft goods are out in the sun to see if there is any hope of saving some of them. This evening I'll be bringing the wet/dry shop vac up to get rid of any remaining standing water.

Mid-range Plans

The immediate goal is to get her into good enough condition to get on the lake this season. Once I actually start sailing, I'm sure I'll find countless things I want to add and tweak. On my radar, in no particular order, are the following:

• Solar Fan - This is probably part of the short term plan, but it's important enough to list twice. Airflow prevents mold. I want airflow. Interestingly, in order for air to flow, it needs an inlet... and the boat doesn't currently have one that I can tell. So part of this will be adding some kind of inlet.

• Remote Monitoring - I love to tinker, and this is a great excuse to mix my Home Automation and Embedded Controls hobbies with water. I think remote temp/humidity and location tracking are immediate goals for this little side project, but with Open Source projects like OpenPlotter, the sky is the limit.

• Electrical Upgrade - The boat has a new battery, but the panel and most of the wiring is original. I think I want to add a quick disconnect on the battery (Anderson style connector), as well as add a solar charger / battery maintainer. After that, replacing the panel (modern chargers instead of cigarette style ones), lights (LEDs please), and maybe even adding more charge ports around.

• New Cushions - I know next to nothing about sewing, so this would likely involve a lot of bribes to my lovely wife. The existing cushions are quite literally falling apart, and are full of mold. We could try to salvage them, but replacement is probably the way.

• Bottom Paint - This is more like general maintenance, but the bottom could definitely use a new coat of paint. When I do this, I'll likely increase the scope to include any repairs needed for the gelcoat and fiberglass.

Long-range Plans

• Cruising Vacations - If this lifestyle suits me and the family, there will be many trips to tropical locals to do more sailing on larger boats. My dream is to sail the world, but it takes baby steps to get there when you've got a family that you love.

• Get a Bigger Boat - This is a great boat for Lake Nockamixon, but it's not a great boat for multi-day cruises or vacations. Getting a bigger boat would unlock more aspects of sailing, and might even add a "beach house" to the vacation options. Only time will tell

Closing Thoughts

Though I sailed a bit as a kid, I'm very much new to the boating lifestyle. If you have any thoughts, suggestions, or comments, please reach out and let me know. Going forward, I'm going to document the work on the boat here in the hopes of helping others who are interested see that this is a somewhat accessible hobby as long as you are willing to work at it.

Zigbee2mqtt docker-compose.yaml

version: '3.8'
services:
  zigbee2mqtt:
    restart: unless-stopped
    image: koenkk/zigbee2mqtt
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    environment:
      - TZ=America/New_York
    devices:
      - '/dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2400118-if00:/dev/ttyACM0'
    labels:
      - "traefik.http.routers.zigbee2mqtt.rule=Host(`zigbee2mqtt.internal.murawsky.net`)"
      - "traefik.http.services.zigbee2mqtt.loadbalancer.server.port=8080"
    networks:
      - web

networks:
  web:
    external: true

zwavejs2mqtt docker-compose.yaml

version: "3.7"
services:
  zwavejs2mqtt:
    container_name: zwavejsui
    image: zwavejs/zwave-js-ui:latest
    restart: unless-stopped
    tty: true
    stop_signal: SIGINT
    environment:
      - ZWAVEJS_EXTERNAL_CONFIG=/usr/src/app/store/.config-db
      - TZ=America/New_York
    env_file:
      - ./secrets.env
    devices:
      # Do not use /dev/ttyUSBX serial devices, as those mappings can change over time.
      # Instead, use the /dev/serial/by-id/X serial device for your Z-Wave stick.
      - '/dev/serial/by-id/usb-Silicon_Labs_Zooz_ZST10_700_Z-Wave_Stick_0001-if00-port0:/dev/zwave'
    volumes:
      - zwave-config:/usr/src/app/store
    ports:
      - "3000:3000" # port for Z-Wave JS websocket server
    labels:
      - "traefik.http.routers.zwavejs2mqtt.rule=Host(`zwavejs2mqtt.internal.murawsky.net`)"
      - "traefik.http.services.zwavejs2mqtt.loadbalancer.server.port=8091"
    networks:
      - web

networks:
  web:
    external: true

volumes:
  zwave-config:
    name: zwave-config

Traefik docker-compose.yaml

Both services exist behind the traefik reverse proxy, also running via docker.

version: '3'
services:
  reverse-proxy:
    # The official v2 Traefik docker image
    image: traefik:v2.8
    restart: unless-stopped
    # Enables the web UI and tells Traefik to listen to docker
    # --serverstransport.insecureskipverify=true
    command: --api.insecure=true --providers.docker --metrics.prometheus=true
    ports:
      # The HTTP port
      - "80:80"
      # The Web UI (enabled by --api.insecure=true)
      - "8080:8080"
    volumes:
      # So that Traefik can listen to the Docker events
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - web

networks:
  web:
    external: true

Closing Thoughts

Better late than never! 😆 This system has worked very well with almost no hiccups at all. It integrated easily with Home Assistant as well.

The Opportunity

Here's the opportunity: my kitchen as it stands now... It's a bare canvas! With everything open like this, and new fixtures being selected, it's the perfect time to add a serious dose of control-ability into my home.

Goals

My goals for this project are fairly simple: I want a device that can bridge my Zigbee and Z-Wave devices to Home Assistant via MQTT. I want it to be stable, relatively secure, and easy to maintain. Now, just because the goals are simple, doesn't mean the implementation will be... Because, to me, stability and ease of maintenance means putting it in Docker containers... And that brings some complexity with it.

Further, I want this to be a stable platform that I can build on over time. My kids love RGB LEDs and other cool tech, so having a reliable home control network is important to nurture that love going forward.

Devices

What devices do I want to support, exactly? Here's a list, with handy Amazon links. They're not affiliate links yet, though. I'm not sure if I want to get into that whole world or not, yet.

• Aeotec Multisensor 6 - A Z-Wave multisensor for motion, temperature, humidity, light, UV, and vibration sensing. For outdoor entry ways (protected areas).
• Aqara motion sensor - A fantastic, tiny little motion sensor. For discrete interior motion detection.
• Conbee 2 - A Zigbee controller USB stick to interface with the Zigbee network from a Raspberry Pi.
• S2 Stick 700 - A Z-Wave controller USB stick to interface with the Z-Wave network from a Raspberry Pi.
• Zooz ZEN72 - A Z-Wave dimmer switch to control all new and existing light fixtures.
• Zooz ZEN32 - A Z-Wave switch with one switch button and four scene buttons to control outdoor lights and provide convenient scene selection capabilities for the entire first floor.
• Zooz ZSE40 - A Z-Wave motion/light/temp/humidity sensor for interior entry ways to detect a person coming into the home.

More to come

In the next post in this series, I'll dive in and configure docker and zwavejs2mqtt on an old Raspberry Pi 3 that I had lying around. I don't have controllable devices installed, yet, but I can at least start getting some signal data.

• Set up Oh my Zsh
• Install a NerdFont
• Set up Starship

In terms of terminal emulators, I like the good old reliable iTerm2. If you don't already have it, you can install it easily with homebrew brew install --cask iterm2.

Set up Oh My Zsh

Oh my Zsh has a scripted installer available, so it's really simple to get it installed. Open up iTerm2 and run sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" Note: You should definitely check the install script before running it!

Great we're installed! But, what's this? Some of my old installed apps aren't working (like NVM)? Oh My Zsh overwrites your ~/.zshrc file, so you will have to edit it to add your missing configuration back in. Your original config was backed up by the installer to ~/.zshrc.pre-oh-my-zsh. While you're editing your ~/.zshrc, it's also a good idea to read through all the new options that were added. Once you're done with your edits, restart your terminal and you're off!

Finally, if you ever want to uninstall Oh My Zsh, just run uninstall_oh_my_zsh from your terminal. It will reset your old ~/.zshrc file, too.

Plugins

One of the big reasons I like Oh My Zsh is their absolutely massive list of plugins. It's easy to enable too many and forget what you even have loaded (and slow down your shell as well!). The ones I use are aliases, aws, git, macos, npm & nvm. If I dive into specific areas, like docker/k8s, I'll add additional plugins as needed and then remove them when I'm done.

Install a NerdFont

Next up is installing a NerdFont. What is a NerdFont? From the website:

Nerd Fonts patches developer targeted fonts with a high number of glyphs (icons). Specifically to add a high number of extra glyphs from popular ‘iconic fonts’ such as Font Awesome, Devicons, Octicons, and others.

Essentially, this means you get a font library with a ton of extras that you can use in the console, or anywhere else. So head over to the download area and grab a font that you like. I like FiraCode. And since I have brew, I install it with brew tap homebrew/cask-fonts && brew install --cask font-<FONT NAME>-nerd-font.

And, yes, you may need to figure out the font name... Next time, remember, you can search with brew search --casks <PART OF FONT NAME> to take the guesswork out.

To use the font as your primary in your terminal, open the profiles editor, edit your default profile, and select the NerdFont you downloaded.

Install StarShip

The last thing to do is set up StarShip, a fast cross-shell prompt written in rust. Using homebrew, the install couldn't be simpler. Just brew install starship.

Once installed, you can echo 'eval "$(starship init zsh)"' >> ~/.zshrc to get it to load in your shell every time. Now we have a great prompt, with useful feedback and near infinite customizability. Here is an example of the default when you're in a node project (CDK app in this case). And if you're curious about anything in your prompt, a quick starship explain will give you some really useful information.

image.png

Other Customizations

There are a lot of other little extras that I add in, but the basics are above. I'm a fan of the setup used in the examples of StarShip.

• zsh-autosuggestions - For some nice autosuggestion display functionality.
• zsh-syntax-highlighting - for those long, complicated command lines with lots of escapes and special characters.
• iterm2-snazzy - For a nice color scheme in iTerm2.

Conventional Commits

When it comes to commit messages, there are many opinions on what makes a good one and why. Most folks will agree, though, that a simple one line commit is far from ideal. I've adopted the Conventional Commits standard with a required body that describes why I made a change, rather than just describing the change I made. Thank you Chris Beams for that idea. Here's the standard message format in a nutshell, pulled from the Conventional Commits summary:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The commit contains the following structural elements, to communicate intent to the consumers of your library:

1. fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
2. feat: a commit of the type feat introduces a new feature to the codebase (this ?>correlates with MINOR in Semantic Versioning).
3. BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
4. types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others.
5. footers other than BREAKING CHANGE: may be provided and follow a convention similar to git trailer format.

Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE). A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays.

Benefits

This approach has many advantages when working with a team or on a complex project.

Firstly, when something breaks it is easy to not only find our who made a change but also why they made the change. That context can be invaluable, and you no longer have to break your flow to go look up an old ticket reference that's hopfully still valid. Couple that message with a tool like GitLens, which lets you quickly and easily see git commit messages in your IDE, and your flow is even cleaner.

Next up, this aligns beautifully with Semantic Versioning and allows for more automation around releases and version numbering. Fixes map to patches. Features map to minor increments. Breaking changes map to major. There is even some good automation already built to support this not only in your release flow, but also in your pre-commit stage. This post from jsilvax over on Medium goes into this in more detail.

Finally, ticketting systems change. While you may have kept your issues in GitHub Issues, your organization may want to move to Jira. I would hope the teams in charge of that would migrate your issues over, but do you want to rely on that? It is my opinion that the why of your changes should live with your code, in you git commit messages. As long as you keep git as your VCS, these messages will always remain.

Architectural Decision Records (ADRs)

But can the context of all changes be clearly conveyed in a commit message? What if the change is part of a larger decision made by the team? Enter Architectural Decision Records (ADRs). ADRs are a way to capture the Architecturally significant decisions made as part of a projects evolution. There are many formats, but the key is to capture what decision was made, why it was made, and who agreed to it. In addition, I like to capture the other options that were considered and why the final choice was made. I'm a fan of Markdown Any Decision Records for their flexibility and relative completeness.

By putting your ADRs in a subdirectory of your documentation, it becomes easy to reference as things move forward. Keeping this close to your code, instead of a separate system like Confluence, has many of the same advantages as those listed above for conventional commits, like ease of reference from comments/commits and the fact that it will always be along side your code even if external systems change.

A bonus feature of this approach is that if you use a static site generator, your ADRs can be published along with your normal documentation. I typically use MKDocs to generate a static site from the /docs/ directory which includes ADRs. For an example, you can check out this reference repo and the static site that it generates.