BrightBot.co.uk

Verifying Your GitHub Commits with GPG or SSH

Andrew Townsend — Mon, 06 Oct 2025 20:28:52 GMT

If you’ve been following along with the previous posts on managing multiple Git identities and multiple SSH keys, this next step adds a nice layer of polish — verified commits.

You’ve probably noticed some commits on GitHub have a little “Verified” badge next to them.
That badge tells others (and your future self) that GitHub has confirmed the commit really came from you — not someone impersonating your name and email.

Let’s walk through how to set up commit signing for your personal and work Git accounts.

🧩 Why Sign Commits?

Git already tracks who made each commit, but those details (name and email) are easy to fake — they’re just text in your config.

Signing your commits adds cryptographic proof that they actually came from you.

Benefits:

✅ Verified commits on GitHub
🧠 Stronger identity assurance for open-source work
🔒 Prevents impersonation or accidental misattribution

🔐 Two Ways to Sign Commits

GitHub supports two signing methods:

GPG (GNU Privacy Guard) – traditional, widely supported
SSH signing – newer and simpler (especially if you already use SSH keys)

We’ll go through both, starting with SSH since it’s the easiest to set up.

⚙️ Option 1 – Signing Commits with SSH

If you already have SSH keys for GitHub (from Part 2), you can use them to sign commits.

1. Check your Git version

SSH commit signing requires Git 2.34+:

git --version

If it’s older, update it before continuing.

2. Tell Git to use SSH signing

Pick which key you want to use (personal or work) and set it as the signing key:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519_personal.pub
git config --global commit.gpgsign true

If you use separate identities, you can set the signing key per directory using the same includeIf setup from earlier:

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

And inside ~/.gitconfig-work:

[gpg]
    format = ssh
[user]
    signingkey = ~/.ssh/id_ed25519_work.pub

3. Add the public key to GitHub

Copy your SSH public key:

cat ~/.ssh/id_ed25519_personal.pub

Go to GitHub → Settings → SSH and GPG keys → New SSH key,
then choose "Signing Key" as the type.

Once saved, any commit signed with that SSH key will show up as Verified on GitHub.

🔑 Option 2 – Signing Commits with GPG

If you prefer GPG, or already use it for encryption, you can generate and add a GPG key instead.

1. Generate a GPG key

gpg --full-generate-key

Choose:

Key type: RSA and RSA
Key size: 4096
Expiration: up to you
Real name & email: must match your Git config

Then list your keys:

gpg --list-secret-keys --keyid-format=long

2. Set your signing key in Git

Take the long key ID (the part after sec rsa4096/) and configure Git:

git config --global user.signingkey YOURKEYID
git config --global commit.gpgsign true

3. Add your public key to GitHub

Export your public key:

gpg --armor --export YOURKEYID

Copy the output and add it at
GitHub → Settings → SSH and GPG keys → New GPG key

That’s it — your GPG-signed commits will now show as verified too.

🧠 Testing It

Make a test commit:

git commit -S -m "test signed commit"

Push it to GitHub, then open the commit in your repo — you should see:

✅ Verified

For example, when enabled on GitHub it should look like this, see previous Unverified and then subsequent Verified commit.

If you don’t, check that:

The key email matches your GitHub account email
The right key was added as a signing key
You’re not committing as a different user/SSH alias

🧩 Bonus Tip – Visual Verification

You can confirm locally that commits are signed and valid:

git log --show-signature

This will show which key signed each commit.

✅ Summary

You’ve now got:

Part 1: 🔄 Automatic author switching per directory
Part 2: 🔑 SSH key separation for multiple Git accounts
Part 3 (This post): 🪪 Verified commits on GitHub

Together, these make your Git setup more professional, secure, and organised — whether you’re working across open-source, side projects, or enterprise repos.

Managing Multiple Git SSH Keys by Directory

Andrew Townsend — Mon, 06 Oct 2025 20:07:48 GMT

In the last post, we configured Git to automatically use different user names and emails depending on the project directory.
That solved one half of the problem.

But if you use multiple Git accounts — say, one for work, one for personal projects — you’ll also need to make sure Git connects using the right SSH key for each.

Let’s fix that next.

The Problem

By default, Git uses your system-wide SSH key (typically ~/.ssh/id_rsa or ~/.ssh/id_ed25519).
If both your personal and work GitHub accounts use SSH, you can easily run into:

ERROR: Permission denied (publickey)

or worse — commits showing up under the wrong GitHub account.

The trick is to have separate SSH keys and tell your SSH client when to use which one.

🧰 Step 1 – Generate Your Keys

If you don’t already have separate keys, create them now.

# Personal key
ssh-keygen -t ed25519 -f ~/.ssh/id_rsa_personal -C "personal@example.com"

# Work key
ssh-keygen -t ed25519 -f ~/.ssh/id_rsa_work -C "work@example.com"

You’ll end up with two key pairs:

id_ed25519_personal / id_ed25519_personal.pub
id_ed25519_work / id_ed25519_work.pub

🧩 Step 2 – Add Keys to Your Git Hosts

Add each public key (.pub file) to the correct account:

Personal GitHub → Settings → SSH and GPG keys → New SSH key
Work GitHub / GitLab → Same path, different account

Give them clear names like “Laptop Personal” and “Laptop Work.”

⚙️ Step 3 – Create a Custom SSH Config

Open (or create) ~/.ssh/config and define custom host aliases for each account:

# Personal GitHub
Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_personal
    IdentitiesOnly yes

# Work GitHub
Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_work
    IdentitiesOnly yes

# Another Work Bitbucket
Host bitbucket
    HostName bitbucket.org
    User git
    IdentityFile ~/.ssh/id_rsa_work_bitbucket
    IdentitiesOnly yes

Now, instead of using git@github.com, you’ll use either:

git@github-personal
git@github-work

Each alias tells SSH which key to use. This will work for any provider, not just GitHub such as GitLab or Bitbucket etc.

🧱 Step 4 – Clone Repositories with the Right Alias

When cloning, use the correct alias:

# Personal project
git clone git@github-personal:username/personal-repo.git

# Work project
git clone git@github-work:company/work-repo.git

Git doesn’t care about the alias — it’s just an SSH shortcut that ensures the correct key gets used.

If you’ve already cloned a repo, you can edit the .git/config file inside it:

[remote "origin"]
    url = git@github-work:company/work-repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*

🧠 Step 5 – Combine with Conditional Git Configs

If you followed the previous post, you can now combine the two setups:

Use includeIf in ~/.gitconfig to pick the right author details.
Use SSH aliases in ~/.ssh/config to pick the right authentication key.

That means everything just works when you’re in the right directory — no more switching accounts manually.

🧩 Example Directory Setup

~/projects/personal/     → uses github-personal + personal identity  
~/work/                  → uses github-work + work identity

Each repo inside those folders automatically gets the right author and the right SSH key.

✅ Summary

With a few lines of config, you’ve now built a clean, automatic Git environment that handles multiple accounts seamlessly.

Benefits:

Separate identities and SSH keys per project type
No more “wrong account” commits or permission errors
Clean, organized Git and SSH setups that just work

This approach is especially useful if you:

Contribute to open-source projects with your personal account
Work for multiple clients
Keep your personal and professional Git presence strictly separated

In Part 3 we go a step further and verifying our commits providing confidence they are from trusted authors

Managing Multiple Git Authors by Directory

Andrew Townsend — Mon, 06 Oct 2025 19:44:53 GMT

If you contribute to both personal and work repositories, you’ve probably run into this:

You commit to a personal project — and realise your work email is all over it.

Or worse, you commit to a company repo using your personal identity.

Git only tracks one author configuration per system by default, but with a little setup, you can make Git automatically choose the right name and email based on the directory you’re working in.

Let’s walk through how to do it cleanly.

🧩 The Problem

By default, Git uses the global configuration you set up when you first installed it:

git config --global user.name "John Smith"
git config --global user.email "john@work.com"

That means every commit — no matter which project — will use that identity.

If you use Git for both work and personal projects, this gets messy fast.

🛠️ The Solution: Per-Directory Config

Git allows conditional includes, meaning you can load different configuration files depending on the path of your repository.

You can define separate config files for each identity and tell Git which one to use automatically based on directory.

⚙️ Step 1 – Set Your Global Config

Keep your global Git config simple — it acts as the default.

git config --global user.name "Personal Name"
git config --global user.email "personal@example.com"

Then open your global config file for editing:

nano ~/.gitconfig

You’ll see something like:

[user]
    name = Personal Name
    email = personal@example.com

⚙️ Step 2 – Add Conditional Includes

Now, let’s add rules so Git automatically uses your work identity in a specific folder, and your personal identity elsewhere.

Append this to your ~/.gitconfig:

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

[includeIf "gitdir:~/projects/personal/"]
    path = ~/.gitconfig-personal

Each includeIf rule checks the path of the repository.
If the repo lives inside ~/work/, Git will include your ~/.gitconfig-work settings.

💡 The path must end with a slash (/) to match everything inside that directory.

Step 3 – Create the Additional Config Files

Now create the two files:

~/.gitconfig-work

[user]
    name = Work Name
    email = work@example.com

~/.gitconfig-personal

[user]
    name = Personal Name
    email = personal@example.com

You can add as many of these as you need — for freelance clients, open-source accounts, or separate organisations.

🧪 Step 4 – Test It

Navigate into one of your repos and check which author Git is using:

cd ~/work/project1

git config user.name
-> Work Name

git config user.email
-> work@example.com

cd ~/projects/personal/myproject2

git config user.name
-> Personal Name

git config user.email
-> personal@example.com

You should see the correct identity based on the folder you’re in.

🧰 Bonus Tip – Verify Before You Commit

If you want a quick reminder before committing, you can add an alias to show the current identity:

git config --global alias.whoami '!git config user.name && git config user.email'

Now run:

cd ~/work/anotherproject

git whoami
Work Name

to double-check which author Git will use in the current repo.

🛠️ Fixing any previous commits

If you have accidentally committed with the wrong git author, you can always go back and alter the commit history, however note this can be a destructive process so use with caution! Where GIT_HASH is the commit just before the bad commit author you can substitute that and run the following:

git rebase -r GIT_HASH \
    --exec 'git commit --amend --no-edit --reset-author'

This will rebase ALL commits from that point resetting them against the currently configured author.

⚠️ Warning: This rewrites history — only do this on branches you control (not shared ones).

✅ Summary

With conditional includes, Git becomes smart enough to switch identities automatically based on directory.

Benefits:

No need to constantly reconfigure or remember which profile you’re using.
Prevents accidentally committing to personal projects with your work email.
Keeps your global configuration clean and simple.

It’s a small setup that saves a lot of cleanup later — especially if you juggle multiple Git identities daily.

In Part 2 we go into the next step of using separate SSH keys for multiple Git Accounts

Building a Laser Trip Sensor with a Photoelectric Sensor and ESPHome

Andrew Townsend — Sun, 05 Oct 2025 12:09:25 GMT

Presence detection is a cornerstone of home automation. Whether you want lights that automatically switch on when someone walks into a room, or smarter security alerts, presence sensors give your automations real-world context.

While PIR (motion) sensors are common, another interesting option is the photoelectric sensor. These sensors detect when an object breaks a light beam, making them great for detecting someone passing through a doorway, entering a hallway, or triggering an event when something moves past.

In this post, I’ll walk through building a simple ESPHome-based presence sensor using a photoelectric sensor, an ESP microcontroller, and Home Assistant integration.

Why Photoelectric Sensors?

Most people default to PIR sensors, but photoelectric sensors offer some nice benefits:

Directional detection – can be placed across a doorway or passage.
More reliable indoors – less prone to false triggers from heat changes.
Fast response – detects instantly when the beam is broken.
Versatile – can detect objects, not just people.

This makes them especially useful in hallways, staircases, garages, or even for counting entries/exits.

Hardware Needed

ESP8266 or ESP32 board (NodeMCU, ESP32-DevKit, etc.).
Photoelectric sensor (common 5V or 12V models, like E18-D80NK).
Relay or MOSFET (optional) if the sensor requires different power than the ESP board.
Wiring & enclosure depending on where it’s installed.

Most photoelectric sensors provide a digital output (HIGH/LOW) when the beam is broken, which makes them easy to integrate with ESPHome.

Wiring Overview

VCC of the sensor → 5V (or 12V depending on model).
GND → Common ground with ESP board.
OUT → Connect to an ESP GPIO pin (with level shifting if needed).

ESPHome Configuration

Here’s a simple YAML config to turn the sensor into a binary sensor in Home Assistant:

esphome:
  name: photo-sensor
  platform: ESP8266
  board: nodemcuv2

wifi:
  ssid: "YOUR_WIFI"
  password: "YOUR_PASSWORD"

api:
logger:
ota:

binary_sensor:
  - platform: gpio
    pin: D5
    name: "Presence Sensor"
    device_class: motion
    filters:
      - delayed_off: 500ms

✅ This setup creates a binary sensor entity in Home Assistant called Presence Sensor.
✅ delayed_off prevents flickering if the beam is quickly interrupted multiple times.

Example Automations

Once in Home Assistant, you can start building automations like:

Hallway lights: Turn on when someone walks through.
Garage alert: Send a notification when the beam is broken after hours.
Entry counting: Use two sensors side-by-side to count in/out movement.

Example automation for lights:

alias: Hallway Lights On
trigger:
  - platform: state
    entity_id: binary_sensor.presence_sensor
    to: "on"
action:
  - service: light.turn_on
    target:
      entity_id: light.hallway

Benefits of a Photoelectric Presence Sensor

Accurate – triggers only when the beam is broken.
Flexible – works for both people and objects.
DIY-friendly – simple binary sensor integration with ESPHome.
Expandable – add multiple sensors to track direction or build counters.

Conclusion

A photoelectric sensor paired with ESPHome gives you a fast, reliable way to detect presence and movement in your smart home. It’s a great alternative to PIR sensors, especially in narrow or controlled spaces like doorways, staircases, or garages.

Once integrated with Home Assistant, the possibilities are endless — from simple light automation to more advanced occupancy tracking.

Building a 4-Zone Irrigation Controller with ESPHome - Part 1

Andrew Townsend — Sat, 04 Oct 2025 20:44:38 GMT

Automating irrigation is one of those home automation projects that’s both practical and fun.

Instead of manually turning sprinklers or valves on and off, you can control watering schedules through your smart home — or even trigger watering based on weather or soil moisture sensors.

In this series, I’ll walk through building a 4-zone irrigation controller using ESPHome, some off-the-shelf components, and Home Assistant integration.

Series Overview

As I publish parts of this series I will update the links between each part for easier navigation.

Part 1 – Planning the Build & Hardware Setup
→ Components, software, wiring concept, safety.

Part 2 – Prototype, Flashing ESPHome & Writing the YAML
→ ESPHome config, relay control, and testing each zone.

Part 3 – Creating a custom PCB
→ Walking through PCB design and ordering process

Part 4 – Integrating with Home Assistant
→ Adding all entities, automations, scheduling, and dashboard.

Part 5 – Adding Sensors & Smart Features
→ Soil moisture, rain delay, weather data, and refinement.

Part 6 – Final thoughts and future improvements
→ Closing thoughts what I like, what I dislike and would do better next time.

Why Build a Custom Controller?

Off-the-shelf irrigation systems work fine for simple setups — but they’re often limited, closed, and inflexible. By building your own controller with ESPHome and Home Assistant, you get:

Full control and customisation – tailor schedules, sensor logic, and automations exactly how you want.
Local operation – no reliance on vendor cloud services or app subscriptions.
Easy integration – connect with weather data, soil sensors, and other smart home devices.
Expandability – add more zones, relays, or features later without replacing the hardware.
Lower cost – use inexpensive components you can maintain or upgrade yourself.

In short, a DIY controller gives you flexibility and transparency that commercial units rarely offer — and it’s far more satisfying to build something that perfectly fits your garden and your system.

Why ESPHome?

ESPHome is a framework for programming ESP8266/ESP32 microcontrollers with simple YAML configuration. Instead of writing C++ code, you declare sensors, switches, and automations in YAML, then flash them to your device. Benefits include:

Tight Home Assistant integration (auto discovery).
Easy configuration and updates via Wi-Fi.
Support for a huge range of sensors and relays.
Community-friendly with lots of real-world examples.

Perfect for a project like irrigation control.

Hardware Needed

For a 4-zone controller, you’ll need at a minimum the following:

Electrical Components

Component	Example	Purpose
Microcontroller	ESP8266 (NodeMCU) or ESP32	Brain of the system
Relay module (4-channel)	5 V or 12 V logic	Controls solenoid valves
Solenoid valves	12 VAC garden valves	Open/close water flow
Power supply	12 VAC transformer (for valves) + 5 V DC (for ESP)	Powers everything
Jumper wires & terminals	Dupont / screw connectors	Clean wiring
Enclosure	Weather-resistant box	Keeps electronics dry
(optional) Manual override switch or button	—	Run a zone manually

Water/Hose Components

Component	Example	Purpose
Hose Manifold		Used to split the cold water supply to each zone
Hose to G-thread adapters	G3/4 to Hose	Used to connect various hose pipes to solenoid valves, depending on the valve depends on which connectors/adapters are required.
G-thread to irrigation adapters		Dependant on the irrigation system you use, you may need a specific adapter to go from the solenoid to pipe
Irrigation kit/drip feeders	Claber Dripper Irrigation Set for Ten Plants	Provides the irrigation part of the solution with suitable pipe and drip feeders, this solution can be adapted to use any brand of irrigation kits
Standard hose pipe		Misc. lengths of hose pipe to connect everything up

⚠️ Safety First

Even though this project mostly uses low voltage, it still involves water! Electrical safety still matters:

Double-check power ratings of relays and valves.
Keep low-voltage and mains-voltage circuits physically separate.
If you’re not confident with wiring, get help from someone experienced.
Always test with the water supply off the first time you power it up.
Always test the water fittings without the controller being connected to mains power!

A small amount of planning here avoids fried boards (or flooded flowerbeds) later.

Wiring Overview

The core idea is simple:
Each relay controls one irrigation zone (valve).
When the relay energizes, it completes the 24 VAC circuit to that valve.
The ESP sends a HIGH or LOW signal to trigger the relay.

[ESP32] ---> [Relay1] ---> Zone 1 Valve  
        ---> [Relay2] ---> Zone 2 Valve  
        ---> [Relay3] ---> Zone 3 Valve  
        ---> [Relay4] ---> Zone 4 Valve

Diagram (simplified)

ESP8266 GPIO → Relay Input → Relay Output → Solenoid Valve → 24 VAC Transformer

Basic flow for controlling a zone

Label each zone clearly (Zone 1 – Front Garden, Zone 2 – Lawn, etc.). It makes automation easier down the road.

Planning the Zones

Think through how you want to divide watering areas:

Zone 1 – Front garden
Zone 2 – Back lawn
Zone 3 – Vegetable bed
Zone 4 – Pots / greenhouse

The beauty of this project is you can add/remove zones as required at anytime, you can even expand this further to include even more zones should it be required.

Even if you wanted another controller in another part of the garden, its easy and cheap to replicate, compared to commercial offerings.

I started with one zone and build out the system at a later date to accommodate four zones.

If you plan ahead, you can also size your transformer and relay contacts properly for the total potential current draw.

Next Up

In Part 2, we’ll:

Build a prototype solution using one zone
Flash ESPHome onto the board
Write a simple YAML config for up to four relays
Expose each zone as a switch in Home Assistant

By the end of Part 2, you’ll be able to toggle each valve manually from your Home Assistant dashboard.

Tracking Daily Power Usage and Cost with Shelly and Home Assistant - Part 2

Andrew Townsend — Sat, 04 Oct 2025 18:20:35 GMT

One of the most rewarding parts of home automation is getting insights into how your home uses energy — and how much it’s costing you. If you’ve ever wondered what your washing machine, PC, or server rack really costs to run, you can easily find out using Shelly smart devices and Home Assistant.

In this post, we’ll look at how to set up Shelly devices to monitor power usage, track daily totals with Home Assistant’s Utility Meter, and calculate energy costs automatically.

Tutorial parts breakdown

Part 1 - (This post) Covering basic shelly setup along with configuring Home assistant utility meters to track periodic consumption daily/weekly etc.
Part 2 - (This Post) Covering device cost tracking, building upon Part 1 and extending this to track daily, weekly costs

Why Shelly?

Shelly devices are compact, Wi-Fi–enabled smart switches and relays made by Allterco Robotics. What makes them great for energy tracking is that many models (like the Shelly 2PM, , Shelly 1PM Mini Gen3, Shelly Plug S, or Shelly EM) include built-in power monitoring.

They’re:

Local-first (no cloud required).
Affordable and easy to retrofit.
Highly compatible with Home Assistant.
Reliable for continuous energy measurement.

If you’re already running Home Assistant, Shelly is one of the most seamless ways to get per-device power metrics.

A Quick Note on Electrical Safety ⚠️

Before diving into wiring any Shelly devices, it’s really important to emphasise electrical safety.

If you’re installing in-line devices like a Shelly 1PM or 2.5 — anything that involves mains voltage wiring — make sure you fully understand what you’re doing.

Always turn off power at the breaker before working.
Use proper tools and insulation.
If you’re not confident with electrical work, it’s best to get help from a qualified electrician.
Ensure you have reviewed the manufacturer guidelines and specifications, Shelly are very good at this and link all of the documentation alongside their models. Not all relays are suitable for certain load types i.e inductive vs resistive loads!

Smart home projects are great fun and rewarding to learn from, but safety should always come first — no automation is worth a shock or a fire hazard.

Hardware Setup & Adding Shelly to Home Assistant

We covered this in the previous post which went step by step through getting up to this point. Along with setting up the utility meters.

Adding Cost Tracking 💰

To track cost, you can create template sensors that multiply energy usage by your electricity rate. These are in the sensors.yaml file in the home directory of your Home Assistant installation, this may not exist so you might have to create it.

I have the benefit of having my In Home Display (IHD) feed data into Home assistant via MQTT which provides my import rate per kWh of electric, however if you know this value you can setup a helper which stores the current price per kWh which I will use in the example below.

For example, if your electricity costs £0.30 per kWh,

# Platform: template
- platform: template
  sensors:

    # microwave usage cost tracking today
    microwave_switch_electric_cost_today:
      friendly_name: "Microwave Switch Cost Today"
      unique_id: microwave_switch_electric_cost_today
      unit_of_measurement: "GBP"
      icon_template: mdi:currency-gbp
      value_template: >

        {% set todayPower = states('sensor.sensor.microwave_switch_power_today') %}

        {% if todayPower == 'unknown' or todayPower == 'unavailable' %}
          {% set todayPower = 0 | float %}
        {% endif %}


        {{ '%0.2f' % ((todayPower | float) * 0.30 | float) }}

    # microwave usage cost tracking week
    microwave_switch_electric_cost_week:
      friendly_name: "Microwave Switch Cost Week"
      unique_id: microwave_switch_electric_cost_week
      unit_of_measurement: "GBP"
      icon_template: mdi:currency-gbp
      value_template: >

        {% set todayPower = states('sensor.sensor.microwave_switch_power_today') %}

        {% if todayPower == 'unknown' or todayPower == 'unavailable' %}
          {% set todayPower = 0 | float %}
        {% endif %}


        {{ '%0.2f' % ((todayPower | float) * 0.30 | float) }}

Snipper from Home assistant home directory sensors.yaml

When you have saved this file, head to Developer tools -> Check configuration, assuming this gives you the green light of Configuration will not prevent Home Assistant from starting! you can simply click the Template entities button to load/reload them into Home Assistant.

This will give you two new entities:

sensor.microwave_switch_electric_cost_today
sensor.microwave_switch_electric_cost_week

As your utility meters update, these cost sensors will automatically calculate your spending based on current usage.

For more information on Template Sensors you can find the official documentation for them here: https://www.home-assistant.io/integrations/template/#sensor

Visualising Energy and Cost

Once your sensors are in place, you can add a card to your Home Assistant dashboard:

type: vertical-stack
cards:
  - type: statistics-graph
    title: Daily Energy Usage
    entities:
      - sensor.microwave_switch_power_today
    chart_type: bar
    days_to_show: 7
    stat_types:
      - sum
  - type: entities
    title: Today's Cost
    entities:
      - entity: sensor.microwave_switch_electric_cost_today
        name: Microwave Cost Today

Home assistant dashboard card showing statistics for energy usage and cost of that entity today

You’ll get a graph showing usage over the last week and a live readout of today’s running cost.

Example dashboard card showing power usage and cost today

Going Further

Use Shelly EM or 3EM to track total household energy usage.
Add automations to alert you if an appliance exceeds a certain daily cost.
Combine with InfluxDB + Grafana for long-term cost trends and forecasts.
Adjust your rate dynamically if your energy provider uses time-of-day pricing.

Conclusion

With just a few Shelly devices and some Home Assistant YAML, you can turn your smart plugs into a detailed, cost-aware energy dashboard.

You’ll not only see how much power your devices use, but also how much it costs — giving you real insight into your home’s efficiency and helping you make smarter energy decisions.

Just remember: when dealing with mains wiring, take electrical safety seriously — measure twice, wire once, and if in doubt, call an electrician.

It’s one of those simple automations that pays for itself — literally.

Tracking Daily Power Usage with Shelly and Home Assistant - Part 1

Andrew Townsend — Sat, 04 Oct 2025 14:28:21 GMT

One of the best parts of home automation is getting real data about how your home works — not just controlling things, but understanding them. If you’ve ever wondered how much energy your appliances are actually using, or wanted to see your daily consumption trends, you can do that easily with Shelly smart devices and Home Assistant.

In this post, I’ll walk through how to integrate Shelly devices with Home Assistant and use them to track and visualise your daily power usage.

Tutorial parts breakdown

Part 1 - (This post) Covering basic shelly setup along with configuring Home assistant utility meters to track periodic consumption daily/weekly etc.
Part 2 - Covering device cost tracking, building upon Part 1 and extending this to track daily, weekly costs

Why Shelly?

They’re:

Local-first (no cloud required).
Affordable and easy to retrofit.
Highly compatible with Home Assistant.
Reliable for continuous energy measurement.

If you’re already running Home Assistant, Shelly is one of the most seamless ways to get per-device power metrics.

A Quick Note on Electrical Safety ⚠️

Before diving into wiring any Shelly devices, it’s really important to emphasise electrical safety.

If you’re installing in-line devices like a Shelly 1PM or 2.5 — anything that involves mains voltage wiring — make sure you fully understand what you’re doing.

Always turn off power at the breaker before working.
Use proper tools and insulation.
If you’re not confident with electrical work, it’s best to get help from a qualified electrician.
Ensure you have reviewed the manufacturer guidelines and specifications, Shelly are very good at this and link all of the documentation alongside their models. Not all relays are suitable for certain load types i.e inductive vs resistive loads!

Smart home projects are great fun and rewarding to learn from, but safety should always come first — no automation is worth a shock or a fire hazard.

Hardware Setup

For this example, you can use any of the following Shelly devices:

🧱 Shelly 1PM / 2.5 – inline relays with power monitoring for lights or sockets.
🔌 Shelly Plug S / Plug UK – smart plugs for standalone devices.
⚡ Shelly EM / 3EM – clamp meters for whole-circuit or multi-phase monitoring.

Connect them to your Wi-Fi and assign static IPs if possible — it helps with reliability.

Adding Shelly to Home Assistant

You have two main options for integration:

1. Native Shelly Integration (Recommended)

Home Assistant natively supports Shelly devices using the CoAP or MQTT protocol.

In Home Assistant, go to Settings → Devices & Services → Add Integration.
Search for Shelly.
It should auto-discover devices on your network.
Click Configure to add them.

Once connected, you’ll see new entities like:

sensor.shelly_plug_power (instantaneous power, W)
sensor.shelly_plug_energy (total energy, Wh or kWh)
- This is total energy over all-time rather than today/yesterday like other devices such as Sonoff / Tasmota, so Shelly requires a bit more setup to get Periodic data (Daily, Weekly etc)
switch.shelly_plug_relay (on/off control)

2. MQTT Integration (Optional)

If you already use MQTT, you can flash Shelly devices to use it directly. Home Assistant will automatically create entities for MQTT topics like shellies/shellyplug/emeter/0/power.

Tracking Daily Power Usage

Now that your Shelly devices are feeding data into Home Assistant, let’s turn that into meaningful daily stats.

You can use Home Assistant’s built-in Utility Meter integration to automatically track daily, weekly, or monthly energy totals.

Example Configuration

In your configuration.yaml:

...
utility_meter:
  microwave_switch_power_today:
    source: sensor.microwave_switch_power
    cycle: daily
  microwave_switch_power_weekly:
    source: sensor.microwave_switch_power
    cycle: monthly
...

Example utility meters in Home Assistant configuration.yaml

This creates two new entities:

sensor.microwave_switch_power_today
sensor.microwave_switch_power_weekly

Each resets automatically at the start of a new day or month.

Visualizing in the Dashboard

Once you’ve got your utility meter entities, you can create a Lovelace dashboard card:

type: statistics-graph
title: Daily Energy Usage
entities:
  - sensor.microwave_switch_power_today
  - sensor.tv_daily
chart_type: bar
days_to_show: 7
stat_types:
  - sum

Home assistant dashboard card showing statistics for energy meters

Now you’ll have a bar chart showing daily consumption per device — great for spotting trends and understanding where your power goes.

Bonus: Alerts & Automation

You can also use automations to warn you about unusual power usage or when an appliance finishes running. For example:

Notify when washing machine is done:

alias: Microwave Finished
trigger:
  - platform: numeric_state
    entity_id: sensor.microwave_switch_power
    below: 2
    for:
      minutes: 3
action:
  - service: notify.mobile_app_your_phone
    data:
      message: "Microwave cycle completed!"

Home assistant automation detecting when a device has finished its cycle

A simple and unnecessary but very satisfying automation.

Conclusion

Shelly devices + Home Assistant = a powerful combo for understanding your home’s energy use.

With just a few sensors and a couple of YAML lines, you can build detailed daily usage charts, track trends over time, and even trigger automations based on real power data.

Whether you’re trying to save energy, monitor appliance efficiency, or just geek out on data, this setup is one of the most practical additions to any home lab.

Building a Home Lab Dashboard with Homer

Andrew Townsend — Fri, 03 Oct 2025 21:14:20 GMT

If you’ve been running a home lab for a while, you’ve probably collected a fair number of services — things like Home Assistant, Pi-hole, Proxmox, Uptime Kuma, Grafana, media servers, and more. The problem is, remembering all those URLs and ports gets messy fast.

That’s where Homer comes in: a simple, customizable static dashboard you can host anywhere to keep your home lab neat and organized.

What is Homer?

Homer is a lightweight homepage for your self-hosted services. It’s just a single-page web app written in Vue.js that you can run with Docker, Nginx, or even a static file host.

Key features:

Config-driven: Simple YAML config file for customisation.
Beautiful UI: Clean, tile-based interface with icons and colours.
Group support: Organise services into categories (e.g., Media, Monitoring, Infrastructure).
Custom links and widgets: Add search bars, markdown notes, or quick links.
Portable: No database — just config and assets.

It’s like having your own start page for everything in your lab.

Why Use Homer in a Home Lab?

Central access point for all your services.
Easy to remember one URL (like http://homer.local) instead of 20 different ports.
Customizable look and feel with icons and branding.
Lightweight — runs anywhere without heavy dependencies.

Installing Homer

Using Docker

The easiest way to get Homer running is with Docker:

docker run -d \
  -p 8080:8080 \
  -v /path/to/config:/www/assets \
  b4bz/homer:latest

Mount a volume for your config at /www/assets.
Access Homer at http://your-server:8080.

Using Proxmox LXC

Homer is even easier to setup in Proxmox using a LXC Container, there is a community script available and its instructions can be found here:
https://community-scripts.github.io/ProxmoxVE/scripts?id=homer

Always good to review scripts before blindly running them on your hardware but its as simple as running the following script and following the steps in the console

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/homer.sh)"

Configuring Homer

Homer is configured via a single YAML file: config.yml.

Here’s an example:

title: "Home Lab Dashboard"
subtitle: "All my services in one place"
logo: "assets/logo.png"

links:
  - name: "GitHub"
    url: "https://github.com"

services:
  - name: "Media"
    icon: "fas fa-film"
    items:
      - name: "Plex"
        logo: "assets/icons/plex.png"
        url: "http://192.168.1.10:32400"
      - name: "Jellyfin"
        logo: "assets/icons/jellyfin.png"
        url: "http://192.168.1.11:8096"

  - name: "Monitoring"
    icon: "fas fa-chart-line"
    items:
      - name: "Grafana"
        logo: "assets/icons/grafana.png"
        url: "http://192.168.1.12:3000"
      - name: "Uptime Kuma"
        logo: "assets/icons/uptime-kuma.png"
        url: "http://192.168.1.13:3001"

homer config.yml example

You can even do things such as integrating with specific applications such as Proxmox to get disk usage etc, this is done with smart cards.

See my image below or handily get it to ping resources to check they are online/offline, this can be achieved with the following snippet as an example.

- name: "Plex"
  logo: "https://i.redd.it/5x93lknmuaw81.jpg"
  subtitle: "https://plex.your-domain.com"
  url: "https://plex.your-domain.com/"
  type: Ping
  successCodes: [200, 401]
  method: "get"
  target: "_blank"

For a full list of available Smart cards these are included in the Homer documentation here including a few I have mentioned above:

Customising the Dashboard

Some nice touches you can add:

Icons and logos: Drop PNG/SVGs into the assets folder.
Themes: Light, dark, and custom themes supported.
Widgets: Add search bars (Google, DuckDuckGo, internal docs) or markdown notes.
External links: Quick access to GitHub, documentation, or cloud dashboards.

Example customised dashboard

Tips for Home Lab Use

Host Homer on a reverse proxy (like HAproxy or Nginx or Traefik) at http://homer.your-domain.
Use HTTPS with Let’s Encrypt if exposing outside your LAN.
Combine with authentication (Authelia, OAuth, etc.) for secure access or keep it hidden and internal use only.
Keep a backup of your config.yml — that’s your whole dashboard.

Conclusion

Homer is a simple, elegant way to bring order to your home lab chaos. With one URL, you get a beautiful dashboard that keeps all your services accessible and organised. It’s lightweight, easy to configure, and endlessly customisable.

If your browser bookmarks are overflowing or you’ve ever forgotten which port a service runs on, Homer is the perfect solution.

References

https://github.com/louislam/uptime-kuma

GitHub - louislam/uptime-kuma: A fancy self-hosted monitoring tool

A fancy self-hosted monitoring tool. Contribute to louislam/uptime-kuma development by creating an account on GitHub.

GitHublouislam

https://community-scripts.github.io/ProxmoxVE/scripts?id=uptimekuma

Proxmox VE Helper-Scripts

The official website for the Proxmox VE Helper-Scripts (Community) repository. Featuring over 300+ scripts to help you manage your Proxmox Virtual Environment.

Proxmox VE Helper-ScriptsBram Suurd

Monitoring Services with Uptime Kuma

Andrew Townsend — Fri, 03 Oct 2025 20:52:56 GMT

If you run self-hosted apps, home lab services, or production infrastructure, you know the feeling: is it just me, or is the service down? Instead of waiting for someone to complain (or discovering it yourself when you try to use it), it’s better to have a monitoring tool that tells you when things break — and ideally before your users notice.

That’s where Uptime Kuma comes in.

What is Uptime Kuma?

Uptime Kuma is a self-hosted, open-source status monitoring tool. Think of it as a free, self-managed alternative to services like UptimeRobot or StatusCake. It lets you monitor websites, APIs, and network services, then alerts you when they go down.

Key features:

Multiple monitor types: HTTP(s), TCP, ICMP (ping), DNS, Push, and more.
Customisable alerts: Email, Telegram, Discord, Slack, Gotify, Pushover, etc.
Beautiful dashboard: A clean web interface with status history and charts.
Public status pages: Share uptime with your team or community.
Self-hosted: You control the data and deployment.

Why Use Uptime Kuma?

Keep an eye on home lab services (Pi-hole, Home Assistant, media servers).
Monitor production apps and APIs with confidence.
Get alerts quickly instead of discovering downtime by accident.
Track historical uptime for troubleshooting or reporting.
Run it anywhere — from a Raspberry Pi to a cloud VPS.

Installing Uptime Kuma

Using docker

The easiest way to get started is with Docker:

docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  louislam/uptime-kuma

This runs Uptime Kuma on port 3001 and persists data in a Docker volume.

Then, open http://your-server:3001 in a browser, create an admin account, and you’re ready to go.

Using Proxmox LXC

Kuma is even easier to setup in Proxmox using a LXC Container, there is a community script available and its instructions can be found here:
https://community-scripts.github.io/ProxmoxVE/scripts?id=uptimekuma

Always good to review scripts before blindly running them on your hardware but its as simple as running the following script and following the steps in the console

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/uptimekuma.sh)"

Adding a Monitor

Showing the create/edit monitor form

Log in to the dashboard.
Click Add New Monitor.
Choose a monitor type (e.g., HTTP(s), Ping, TCP).
Enter the target URL or IP.
Configure interval, timeout, and retries.
Save — and your monitor starts running.

You’ll see real-time status updates, response times, and uptime percentages.

Showing the monitor once it has been setup

You can take this further by assigning meaningful Tags to categorise monitors such as in my example if it is a public facing endpoint or an internal endpoint.

Setting Up Alerts

Uptime Kuma supports a wide range of notifications. For example, to set up Telegram alerts:

Go to Settings → Notification.
Add a new notification of type Telegram Bot.
Provide your bot token and chat ID.
Link it to one or more monitors.

Now, you’ll get a Telegram message whenever a service goes down or comes back up.

Public Status Page

One of Uptime Kuma’s nicest features is the ability to generate a public status page. This is great if you’re running services for others (or just want a clean way to check everything at a glance).

You can create multiple pages — for example:

Internal status page for your home lab.
External status page for services your users access.

Each page shows uptime graphs, response times, and the current state of your monitors.

An example status page once configured

Conclusion

Uptime Kuma is an excellent, self-hosted alternative for service monitoring. It’s lightweight, feature-rich, and easy to deploy. Whether you’re running a home lab, side projects, or production systems, Kuma gives you peace of mind by watching your services and notifying you when something breaks.

If you’ve been relying on hope (or user complaints) to know when things go down, give Kuma a try — your future self will thank you.

References

https://github.com/louislam/uptime-kuma

GitHub - louislam/uptime-kuma: A fancy self-hosted monitoring tool

A fancy self-hosted monitoring tool. Contribute to louislam/uptime-kuma development by creating an account on GitHub.

GitHublouislam

https://community-scripts.github.io/ProxmoxVE/scripts?id=uptimekuma

Proxmox VE Helper-Scripts

The official website for the Proxmox VE Helper-Scripts (Community) repository. Featuring over 300+ scripts to help you manage your Proxmox Virtual Environment.

Proxmox VE Helper-ScriptsBram Suurd

Setting Up Ghost with S3 Storage Using ghost-storage-adapter-s3: Part 2

Andrew Townsend — Thu, 02 Oct 2025 23:01:18 GMT

If you haven't read Part 1 of this series it can be found here Setting Up Ghost with S3 Storage Using ghost-storage-adapter-s3: Part 1

Amazon CloudFront is a powerful CDN for speeding up content delivery. By default, when you create a distribution, AWS gives you a long, autogenerated domain like:

d1234abcdef.cloudfront.net

That works fine, but it’s not user-friendly. For production, you’ll usually want to use your own domain — for example, content.yoursite.com — so your assets are delivered under your brand.

In this post, I’ll walk through setting up a CloudFront distribution with a custom domain alias (CNAME).

Prerequisites

An AWS account with CloudFront enabled. (This is covered in Part 1)
A domain you own (registered with Route 53 or another DNS provider).
An SSL/TLS certificate in AWS Certificate Manager (ACM) for your domain.

Just like the Previous post, example AWS CloudFormation templates are available on my GitHub and can be found here and navigate to the ghost-storage-adapter-s3 directory or using the individual links linked below. Or you can follow the steps to create it manually.

GitHub - atownsend247/brightbot-source-files: Provides git access to scripts and templates for associated BrightBot blog posts

Provides git access to scripts and templates for associated BrightBot blog posts - atownsend247/brightbot-source-files

GitHubatownsend247

cloudformation-template-acm.yaml Stack to create the AWS Amazon Certificate Manager (ACM) Certificate in the us-east-1 region.
cloudformation-template-with-acm-alias.yaml An update template from Part 1, that includes a custom CloudFront alias and certificate configuration.

Step 1: Request an SSL/TLS Certificate

To use a custom domain with CloudFront, you need an SSL certificate.

Request a public certificate for your custom domain (e.g., content.yoursite.com).
Validate the certificate using DNS or email (DNS is recommended).

Go to AWS Certificate Manager in the us-east-1 (N. Virginia) region.

Important: CloudFront only uses certificates in us-east-1, even if your distribution is elsewhere.

Once validated, your certificate will show as Issued.

Step 2: Create or Edit a CloudFront Distribution

Go to CloudFront > Distributions and click Create Distribution (or edit an existing one).
Under Settings → Alternate Domain Names (CNAMEs), enter your custom domain:

content.yoursite.com

Under Custom SSL Certificate, select the certificate you created in ACM.
Configure the rest of your distribution (origin, caching, behaviors) as usual.
Save and deploy the distribution.

Step 3: Update Your DNS

Now you need to point your custom domain to the CloudFront distribution.

Go to your DNS provider (Route 53 or elsewhere).
Create a CNAME record for your custom domain:

content.yoursite.com → d1234abcdef.cloudfront.net

Save the record.

DNS changes may take some time to propagate.

Step 4: Test the Setup

Once DNS propagation is complete:

Visit https://content.yoursite.com in your browser.
You should see content served from CloudFront.
Check the SSL certificate — it should show your custom domain.

Step 5: Update configuration of Ghost to Use the Adapter

In your Ghost config file (config.production.json), update the storage block assetHost property:

{
  ...,
  "storage": {
    "active": "s3",
    "s3": {
      ...
      "assetHost": "https://content.yoursite.com",
      ...
    }
  }
}

Save the config file and restart your Ghost instance to apply changes:

ghost restart

From now on, uploaded images and media will go directly to your S3 bucket instead of local disk.

Tips & Best Practices

Use Route 53 with Alias Records: If your custom domain is a root domain (example.com instead of cdn.example.com), use an Alias record in Route 53 instead of CNAME.
Leverage a CDN subdomain: Keeping CDN assets on cdn.yoursite.com helps separate them from your main domain.
Enable logging: CloudFront can log requests to S3 for debugging and analytics.
Cache policies: Fine-tune cache behavior to balance performance and freshness.

Conclusion

Setting up a CloudFront distribution with a custom domain alias gives you:

A cleaner, branded URL for your assets.
SSL/TLS encryption with your own domain certificate.
The speed and scalability of AWS CloudFront.

Once configured, your site looks more professional and benefits from faster, more secure content delivery.

This tutorial has talked you through fully configuring Ghost to use an external storage adapter utilising Amazon S3, Amazon CloudFront, Amazon ACM Certificate.

Setting Up Ghost with S3 Storage Using ghost-storage-adapter-s3: Part 1

Andrew Townsend — Thu, 02 Oct 2025 14:32:08 GMT

By default, Ghost stores uploaded images and media locally on the same server that runs Ghost. That works fine for small blogs, but if you want to run Ghost in a scalable environment (like Docker, Kubernetes, or multiple servers behind a load balancer), you’ll quickly run into problems.

To make Ghost more flexible, you can use Amazon S3 (or an S3-compatible service like MinIO, DigitalOcean Spaces, or Backblaze B2) for media storage. This decouples your storage from the Ghost instance, ensuring uploads are consistent across deployments.

The main driver behind this, was to use Ghost as a completely headless CMS allowing for Gatsby to serve images easily and separately without exposing my Ghost instance to the public. This process allows you to upload images within Ghost and have them available within a Gatsby generated site.

In this post, I’ll walk through setting up Ghost with ghost-storage-adapter-s3. Using Amazon S3 and Amazon CloudFront to seamlessly serve images for both Ghost as CMS and Gatsby as a static website.

Why Use S3 for Ghost Storage?

Scalability: Media is available no matter how many Ghost instances you run.
Durability: S3 handles replication and durability better than local disk.
Flexibility: Works with AWS S3 or any S3-compatible service.
Portability: Makes running Ghost in containers or serverless setups easier.

Why Use CloudFront for asset delivery?

Fast: Caches your content across a global network of edge locations, so users get data from the nearest server instead of your origin. This reduces latency and speeds up page loads.
Scalability: Your site can handle sudden traffic spikes without overwhelming your origin server. It distributes requests across multiple edge locations, keeping things stable even under heavy load.
Security: integrates with AWS Shield, WAF, and SSL/TLS to protect against DDoS attacks, bots, and other threats — while ensuring encrypted connections for your users.
Cost: By caching content at the edge, CloudFront reduces the amount of data pulled directly from your origin (like S3 or an EC2 instance). That means lower bandwidth costs and more efficient infrastructure usage.

Prerequisites

A running Ghost instance (self-hosted).
Node.js environment (to install the adapter).
An Amazon S3 bucket. (Steps to create these will also be detailed below)
An Amazon CloudFront distribution. (Steps to create these will also be detailed below)
AWS IAM Access key + Secret key with appropriate permissions. (Steps to create these will also be detailed below)

Step 1: Install `ghost-storage-adapter-s3`

Navigate to your Ghost installation directory and install the adapter:

npm install ghost-storage-adapter-s3
mkdir -p ./content/adapters/storage
cp -r ./node_modules/ghost-storage-adapter-s3 ./content/adapters/storage/s3

Ghost looks in content/adapters/storage/ for storage adapters, so the directory structure is important

Node.js environment (to install the adapter).
An S3 bucket (AWS or compatible).
S3 access key + secret key with appropriate permissions.

Step 2: Configure AWS resources

There are two ways to proceed with AWS, I would strongly suggest using the CloudFormation template and sticking with Configuration as Source Code, but I have included the manual steps also if that is more preferable. At the end of this s you should have the values for

AWS CLI Access Key - Used by Ghost to authenticate with AWS
AWS CLI Secret Access Key - Used in conjunction with the Access Key
AWS Region - The region in which your resources are deployed
AWS CloudFront distribution URL - Used as assetHost

Using a CloudFormation Template

I have provided a GitHub repository for this article that offers a bare bones CloudFormation template which will provision the following AWS resources:

24 Hour CloudFront Cache Policy
CloudFront Origin Access Control (OAC)
S3 Storage Bucket
S3 Storage Bucket Policy - Linking the Distribution/OAC with the bucket
IAM Ghost User - Used by Ghost to access the bucket securely
IAM Ghost User Policy
CloudFront Distribution

The code can be reviewed here: https://github.com/atownsend247/brightbot-source-files/blob/main/ghost-storage-adapter-s3/cloudformation-template.yaml

You can use this to create a new CloudFormation stack from the AWS Console, then update the Project parameter to suit your requirement.

Finally once created complete, reference the Outputs tab of CloudFormation to get the CloudFront distribution URL to use as assetHost later on.

Now the IAM user is created navigate to it in the AWS Console, click on Security Credentials -> Create access key. Select Command Line Interface (CLI), select the confirmation, give it a friendly name and either download the credentials.csv or copy the Access key value and Secret access key to somewhere safe as we need these later.

Manually creating resources

You'll likely want to configure a separate S3 bucket for your blog, a specific IAM role, and, optionally, CloudFront, to serve from a CDN.

S3

Create a new bucket. The region isn't important at this stage.

As we are setting this up manually, you can let Amazon CloudFront setup the OAC (Origin Access Control) on your behalf.

IAM

You'll want to create a custom user role in IAM that just gives your Ghost installation the necessary permissions to manipulate objects in its S3 bucket.

Go to IAM in your AWS console and add a new user. Give it a username specific to your blog, and select Programmatic access as the Access type.

Next, on the permissions page, select Attach existing policies directly and click to Create policy. For the policy click on the JSON editor and add the following policy. You'll want to replace where it says your-bucket-name with the name of your blog's S3 bucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::your-bucket-name"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectVersionAcl",
                "s3:DeleteObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::your-bucket-name/*"
        }
    ]
}

IAM User Policy

What this policy does is allow the user access to see the contents of the bucket (the first statement), and then manipulate the objects stored in the bucket (the second statement).

Finally, create the user and copy the Access key and Secret access key, these are what you'll use in your configuration.

At this point your done with the Ghost access to Amazon S3

CloudFront

CloudFront is a CDN that replicates objects in servers around the world so your blog's visitors will get your assets faster by using the server closest to them. It uses your S3 bucket as the "source of truth" that it populates its servers with.

Got to CloudFront in AWS and choose to Create a Distribution. On the next screen you'll want to leave everything the same, except change the following:

Then create the distribution.

Finally, in your configuration, use the subdomain for the CloudFront distribution as your setting for assetHost.

Step 3: Configure Ghost to Use the Adapter

In your Ghost config file (config.production.json), add the storage block:

{
  ...,
  "storage": {
    "active": "s3",
    "s3": {
      "accessKeyId": "YOUR_AWS_ACCESS_KEY",
      "secretAccessKey": "YOUR_AWS_SECRET_KEY",
      "region": "your-region",
      "bucket": "your-s3-bucket-name",
      "assetHost": "https://your-cloudfront-endpoint",
      "serverSideEncryption": "AES256",
      "forcePathStyle": true,
      "acl": "private"
    }
  }
}

Step 4: Restart Ghost

Restart your Ghost instance to apply changes:

ghost restart

From now on, uploaded images and media will go directly to your S3 bucket instead of local disk.

Step 5: Verify Uploads

If you see the image in S3 and it loads in your post, you’re good to go.

Conclusion

With ghost-storage-adapter-s3, you can decouple Ghost’s media storage from your server, making your blog more resilient and easier to scale. Whether you’re running Ghost in Docker, on Kubernetes, or just want the reliability of cloud storage, this setup is a solid way to go.

If you also serve your media through a CDN (like CloudFront), you’ll get the added bonus of faster load times for readers all over the world.

Head over to Part 2 linked below, to expand this further and use a custom domain with AWS CloudFront.

References

https://ghost.org/

Ghost: The best open source blog & newsletter platform

Beautiful, modern publishing with email newsletters and paid subscriptions built-in. Used by Platformer, 404Media, Lever News, Tangle, The Browser, and thousands more.

Ghost - The Professional Publishing Platform

https://github.com/colinmeinke/ghost-storage-adapter-s3

GitHub - colinmeinke/ghost-storage-adapter-s3: An AWS S3 storage adapter for Ghost

An AWS S3 storage adapter for Ghost. Contribute to colinmeinke/ghost-storage-adapter-s3 development by creating an account on GitHub.

GitHubcolinmeinke

https://github.com/atownsend247/brightbot-source-files/blob/main/ghost-storage-adapter-s3/cloudformation-template.yaml

GitHub - atownsend247/brightbot-source-files: Provides git access to scripts and templates for associated BrightBot blog posts

Provides git access to scripts and templates for associated BrightBot blog posts - atownsend247/brightbot-source-files

GitHubatownsend247

Linting Documentation with Vale: Consistent, Clear, and Error-Free Writing

Andrew Townsend — Wed, 01 Oct 2025 18:38:50 GMT

If you’ve ever worked on a large documentation project, you know how quickly things can get messy. Different contributors bring different writing styles, terminology gets inconsistent, and small grammar mistakes sneak through. That’s where Vale comes in — a linter for prose that helps keep your docs clean, consistent, and professional.

What is Vale?

Vale is an open-source command-line tool for linting and style-checking text. Think of it like ESLint or Prettier, but for documentation and prose instead of code. It helps you:

Enforce a consistent style across docs.
Catch grammar, spelling, and clarity issues early.
Standardize terminology (e.g., always use “sign in” instead of “login”).
Automate reviews so humans can focus on content, not nitpicks.

Vale works with Markdown, reStructuredText, AsciiDoc, and more — making it a great fit for docs-as-code workflows.

Why Use Vale?

Consistency matters: Readers trust documentation that feels cohesive.
Saves reviewer time: Automates style nitpicks so reviewers can focus on accuracy.
Integrates with CI/CD: Catch doc issues before merging.
Customisable: Define your own style rules or adopt existing ones (like Google or Microsoft style guides).

Installing Vale

Vale is distributed as a single binary — no big dependencies.

On macOS (via Homebrew):

brew install vale

On Linux (via binary release):

curl -s https://api.github.com/repos/errata-ai/vale/releases/latest \
| grep "browser_download_url.*Linux_64-bit.tar.gz" \
| cut -d '"' -f 4 \
| wget -qi - && tar -xzf Vale_*_Linux_64-bit.tar.gz

On Windows: download from the Vale releases page.

Setting Up Vale

In the root of your docs project, create a .vale.ini file:

StylesPath = styles
MinAlertLevel = suggestion

Packages = Google, proselint, write-good

[*.md]
BasedOnStyles = Vale, Google, proselint, write-good

This tells Vale to:

Look for styles in the styles/ directory.
Use Microsoft’s style guide.
Apply it to all .md files.

Running Vale

Once configured, lint your docs with:

vale path/to/docs/

Example output:

docs/getting-started.md
 25:5  error  'login' should be written as 'sign in'  Google.Terms
 44:10 warning  Avoid using 'simply'                  Google.Avoid

Here you can see Vale catching terminology and tone issues automatically.

Customizing Rules

Vale is powerful because you can define your own style rules. For example, let’s enforce “e-mail” vs “email.”

Create a file at styles/Custom/Terms.yml:

extends: existence
message: "Use 'email' instead of 'e-mail'."
level: error
ignorecase: true
tokens:
  - e-mail

Now Vale will flag “e-mail” anywhere in your docs.

Using Vale in CI/CD

To ensure consistency across teams, add Vale to your build pipeline. For example, in GitHub Actions:

name: Lint Docs

on: [pull_request]

jobs:
  vale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Vale
        run: |
          curl -fsSL https://install.goreleaser.com/github.com/errata-ai/vale.sh | sh
          sudo mv ./bin/vale /usr/local/bin/
      - name: Run Vale
        run: vale .

This way, PRs can’t be merged until documentation passes linting.

Starter Vale Style Guide

This starter style guide enforces clear, consistent, and professional writing. It includes rules for terminology, tone, and formatting that you can extend as your docs mature.

👉 Folder structure example:

docs/
styles/
  Starter/
    Terms.yml
    Tone.yml
    Spacing.yml
.vale.ini

.vale.ini

StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Starter

This tells Vale to look in the styles/ folder and apply the Starter style to all Markdown files.

`Terms.yml` – Consistent Terminology

extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
  login: sign in
  log-in: sign in
  e-mail: email
  Github: GitHub
  Javascript: JavaScript

✅ Enforces consistent word choices and fixes common brand/style mistakes.

`Tone.yml` – Avoid Filler Words

extends: existence
message: "Avoid using '%s'."
level: warning
ignorecase: true
tokens:
  - simply
  - obviously
  - clearly
  - basically
  - just

✅ Flags words that can sound condescending or unnecessary in documentation.

`Spacing.yml` – Clean Formatting

extends: existence
message: "Use a single space between sentences."
level: error
nonword: true
tokens:
  - '\s{2,}'

✅ Ensures no double spaces sneak into your text.

How to Use

Save the above files into styles/Starter/.
Update .vale.ini to include Starter.
Run vale docs/ and watch it flag issues.

Example in Action

Input:

To login, just click the button. Github is simply awesome!

Output:

 1:4  error   Use 'sign in' instead of 'login'.       Starter.Terms
 1:11 warning Avoid using 'just'.                     Starter.Tone
 1:29 error   Use 'GitHub' instead of 'Github'.       Starter.Terms
 1:37 warning Avoid using 'simply'.                   Starter.Tone
 1:50 error   Use a single space between sentences.   Starter.Spacing

Conclusion

Vale takes the guesswork out of documentation quality. By automating style and consistency checks, it frees up writers and reviewers to focus on content and accuracy. Whether you’re maintaining internal runbooks, public APIs, or open-source docs, Vale helps you deliver polished, professional writing every time.

This starter style guide gives you:

Terminology enforcement (consistent words, correct brands).
Tone checks (avoid filler or condescending words).
Formatting rules (like spacing).

It’s lightweight but effective — and you can extend it with custom rules as your docs grow.

If you’re serious about treating docs like code, adding Vale to your toolchain is a no-brainer.

Setting Up Network UPS Tools (NUT) for APC UPS Devices on Linux

Andrew Townsend — Wed, 01 Oct 2025 08:56:05 GMT

When you’re running critical systems — whether it’s a home lab, a small business server, or production workloads — power outages can cause real headaches. That’s where an Uninterruptible Power Supply (UPS) comes in. But to make the most of it, your server needs to know when the UPS is running on battery, when it’s low, and when to shut down gracefully.

That’s exactly what Network UPS Tools (NUT) does. In this guide, we’ll walk through setting up NUT on Linux with an APC UPS.

What is NUT?

Network UPS Tools (NUT) is an open-source suite that provides:

Drivers for a wide range of UPS devices (including APC).
A monitoring daemon to track UPS status.
Shutdown coordination for multiple systems.
Remote monitoring over the network.

It’s highly flexible, works across many UPS models, and is widely used in both enterprise and homelab environments.

Prerequisites

A Linux system (Debian/Ubuntu, RHEL, or similar).
An APC UPS connected via USB or serial cable.
Root or sudo access.

For the purposes of this post, I will be connecting 2x APC UPS-B Back-UPS XS 1400U UPS's to a single Raspberry Pi5

Step 1: Install NUT

On Debian/Ubuntu:

sudo apt update
sudo apt install nut nut-client nut-server

Step 2: Identify Your UPS

Plug in your APC UPS via USB, then run:

lsusb

You should see something like:

Bus 001 Device 005: ID 051d:0002 American Power Conversion Uninterruptible Power Supply
Bus 001 Device 004: ID 051d:0002 American Power Conversion Uninterruptible Power Supply

This tells us the UPS is detected.

Step 3: Configure NUT Driver

Edit /etc/nut/ups.conf:

# Generic APC UPS
[apc]
    driver = usbhid-ups
    port = auto
    desc = "APC UPS"

# Specific to my UPSs
[apcupsa]
driver = usbhid-ups
desc = "APC UPS-A Back-UPS XS 1400U 4B2028P50251"
port = auto
vendorid = 051d
productid = 0002
serial = serial1

[apcupsb]
driver = usbhid-ups
desc = "APC UPS-B Back-UPS XS 1400U 4B2028P50042"
port = auto
vendorid = 051d
productid = 0002
serial = serial2

apc is the UPS name (you can choose your own).
usbhid-ups is the driver used for most modern APC UPS devices.
port = auto lets NUT detect the UPS automatically.

Test the driver:

sudo upsdrvctl start

Step 4: Configure UPS Daemon

Edit /etc/nut/upsd.conf:

LISTEN 0.0.0.0 3493

This tells NUT to listen for connections on localhost.

Then edit /etc/nut/upsd.users:

[upsmon]
    password = strongpassword
    upsmon primary
    instcmds = ALL

Step 5: Configure NUT Client

Edit /etc/nut/upsmon.conf:

MONITOR apcupsa@localhost 1 upsmon strongpassword primary
MONITOR apcupsb@localhost 1 upsmon strongpassword primary

This means:

Monitor the UPS named apc at localhost.
Use the admin user with the password.
master indicates this system will manage shutdowns.

Step 6: Set NUT Mode

Edit /etc/nut/nut.conf:

MODE=netserver

(Use netserver or netclient if you want multiple systems connected to the UPS.)

Step 7: Start and Enable Services

sudo systemctl enable nut-server
sudo systemctl enable nut-monitor
sudo systemctl start nut-server
sudo systemctl start nut-monitor

Step 8: Verify

Check UPS status:

upsc apc@localhost

You should see output like:

battery.charge: 100
battery.charge.low: 10
battery.charge.warning: 50
battery.date: 2001/09/25
battery.mfr.date: 2020/07/10
battery.runtime: 4088
battery.runtime.low: 120
battery.type: PbAc
battery.voltage: 27.3
battery.voltage.nominal: 24.0
device.mfr: American Power Conversion
device.model: Back-UPS XS 1400U
device.serial: myserial1
device.type: ups
driver.name: usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.parameter.productid: 0002
driver.parameter.serial: myserial1
driver.parameter.synchronous: auto
driver.parameter.vendorid: 051d
driver.version: 2.8.0
driver.version.data: APC HID 0.98
driver.version.internal: 0.47
driver.version.usb: libusb-1.0.26 (API: 0x1000109)
input.sensitivity: medium
input.transfer.high: 280
input.transfer.low: 155
input.transfer.reason: input voltage out of range
input.voltage: 240.0
input.voltage.nominal: 230
ups.beeper.status: enabled
ups.delay.shutdown: 20
ups.firmware: 926.T2 .I
ups.firmware.aux: T2
ups.load: 9
ups.mfr: American Power Conversion
ups.mfr.date: 2020/07/10
ups.model: Back-UPS XS 1400U
ups.productid: 0002
ups.realpower.nominal: 700
ups.serial: myserial1
ups.status: OL
ups.test.result: No test initiated
ups.timer.reboot: 0
ups.timer.shutdown: -1
ups.vendorid: 051d

OL means “On Line” (power is good).
You’ll see OB (On Battery) if you unplug the UPS.

Step 9 (Optional): Remote Monitoring

If you want multiple servers to shut down gracefully:

Set MODE=netserver on the UPS host.
Configure upsd.conf to listen on the LAN IP.
On client machines, set MODE=netclient and point upsmon.conf at the UPS host.

Conclusion

With NUT configured, your Linux system can monitor your APC UPS, log events, and safely shut down when power runs out. This setup ensures your data and systems stay protected during outages — and you get peace of mind knowing your UPS isn’t just sitting there, but actively integrated into your infrastructure.

Ghost + Gatsby: A Modern Publishing Stack for Fast, Flexible Websites

Andrew Townsend — Mon, 29 Sep 2025 13:29:30 GMT

If you want a publishing platform that’s both powerful and lightning fast, combining Ghost with Gatsby is a great way to go. Ghost handles content management and publishing, while Gatsby builds a highly optimized static site from that content. Together, they deliver the best of both worlds: an easy editor for authors and a blazing-fast frontend for readers.

What is Ghost?

Ghost is a modern, open-source CMS (Content Management System) built specifically for professional publishing. Unlike general-purpose CMS platforms, Ghost focuses on content creation, monetization, and simplicity.

Key features include:

Beautiful, distraction-free editor (Markdown-based with rich embeds)
Membership and subscription support
Built-in SEO and AMP support
Powerful APIs for integration (REST and GraphQL)
Headless CMS mode

Ghost can be used as a full CMS with its own frontend theme system, or as a headless CMS that provides content to another frontend like Gatsby.

What is Gatsby?

Gatsby is a React-based static site generator. It takes your content (from sources like Ghost, WordPress, Markdown, or APIs) and compiles it into a static site. The result: super-fast load times, improved SEO, and high scalability.

Highlights include:

Static site generation with server-side rendering (SSR) and incremental builds
Rich plugin ecosystem for data sources and features
Performance optimization (image optimization, prefetching, code splitting)
React-based frontend for dynamic interactivity
Deployed anywhere (Netlify, Vercel, AWS, etc.)

Why Use Ghost and Gatsby Together?

Ghost as the content hub – Editors and authors manage posts in Ghost’s admin panel.
Gatsby as the frontend – Pulls content from Ghost’s API and builds a fast, secure, static site.
Separation of concerns – Writers focus on content, developers focus on presentation.
Performance and scalability – Gatsby sites are static, so they’re extremely fast and easy to host on CDNs.
Security – With a static frontend, there’s no exposed CMS backend to attack.

Typical Architecture

Here’s what a Ghost + Gatsby setup looks like:

   Authors & Editors
          |
          v
   +---------------+
   |     Ghost     |  <-- CMS (Content API)
   | (Headless)    |
   +---------------+
          |
          v
   +---------------+
   |    Gatsby     |  <-- Static site generator (React)
   |   (Builds)    |
   +---------------+
          |
          v
   +---------------+
   |   Deployed    |  <-- CDN / Hosting (Netlify, Vercel, etc.)
   |   Website     |
   +---------------+
          |
          v
       Readers

Ghost stores and manages your content.
Gatsby fetches content via the Ghost Content API (or GraphQL).
Gatsby builds static files (HTML, CSS, JS).
The site is deployed to a CDN for speed and global availability.

Example Setup

Install Gatsby Ghost Source Plugin

In gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-ghost`,
      options: {
        apiUrl: `https://your-ghost-site.com`,
        contentApiKey: `YOUR_CONTENT_API_KEY`,
      },
    },
  ],
};

Query Ghost Content with GraphQL

Example query in Gatsby:

{
  allGhostPost {
    edges {
      node {
        title
        slug
        published_at(formatString: "MMMM DD, YYYY")
        html
      }
    }
  }
}

This lets you pull posts from Ghost and render them in Gatsby pages.

Benefits of This Setup

Best authoring experience – Ghost provides a clean, intuitive editor.
Blazing-fast sites – Gatsby generates static pages optimized for performance.
Secure & scalable – The frontend is static, hosted on a CDN.
Developer-friendly – Modern React ecosystem for custom UIs.
Future-proof – Decoupled CMS architecture for flexibility.

Conclusion

Ghost + Gatsby is a modern publishing stack that balances content creation ease with frontend performance and scalability. Ghost takes care of authors, while Gatsby ensures readers get a super-fast experience.

If you’re building a blog, magazine, or content-driven business website, this combo is a powerful alternative to traditional CMS platforms.

In the next part of this series I will talk over fully expanding on Gatsby to generate a full static website, which funnily enough exactly how this site is created.

High Availability with HAProxy and Keepalived: A Practical Guide

Andrew Townsend — Mon, 29 Sep 2025 09:27:31 GMT

When it comes to building resilient and scalable infrastructure, two tools often come up together: HAProxy and Keepalived. While HAProxy excels at load balancing and proxying, Keepalived ensures service continuity by managing failover and redundancy. Together, they form a rock-solid foundation for highly available systems.

What is HAProxy?

HAProxy (High Availability Proxy) is an open-source load balancer and reverse proxy widely used in production environments. It sits between clients and backend servers, distributing traffic efficiently and providing features such as:

Layer 4 and Layer 7 load balancing (TCP/HTTP/HTTPS)
SSL termination
Health checks for backend servers
Sticky sessions
Advanced routing and ACLs
Logging and metrics integration

Because of its performance and flexibility, HAProxy is used by some of the largest web platforms in the world.

What is Keepalived?

Keepalived is an open-source tool that provides high availability and failover capabilities for Linux systems. It primarily uses VRRP (Virtual Router Redundancy Protocol) to create a floating IP address shared between servers. If the primary node goes down, Keepalived automatically promotes a standby node to take over the virtual IP.

Key features include:

VRRP-based failover
Health checks for services and nodes
Automatic failover with minimal downtime
Lightweight and easy to configure

Why Use HAProxy and Keepalived Together?

Using HAProxy alone gives you load balancing across your backend servers. But what happens if the HAProxy server itself fails? That’s where Keepalived comes in.

With HAProxy + Keepalived, you get:

Load balancing and traffic management (via HAProxy).
High availability of the load balancer itself (via Keepalived).
A floating virtual IP that clients connect to, which always points to the active HAProxy node.
Failover with minimal service disruption when a node fails.

This setup prevents a single point of failure in your load balancing layer.

Typical Architecture

Here’s a simplified setup:

      +---------------------+
Client ---> VIP:80/443 (Managed by Keepalived)
                 |
     -----------------------------
     |                           |
+------------+             +------------+
| HAProxy #1 |             | HAProxy #2 |
| (MASTER)   |             | (BACKUP)   |
| 10.1.0.10  |             | 10.2.0.10  |
+------------+             +------------+
     |                           |
     |       Load Balancing      |
     -----------------------------
     |       |       |       |
+---------+ +---------+ +---------+
| Backend | | Backend | | Backend |
| Server1 | | Server2 | | Server3 |
+---------+ +---------+ +---------+

Clients connect to a virtual IP (VIP) managed by Keepalived.
HAProxy instances listen on this VIP and distribute traffic to backend servers.
If the master HAProxy node fails, Keepalived promotes the backup node and reassigns the VIP instantly.

Practical guide

This guide is written from the perspective of using a Debian 12 based OS running haproxy/bookworm-backports-2.8,now 2.8.15-1~bpo12+1 amd64 and keepalived/oldstable,now 1:2.2.7-1+b2 amd64 but should still be applicable for any other distribution using similar tooling.

Setting up Keepalived

Install

Ensure that Keepalived is installed on both the primary and backup servers. You can install it using your system's package manager:

For Debian/Ubuntu:

sudo apt install keepalived -y

Primary server

Once installed edit the Keepalived configuration file on the primary server. The default configuration file is usually located at /etc/keepalived/keepalived.conf. Use your preferred text editor to open the file:

# /etc/keepalived/keepalived.conf
global_defs {
    enable_script_security
}

vrrp_script check-script {
   script "/usr/bin/pgrep haproxy"
   interval 2
   user root
}

vrrp_instance haproxy-vip-lc0-haproxy-01 {
    state MASTER
    priority 101
    interface ens18
    virtual_router_id 10

    advert_int 1

    unicast_src_ip 10.1.0.10 dev ens18
    unicast_peer {
        10.2.0.10
    }

    authentication {
        auth_type PASS
        auth_pass vagrant
    }

    virtual_ipaddress {
        10.0.0.100 dev ens18
    }
    track_script {
       check-script
    }
}

Primary server: /etc/keepalived/keepalived.conf

Note for the primary server, the state should be MASTER and priority higher than the secondary server.

Secondary Server(s)

# /etc/keepalived/keepalived.conf
global_defs {
    enable_script_security
}

vrrp_script check-script {
   script "/usr/bin/pgrep haproxy"
   interval 2
   user root
}

vrrp_instance haproxy-vip-lc0-haproxy-02 {
    state BACKUP
    priority 100
    interface ens18
    virtual_router_id 10

    advert_int 1

    unicast_src_ip 10.2.0.10 dev ens18
    unicast_peer {
        10.1.0.10
    }

    authentication {
        auth_type PASS
        auth_pass vagrant
    }

    virtual_ipaddress {
        10.0.0.100 dev ens18
    }
    track_script {
       check-script
    }
}

Secondary server: /etc/keepalived/keepalived.conf

Note for the secondary server, the state should be BACKUP and priority lower than the primary server.

Setting up HAProxy

Installing HAProxy requires a bit of apt repository configuration to get the desired HAProxy 2.8 the Debian site gives a handy helper page which gives instructions for selecting your target OS and version for specific HA Proxy versions, this can be found here: https://haproxy.debian.net/#distribution=Debian&release=bookworm&version=2.8

Once the steps are followed HAProxy 2.8 can be installed as follows

# apt-get update
# apt-get install haproxy=2.8.\*

Once installed you can go ahead and edit the HAProxy config file /etc/haproxy/haproxy.cfg

global
	log /dev/log	local0
	log /dev/log	local1 notice
	chroot /var/lib/haproxy
	stats socket /run/haproxy/admin.sock mode 660 level admin
	stats timeout 30s
	user haproxy
	group haproxy
	daemon

	lua-load /etc/haproxy/cors.lua

	# Default SSL material locations
	ca-base /etc/ssl/certs
	crt-base /etc/ssl/private

	# See: https://ssl-config.mozilla.org/#server=haproxy&server-version=2.0.3&config=intermediate
        ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
        ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
        ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets

defaults
	log	global
	mode	http
	option	httplog
	option	dontlognull
        timeout connect 5000
        timeout client  50000
        timeout server  50000
	errorfile 400 /etc/haproxy/errors/400.http
	errorfile 403 /etc/haproxy/errors/403.http
	errorfile 408 /etc/haproxy/errors/408.http
	errorfile 500 /etc/haproxy/errors/500.http
	errorfile 502 /etc/haproxy/errors/502.http
	errorfile 503 /etc/haproxy/errors/503.http
	errorfile 504 /etc/haproxy/errors/504.http

listen stats
        bind    10.1.0.10:9000
        mode    http
        
        stats   enable
        stats   hide-version
        stats   uri       /
        stats   refresh   30s

frontend web
    bind :80

    acl frontend-ghost hdr_sub(host) -i ghost.atathome.me

    use_backend backend-ghost if frontend-ghost

backend backend-ghost
    server lc0-ghost 10.0.0.1:80 check
    timeout server 30s

/etc/haproxy/haproxy.cfg

This is pretty much the out of the box config with an addition of a sample backend, this should be changed on both the primary and secondary server. Note the listen stats bind address should not be the VIP and be the management IP.

Test and Verify

After configuring Keepalived on both servers, test the configuration for syntax errors:

sudo keepalived -t

If there are no errors, start Keepalived on both servers:

sudo systemctl start keepalived

You can verify the high availability setup by checking the VIP address. On the primary server, the VIP should be active. On the backup server, it should be in a backup state. You can use the following command to check the status:

~# ip a
1: lo:  mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
2: ens18:  mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether bc:24:11:e1:08:40 brd ff:ff:ff:ff:ff:ff
    altname enp0s18
    inet 10.1.0.10/22 brd 10.1.0.255 scope global ens18
       valid_lft forever preferred_lft forever
    inet 10.0.0.100/32 scope global ens18
       valid_lft forever preferred_lft forever

ip a output logs

You should see the VIP address (10.0.0.100 in this example) on the active server and not on the standby server.

Keepalived will automatically manage the failover process. If the primary server goes down or HAProxy becomes unresponsive, the VIP will migrate to the backup server.

If the primary server has not attached the VIP you can debug errors using journal

# journalctl -xefu keepalived
Sep 29 10:35:37 lc0-haproxy-01 Keepalived_vrrp[55583]: Script `check-script` now returning 0
Sep 29 10:35:37 lc0-haproxy-01 Keepalived_vrrp[55583]: VRRP_Script(check-script) succeeded
Sep 29 10:35:37 lc0-haproxy-01 Keepalived_vrrp[55583]: (haproxy-vip-lc0-haproxy-01) Entering BACKUP STATE
Sep 29 10:35:37 lc0-haproxy-01 Keepalived_vrrp[55583]: (haproxy-vip-lc0-haproxy-01) received lower priority (100) advert from 10.2.0.10 - discarding
Sep 29 10:35:38 lc0-haproxy-01 Keepalived_vrrp[55583]: (haproxy-vip-lc0-haproxy-01) received lower priority (100) advert from 10.2.0.10 - discarding
Sep 29 10:35:39 lc0-haproxy-01 Keepalived_vrrp[55583]: (haproxy-vip-lc0-haproxy-01) received lower priority (100) advert from 10.2.0.10 - discarding
Sep 29 10:35:40 lc0-haproxy-01 Keepalived_vrrp[55583]: (haproxy-vip-lc0-haproxy-01) Entering MASTER STATE

Journal logs for keepalived

When successful you should see the message Entering MASTER STATE

Benefits of This Setup

Fault tolerance – no single point of failure at the load balancer layer.
Scalability – distribute traffic across multiple backend servers.
Minimal downtime – failover happens automatically and quickly.
Flexibility – works with web apps, APIs, databases, and more.

Conclusion

By combining HAProxy and Keepalived, you can build a highly available, fault-tolerant, and scalable load balancing infrastructure. HAProxy ensures smart traffic distribution, while Keepalived keeps the load balancer itself redundant and resilient.

Whether you’re running a high-traffic website, an API service, or a critical enterprise application, this duo is a tried-and-true solution for uptime and reliability.