I have been maintaining a git monorepo named docker_templates since sometime in 2023, and I recently added my 200th template (commit 7c112b7)! I thought back to 2015, when I started learning Docker and Docker Compose, and how transformative containers have been in the way I use my machines. There is something very satisfying about describing a runtime you want to work with and encapsulating everything you need to run an app or service the same way each time you run it, on any machine. In reality, there are some edge cases, but it’s a beautiful dream.

The structure of the docker_templates repository continues to evolve, but it’s also come a long way from where it started. I use this repository in some way almost every day. It is the heart of my homelab, and is where I keep references for pretty much every service I’ve stood up on one of my machines. I will now indulge my nostalgia by showing you how the repository has grown over time, how I use it, and share a few of my most useful/favorite containers.

The Beginning: Disparate Directories with Docker Compose Files

I learned to write Dockerfiles to containerize my Python programs, and quickly picked up Docker Compose so I could run things like a Postgres database or Redis message queue (for Python’s Celery scheduling library). Eventually, I started to find programs and apps I wanted to host myself, like a media server, document hosting, monitoring/alerting services, etc.

For years, whenever I wanted to try a new service, I would create a directory for it, write a docker-compose.yml file, and run it. I was hardcoding non-secret values in my Compose files for a long time (using a .env or environment variables to pass secrets to the template). Sometimes I would initialize a git repository and push the stack to Github, other times the directory would just sit on one of my machines wherever I originally put it. The mental overhead of deciding if the new service I wanted to try was worthy of initializing as a git repository, making sure my .gitignore would keep my .env file out of git history and ignore host volume mounts, and deciding where to put the code on my machine started to slow me down and made me hesitant to really invest time into the templates I was creating. I ended up with a lot of different repositories and realized this was not sustainable long-term.

The Monorepo

At some point in 2023, I decided to start a new git monorepo to store all of the services I ran in Docker Compose. I created my docker_templates repository, and one-by-one started copying Compose files I had written into the repository. Pulling everything into one place allowed me to do some cleanup, and made it much easier to start new templates. Whenever I wanted to run a new service, I would clone the repository into a path in my ~/git/ directory, name it after the service, and create the docker-compose.yml file alongside all my other templates in a branch named after the service. Each service existed in an immediate child of the templates/ directory, and over time that path became difficult to sort through.

This worked great for a while, but as I added more and more containers, and thought about all of the templates I planned to add in the future, I realized the structure of the templates/ directory would need to change, and the multiplicative git cloning would end up being a storage problem in the long term. I decided to overhaul the organization of templates in the repository, and write scripts to help me manage the complexity and initialize new templates in a standardized way.

Cookiecutter Templates

When I would start new service templates, I would usually go to a previous template and copy the docker-compose.yml and README.md files into the new path and rewrite them for the new service. I realized I wanted to standardize the way I initialized new template directories. I was familiar with Jinja2 templating from writing Python programs, and had used Cookiecutter in the past to create templated Python project repositories. So I created a standardized Docker Compose service template directory, with a common starting point for all future templates, and a Python script to guide the user through initializing a new template. I am definitely yada-yada-ing a lot of steps I took to get to this point, but after a few iterations, I settled on the template I have been using for the majority of the time this repository has existed.

Each new repository created from the Cookiecutter template starts with the same files:

• .docker-compose.template: An empty marker file for some of the maintenance scripts…I’ll explain more later.
• .env.example: I parameterize my compose.yml files, and provide an example .env file with the defaults for each service.
  • The user is instructed to copy .env.example to .env (which is ignored in the .gitignore for the whole repository) to configure the running stack.
• .gitignore: Template-local ignore pattern overrides.
• README.md: The new_template.py script prompts the user for a title, summary, and optional description, and populates the README file with the user’s inputs.
• compose.yml: The Python script generates a Docker Compose template file with the basic shape defined, so I can just start writing service definitions.

Path Markers

Once the template business was all sorted out, I decided to create subdirectories under the templates/ path that would serve as “categories.” I put my Postgres, Mariadb, Redis, and InnoDB containers under the database/ path, my Plex and Jellyfin servers under media/, Ntfy and Gotify containers under notifications/, and so on. Splitting things up this way made it easier to browse through the containers on the web, and helped to kept the stacks logically sorted by archetype.

In each “category” directory, I created an empty .category file marker. I used the .category and .docker-compose.template files to write scripts that managed some of the complexity in the repository. For example, the count_templates.py script finds all of the .docker-compose.template files in the repository and returns a count, which I use to update the templates count in the repository’s README.md. I wrote a Github workflow to run the script on a schedule, and if the count is different from what’s in the README.md, it updates the Templates:\s*\d+ pattern with the new count.

Repository Map

I also created a repository “map”, a README.md file that finds all of the .category markers and creates a file tree from a README.md Jinja template, and a script to update the map README when new categories are created. The update-repo-map.yml Github workflow also runs nightly to keep this file updated with the latest templates.

Repository Metadata

The scripts that update my README files also write data to the metadata/ directory. This can act as a sort of read-only API using cURL requests. For example, the repository map uses the categories.json file to populate the tree, and all .category and .docker-compose.template markers are in beacons.json. I started calling the marker files “beacons” at one point, and it just kind of stuck.

The metadata files are only really used for rendering README templates, but I have plans for things like a frontend webUI to explore the repository’s templates, and a Go CLI for downloading and using individual templates.

Git Sparse Checkouts

I mentioned earlier that I was cloning the whole repository each time I wanted to run a template I had in docker_templates. This quickly became a problem as the size of the repository grew. The repository is currently 10MB in size (mostly due to image files and some larger files in history that I’ll clean up at some point), so each time I cloned the repository, I added 10MB of disk usage.

I discovered git sparse checkouts when I searched for a solution to this problem. A sparse checkout is a git operation that allows you to checkout only a subset of the files in a repository. When I’m running a Docker Compose template, I don’t need to pull the src/img directory, with the .png I render in the main README.md; I can pull just the files in the Compose template I wish to run.

In practice, most of my sparse checkouts are ~5% of the total size of the repository, which is about the same amount of size they would take as separate git repositories. It adds a few steps to the initial checkout process, but it makes the clone a focused copy with only as much as I need to run.

As an example, if I want to run a Zabbix server container, I would run the following commands:

1
2
3
4
5
6
7
8

$> git clone --no-checkout https://github.com/redjax/docker_templates docker_zabbix
$> cd docker_zabbix
## Initialize sparse checkout
$> git sparse-checkout init --cone
## Tell git which paths to checkout
$> git sparse-checkout set templates/monitoring_alerting/docker_zabbix
## Checkout the main branch, or a working branch for the zabbix server
$> git checkout feat/some-zabbix-feature

This would create a directory named docker_zabbix/, which would have all of the files in the root path, and a single directory named templates/, with monitoring_alerting/docker_zabbix. All of the other containers still exist in the remote, but sparse checkouts let me focus on a single template.

Git Worktrees were not a thing when I started using sparse checkouts. An alternative to the sparse checkout method described above is cloning the whole docker_templates repository once, then creating worktrees for all of the services you want to run. A worktree exists in a separate path on the machine like a sparse clone would. They share the same git object database, meaning paths and objects are deduplicated, which saves space on the disk.

To create a Zabbix server container using a worktree, you would clone the whole repository once, cd into it, then create worktrees for each service you want to run. The limitation here is that each worktree checks out a branch, and only that worktree can use that branch. So, the original repository clone stays on the main branch, and each worktree must have its own branch, even if I’m not making any changes on that service.

1
2
3
4

$> git clone https://github.com/redjax/docker_templates
$> cd docker_templates
$> git worktree add -b feat/zabbix-server ../docker_zabbix
$> cd ../docker_zabbix

I have continued to use sparse checkouts because I often checkout a service and just run it on the main branch until I have updates or fixes to apply, and this flow does not work with worktrees.

How I Use It

I have a full clone of this repository on a few of my machines, which I don’t modify after cloning except to create new templates. When I want to try a new service, I cd into the local clone, create a branch for the new service, and run the new_template.py script, which prompts me for a template name, category, summary, and optional description. I usually add a link of some sort in the summary, i.e. a Github repository or documentation URL.

I commit the files as the initial starting point for that repository and push the branch up to git. Then I do a sparse clone and checkout the new service’s branch, and I get to work building the compose.yml and .env.example. I usually create host volume mounts in the git path, although a better practice would be storing Docker files in another path, like /opt/docker_data or something. The things we wished we learned sooner…

Eventually, when the template is in working condition, I merge the branch into main. As I make changes to the template, I create feat/ and fix/ branches, which also get merged into main. The idea/goal is to be running my services off the stable main branch as often as possible.

Favorite Containers

With some containers, I get them into working order, then bring the stack down and forget about it. I still like having the reference file in my repository, but I might not actively run the container. If it’s in the main branch, it means I got it running at one point and it’s ready to run again.

But there are some templates I am constantly running, or re-using on different machines.

• docker_pangolin: One of the most important services in my stack! Pangolin is my reverse HTTP proxy.
  • I have Pangolin running on a VPS I rent.
  • I route my domain name through Cloudflare, and have Cloudflare pointed at the VPS.
  • In Pangolin, I create subdomain routes to services I want to expose to the Internet, and route the traffic over a private tunnel.
• docker_adguard: I run an AdGuard Home container for ad blocking on my entire LAN.
  • My router uses the AdGuard container as its DNS server.
  • I create records for my important machines, so I can resolve machine-name.home anywhere on my network instead of remembering IP addresses.
• docker_netbird: I use Netbird to run a private network, similar to how many people use Tailscale.
  • I use access policies to allow or restrict traffic between devices, and to give my friends limited access to things like my media and game servers.
• docker_paperless-ngx: Paperless-ngx is an incredibly useful document management system.
  • I upload my receipts, work documents for things like benefits packages and employee handbooks, PDFs, and airline tickets.
  • Daily backups to local and offsite storage prevent data loss (and I’ve had to recover a few times; don’t neglect your backups!).
  • Full-text search lets me find things quickly, and the tagging system lets me sort documents, with tags like receipt, pets, house, vehicle, etc.
• docker_concourse_ci: I use Concourse CI for some of my homelab automation pipelines.
• docker_semaphore: Semaphore lets me run my Ansible roles and playbooks, as well as scheduled Bash scripts and Terraform from a convenient webUI.
• docker_gickup: Gickup is a useful utility for backing up and mirroring git repositories.
  • I keep a config file with all of my most important/valuable repositories, and Gickup runs on a Raspberry Pi, pulling my changes to a local drive and mirroring some to a self-hosted Git instance.
• database: A collection of database templates.
  • I frequently use Postgres and Redis in my homelab, and I use InfluxDB for some of my time-series data like weather readings.
• docker_linkwarden: Linkwarden is a bookmarking/read-it-later app.
  • I imported all of my browser bookmarks when I set it up initially, and I frequently save new links I come across on the web.
  • I can export Linkwarden’s saved links as a bookmarks.html file to synchronize back to my browser.
• docker_forgejo: Forgejo is a self-hosted Git forge, reminiscent of 2015-2018 Github.
  • The Forgejo Actions platform is semi-compatible with Github actions, and Forgejo’s pipelines are very similar in syntax.
  • I host a private/local-only Git forge for some of my more sensitive repositories that I do not want to expose to the Internet.
• docker_opengist: I am a big fan of Github Gists, and discovered OpenGist, which is basically the self-hosted version.
  • I put a lot of code snippets, scripts, and reference files here, and occasionally I will expand a gist into an Obsidian note, or a post on this blog!
• dav: I self-host my contacts and calendars, and synchronize them with my email client.
  • I primarily use Radicale, but have recently been test driving Davis and am liking it a lot.
• games: I host a bunch of game servers for my friends and me. We connect over a private network I host to play.
• monitoring_alerting: I have tried many different monitoring/alerting solutions, and have kept a template for each one in this path.
  • I used Zabbix for a while, but more recently I have used Beszel for server metric monitoring, Uptime Kuma for uptime checks, happyDomain to track and monitor my domains and DNS records, and NtopNG for local network monitoring.
  • I run Uptime Kuma from a VPS so it can watch my homelab for outages.
• docker_ntfy/docker_gotify: My own self-hosted push notification servers.
  • Ntfy and Gotify work very similarly, and I have been test driving both for a while.
  • I can’t decide which one I prefer, and I don’t see much harm in using both.
  • I’ve recently added Apprise into the mix, which lets me send notifications to both services.

Like many people, I am trying to reduce my reliance on Google products. I have not gone as hard as some people, like the users of the DeGoogle subreddit, although I admire their efforts and agree with their philosophy. I have so, so many things tied to the Google/Gmail account I created in 2005. A younger me had no concept of being the product when a service is free, and I foolishly tied so much of my online life to my Gmail account. Extricating is a long, difficult process, and one I’m doing in baby steps.

The AI craze has been just the push I needed to take my privacy more seriously. Companies are changing their Terms of Service, shoving AI hamfistedly into every corner of their product suite, trampling privacy and protection, and will not face any consequences for it in the foreseeable future. While it is too late to keep anything I’ve currently handed over to another entity to hold (like my pictures and personal information), I can limit further damage by pulling my most sensitive pieces of data back under my own control, and my photos felt like a good starting point.

Reasons for Leaving

Google Docs: Gemini features in Photos privacy hub states they do not use your photos to train, but the capability is there and I don’t trust them to resist temptation. And whether or not they directly access my photos, enough of my life is wrapped up in Google’s products that I don’t believe they’d even need direct access to my pictures to abuse my privacy.

There are also horror stories, like the one where a whole house/family lost access to their Google accounts because of 1 user’s data. There is also the fact that Google quietly enabled photo scanning on user devices, and made it opt-out by default, an evil pattern we did not react strongly enough to a decade ago.

Additionally, you could potentially lose access to your account simply because Google decides your pictures are dangerous, without a care for context and with no recourse.

With how sensitive my Google account is, and with how much I currently rely on them, anything I can do to pull my data back into my own control is worth the effort. I researched a few products (hosted and self-hosted, free and paid), and while I did find some promising options, I ultimately settled on 1 self hosted piece of software and a backup plan that I control.

Alternatives to Google Photos

I started by looking into other hosted options, and the only one I would feel comfortable using is Ente photos. Ente is an open source company with a strong focus on privacy. They offer 10GB of free hosting (which is nowhere near enough for my library, but is a generous free tier), and the photos are end-to-end encrypted, meaning they can’t see my photos even if they want to. I am comfortable with that level of control over my own data while hosting it on someone else’s servers. I use some of Ente’s other products and I think they do great work, and for someone who does not want to go through the effort of hosting it themselves, I think Ente is one of the best, most reasonably-priced alternatives to Google Photos there is.

I also evaluated 2 self-hosted solutions: PhotoPrism and Immich. This comparison between self-hosted photo apps came in handy while I was looking over alternatives.

PhotoPrism is more intended for a single user, and for automated/(local) AI-assisted operations on your photos. It has great reviews, it’s been around for a little while and has many users, and setup with Docker looks relatively simple.

Immich can perform many of the same functions as PhotoPrism, automatically recognizing faces and locations, tagging things, sorting by location, etc, but it’s also geared more towards multiple users. And while I am currently the only user of my photo suite, the potential to allow family or friends to host their photos in my library is appealing.

The winner: Immich

Immich is backed by Futo, a company that makes local, privacy-respecting AI tools. They have a host of features I care about, and their Android app works great.

Moving my photos out of Google Photos and into Immich was also relatively painless. Below I detail the steps in detail, but I was able to use Google Takeout to export my photos, and the immich-go CLI to import them into my Immich server. After that, I merely had to install the Immich app, sign into my server, and turn on backups from my phone.

Moving to Immich

I created a Docker Compose template to containerize the application. On a machine where I want to run my Immich stack, I use git’s sparse checkout feature to download only the media/docker_immich directory:

• First, clone the repository without checking out a branch:
  • git clone --no-checkout https://github.com/redjax/docker_templates docker_immich
  • cd docker_immich
• Initialize the sparse checkout: git sparse-checkout init --cone
• Set the checkout path: git sparse-checkout set templates/media/docker_immich
• Checkout the main branch: git checkout main

Bring the whole stack up with:

1
2
3
4
5
6

docker compose \
  -f compose.yml \
  -f overlays/postgres.yml \
  -f overlays/redis.yml \
  -f overlays/caddy.yml \
  up -d

The -f overlays/service-name.yml syntax is for merging Docker Compose files. Running docker compose <command> without any additional -f paths runs only the services in compose.yml. These overlays provide Immich with a database, web server, and cache. If I am using a database or redis cache on another host, I would omit the -f overlays/{postgres,redis}.yml files and provide connection details for the remote.

Export Google Photos

Google offers a feature for exporting your Google Photos (and more account/app data) with Google Takeout. Using this feature, I exported ~200GB of photos and videos I’ve taken over the years into a .zip archive.

Networking

I use Pangolin as a reverse proxy for my services. This allows me to route web traffic incoming to https://immich.mydomain.com to the Immich container running on a machine in my homelab. When protecting my site with Pangolin’s SSO authentication, I found I could not reach the URL when using the Immich Android app. I found this answer on Github that shows the custom request headers required to enable passing an access token.

After setting up Immich as an HTTPS resource in Pangolin, create a shareable link and set the new Immich service as the resource. Set this link to “never expire” for convenience; if you set an expiration date, you will need to update the app with a new link each time it expires.

On the next screen, scroll past the QR code and copy the link below it. This is the link you will provide to the Android app. Click the Usage Examples button and note the P-Access-Token-Id and P-Access-Token values.

You will use this link and the access token to allow the Immich app to communicate with the server behind the Pangolin proxy.

Setup Android App

In the Immich Android app, navigate to Settings > Advanced > Custom proxy headers, and click “Add new header.” Name the header P-Access-Token-Id and paste the value from when you created the token. Create another header named P-Access-Token.

This setup authenticates requests from the Android app to the Pangolin proxy, then passes the traffic to the Immich server.

Upload Photos

I uploaded the collection I exported with Google Takeout to Immich using the immich-go CLI tool. First, I had to create an API key in Immich with the following permissions:

• asset.read
• asset.statistics
• asset.update
• asset.upload
• asset.copy
• asset.replace
• asset.delete
• asset.download
• album.create
• album.read
• albumAsset.create
• server.about
• stack.create
• tag.asset
• tag.create
• user.read
• job.create
• job.read

I also created an admin key in Immich from the administrator account, with full permissions. The immich-go CLI uses the admin token to pause Immich jobs during upload. Othewrise, the regular API key will be used for operations. I created a .env file to store these values:

1
2
3
4

export IMMICH_SERVER_URL=https://photos.mydomain.com
export IMMICH_KEY=<Immich user key>
export IMMICH_ADMIN_KEY=<Immich admin key>
export IMMICH_LOCAL_PHOTOS="/path/to/google-takeout/Takeout/Google Photos/"

I wrote a script so I could repeat this upload process in the future if needed. Before running the script, I source the .env file with . .env, exporting the Immich variables to my environment.

This is the script I used to upload my photos:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100

#!/usr/bin/env bash
set -euo pipefail

if ! command -v immich-go >&/dev/null; then
  echo "[ERROR] immich-go is not installed." >&2
  exit 1
fi

IMMICH_URL="${IMMICH_SERVER_URL:-}"
IMMICH_KEY="${IMMICH_KEY:-}"
IMMICH_ADMIN_KEY="${IMMICH_ADMIN_KEY:-}"
PHOTO_DIR="${IMMICH_LOCAL_PHOTOS:-}"
## Trim trailing slashes
PHOTO_DIR="${PHOTO_DIR%/}"

DRY_RUN="false"

function usage() {
  cat <<EOF
Usage: ${0} [OPTIONS]

Options:
  -h, --help        Print this help menu
  -u, --server-url  Immich server URL
  -k, --api-key     Immich API token
  -K, --admin-key   Immich API token with admin privileges
  -p, --local-path  Path to local photos directory
  --dry-run         Describe actions without taking them
EOF
}

## Parse CLI arguments
while [[ $# -gt 0 ]]; do
  case $1 in
  -h | --help)
    usage
    exit 0
    ;;
  -u | --server-url)
    IMMICH_URL="${2}"
    shift 2
    ;;
  -k | --api-key)
    IMMICH_KEY="${2}"
    shift 2
    ;;
  -K | --admin-key)
    IMMICH_ADMIN_KEY="${2}"
    shift 2
    ;;
  -p | --local-path)
    PHOTO_DIR="${2}"
    shift 2
    ;;
  --dry-run)
    DRY_RUN="true"
    shift
    ;;
  *)
    echo "[ERROR] Invalid arg: $1" >&2
    usage
    exit 1
    ;;
  esac
done

## Validate inputs
[[ -z "${IMMICH_URL}" ]] && echo "[ERROR] Missing --server-url" >&2 && usage && exit 1
[[ -z "${IMMICH_KEY}" ]] && echo "[ERROR] Missing --api-key" >&2 && usage && exit 1
[[ -z "${PHOTO_DIR}" ]] && echo "[ERROR] Missing --local-path" >&2 && usage && exit 1

if [[ ! -d "${PHOTO_DIR}" ]]; then
  echo "[ERROR] Could not find local photos dir: ${PHOTO_DIR}" >&2
  exit 1
fi

cmd=(immich-go upload from-google-photos -s "$IMMICH_URL" -k "$IMMICH_KEY" --on-errors continue)

if [[ -n "${IMMICH_ADMIN_KEY}" ]]; then
  cmd+=(--admin-api-key "${IMMICH_ADMIN_KEY}")
else
  cmd+=(--pause-immich-jobs=FALSE)
fi

## Append photo dir to end of command
cmd+=("$PHOTO_DIR")

if [[ "$DRY_RUN" == "true" ]]; then
  echo "[DRY RUN] Running immich-go in dry-run mode"
  cmd+=(--dry-run)
fi

echo "Starting upload from $PHOTO_DIR to server: $IMMICH_URL"

if ! "${cmd[@]}"; then
  echo "[ERROR] Failed uploading photos" >&2
  exit 1
fi

echo "Upload complete"

If I ever need to re-import my collection, or if I create a new Google Takeout with my photos, I can use this script to upload them to my Immich server. The tool works great, it even imported my albums and all of the EXIF data from Google.

Tradeoffs

Immich feels like a true replacement for Google Photos. The app is familiar enough if you’ve used Google Photos. It has many of the same features, like duplicate and face detection, searches for objects like “dog” or “tree,” and creating shareable links for photos, videos, and galleries. But there are several real tradeoffs you need to be aware of, and risks you need to accept, when moving from a hosted photo provider to your own self-hosted setup.

Security

The first and biggest concern is security. A large company like Google has an interest in protecting what you upload to their servers. While they may use this data in objectionable ways, it is undeniably more secure to entrust your memories to a corporation with a dedicated security team and another team of engineers improving the service over time. While Google is famous for abruptly killing useful services, when you self host your media, you are also responsible for how you expose the server to the world (if you do this at all), and protecting the resources from active and passive attacks, and for ensuring your authentication layer and firewall keep unsavory traffic out of your systems.

Backups

The next important factor to consider is backups. When you host your own media collection, you will want to ensure memories aren’t lost from hardware failures or containerization problems. Keeping backups is crucial, and entirely your responsibility. When backing up important data, you should follow the “3-2-1 backups” principle, which boil down to:

• Keep 3 copies of your data: the original data on your primary device, and at least 2 copies.
• Use 2 different storage devices: a PC, external disk, USB flash drive, NAS or SAN, or cloud storage services; pick any 2.
• Keep 1 backup copy off-site: always have a copy of the backup somewhere other than where all of the main data and backups are. For example, if you are backing up to an external drive and a NAS on your home network, keeping a backup copy in an encrypted S3 bucket will prevent total data loss due to damage that might occur at home, like a fire/flood or heat damage.

This strategy can be intense for a homelab, and it increases the size your collection uses on-disk. I generally keep 1 copy somewhere local (an external drive or my NAS), and upload an encrypted copy to Wasabi cloud storage. If you want to avoid cloud hosting, you could also do a “buddy backup,” which is where you keep a storage device at a “buddy’s” location (a relative or friend’s house, or rented networked storage at a local datacenter, etc).

I use Restic for backups, and which makes it simple to keep a local backup, a backup on another machine on my LAN via Rclone SFTP copy, and a remote copy in pCloud or Wasabi S3.

Maintenance

Finally, there is the maintenance cost to consider. Comparing again to a hosted service, the company will have a dedicated team of engineers responsible for keeping hardware and software up to date, managing storage and quotas, and fixing things when they break. When you self-host, you become a 1-person maintenance team. The upside of choosing your own SLA is that you choose your own SLA; the downside is that shit’s broken until you fix it. And if you experience a hardware failure, you also become the data recovery team. This can be a burden, but tools like Dockhand can simplify maintenance operations.

Conclusion

Pulling my pictures and videos out of Google Photos felt great. I have all of my media on a drive in my house, backed up in multiple places where I feel comfortable I won’t lose my collection due to an errant account ban or deletion, and I know my media isn’t being ingested and mixed training data for an AI to use. I have full control of my media, accepting the tradeoffs in maintenance and backup responsibilities to have freedom from a service I grow continually displeased with, and do not trust to continue providing the service without interruption or deprecation on a whim. And best of all, I no longer need to pay Google a subscription to hold my growing photo collection. Goodbye, Google One!

There are a number of great solutions out there, from Kopia, Duplicati and Borg, to good ol’ rsync and a remote share, and I have tried most of them. Let’s talk about them, and why I ended up using Restic for all of my backups.

The Problem

For a long time, I used Bash scripts scheduled with cron to create .tar.gz archives of important directories in a directory on my machine, i.e. /opt/backups. I eventually started using the rsync CLI tool to copy the backups via SSH to a central machine with a few extra hard drives.

These scripts got unwieldy, and I’ve lost most of them because I was not using version control yet. I also use both Windows and Linux, and translating my backup scripts to Powershell from Bash was good practice, but tedious.

The Journey

I eventually started looking for tools I could install, and was pleased to find a ton of different open source projects with varying approaches to backups. I tried a bunch of them, feeling more and more like Goldilocks as I found one solution too resource intensive, another too complicated, some were too unreliable and others difficult to navigate. In my quest to find the perfect solution for my needs, the following utilities felt closest to my nebulous idea of the perfect solution for my homelab.

Duplicati + Wasabi

I started with Duplicati, which I used to create scheduled backups to my NAS and Wasabi S3 storage. Creating the scheduled jobs was easy, and there is a management webUI that made creating and monitoring the backups pretty easy.

I was able to avert a couple of data loss events by restoring from a Duplicati backup, but I ended up running into database corruption a time or two (a known issue with Duplicati, if you search “Duplicati database corrupted”). You can recover from this state, but after the 2nd time it happened, I started looking for a different solution.

Kopia

I really liked being able to add a Wasabi bucket as one of the backup destinations, and my searches for an alternative to Duplicati eventually lead me to try Kopia. I had read forum posts of people moving to Kopia from Duplicati, and I ran the two side-by-side for a while to get a feel for Kopia.

It did not take long to drop Duplicati entirely. It took me a little while to get used to having only 1 repository for backups, and I never got around to setting up a Kopia server to allow for more. The way I used Kopia was essentially a per-machine repository.

Kopia worked well for me, and I would still recommend it as an option. The UI was the biggest pain point for me: the CLI commands were long and hard to remember, and the webUI was spartan and at times unintuitive.

Borg Backup

I will be honest, I probably didn’t give Borg enough time to write an honest review about it. I started using it essentially in tandem with picking up restic, and quickly gravitated to restic.

I love Borg in theory, it’s a tool known for its relative ease of use and reliability when it comes time to restore from a backup. In comparing Borg and restic, I found a helpful Reddit thread comparing the two tools, and a few of the points were enough for me to move fully to restic. Below are the direct quotes from the post that swayed me (in case the link rots over time):

• Restic’s cryptography is much better because it has been endorsed by one of Google’s cryptography experts that wrote the crypto library for Google’s Go language. He ended up choosing Restic as his personal backup system after the investigation.
• Borg’s cryptography has many security flaws and they’re working on a rewrite of it for the next 1.3+ release named “Helium”. …truncated
  • Borg 2.0 addresses these concerns, but is still in beta as of February 2026 and not recommended for production use.
• Borg requires that the receiver runs Borg on the server, which limits it to rsync.net and borgbase.com for online cloud storage. …truncated
  • Hetzner storage boxes are also supported now, but the number of available backends for Borg is still limited.

Arriving at Restic

As I researched and tried different backup solutions, I kept seeing comments and posts about restic. I learned about people scripting restic with Bash like I had done with rsync.

Restic has powerful deduplication with their Content Defined Chunking (CDC) implementation, leading to smaller backups and better accuracy.

Restic also works with many different backends, and can use Rclone to expand backup destination options even more.

With restic, you create a repository (it’s easy to create and use multiple repositories stored in different backends), point the program at a path, give it an excludes file (or an includes file), and let it rip. It’s pretty much that easy.

I have tested Restic with an external SSD, a directory on another machine (via SSH, facilitated by Rclone), pCloud (also via Rclone), and a Wasabi S3 bucket. Restic does a great job of making all of this feel insignificant and simple; it doesn’t matter if your backup is on the same machine or a cloud bucket in another region of the world, what matters is the contents and integrity of the backup, which Restic handles gracefully.

Restic makes it easy to explore your snapshots, and in my tests restoring data is quick, simple, and “just works.” You can also script Restic operations, although I never dove too deep into this.

Instead, I found two other tools that cemented my choice to use restic for my backups: Resticprofile and Backrest.

Resticprofile

Resticprofile is a wrapper for restic that works by reading backup configurations from a file. You can define defaults, the file supports inheritance, templates, and template variables; you can “group” individual profiles which you can call with resticprofile -n <profile-name>. After defining your backups, you can run resticprofile schedule install to add scheduled tasks (systemd on Linux, Task Scheduler on Windows, Launchd on macOS), which fully automates your backups. It can monitor backup status using a JSON file or by sending metrics to Prometheus.

Restic and Resticprofile being cross-platform, with support for Linux, Windows, and macOS, meant I could use the same app and portions of the same configuration file across my machines. Automating the backups meant I did not have to write custom, per-platform scripts to run the backups on a schedule.

Backrest

I also add Backrest to some of my servers, which provides a webUI I can use instead of logging into the machine directly. Backrest can import and use existing repositories, and the UI allows for the same level of orchestration as resticprofile or the restic CLI. You can browse snapshots and restore files in the webUI, add notifications to Discord, Slack, Gotify, etc, and it has pre/post command hooks to execute shell scripts. I generally use either Backrest or resticprofile on a given machine, as they both serve essentially the same function. But since they can both use the same backend repository, it’s easy to switch them out on demand if I decide I want to manage backups using one or the other.

Backrest also has a Docker container, which makes it a great addition to Docker Compose stacks for automating container data backup.

Conclusion

I was aware of restic for a while before I actually decided to try it, and I can say I wish I had tried this tool sooner. While there’s a slight learning curve, once you get your first backup running, and especially after using a tool to automate the complexity like resticprofile or backrest, it’s clear to me that restic is the perfect combination of user friendliness, security, reliability, and simplicity for a backup solution. I will write another post or two describing how I actually use restic with examples of a resticprofile configuration file and some dos and don’ts.

I also faced some difficulties getting started with the blog. I spent way too much time creating the Github Action that deploys my content to Netlify. I failed so many times before getting it right, I exceeded Netlify’s free tier 🤡. Most of the difficulty actually came from the “extra” functionality with Lychee link checking and Vale linting. Although I was able to get both of these tools running well locally on my machine, I ran into challenges getting them to run in the pipeline.

Linting with Vale was very difficult to nail down. I was able to get it to work reliabily in the local repository, but struggled with containerizing it and running in a pipeline. I also had invalid syntax in my Lychee link scanning for a while. I resolved both issues, but definitely got caught up in the weeds and did not write any new blog posts in the meantime.

I reposted [one of my old blogs from Medium](/posts/linux-frustrated-lovingI don’t), and realized Hugo doesn’t have a great way of centering images. You can use Hugo shortcodes, but those are specific to/dependent on Hugo, and in the interest of keeping the content as decoupled from the site generator as possible, I did not want to invest too heavily in shortcodes. I found a really helpful blog post on ebaddf.net that had a simple, elegant fix that should work across site generators.

It involves creating a custom CSS file, i.e. at static/css/custom.css:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

img[src$='#center']
{
    display: block;
    margin: 0.7rem auto; /* you can replace the vertical '0.7rem' by
                            whatever floats your boat, but keep the
                            horizontal 'auto' for this to work */
    /* whatever else styles you fancy here */
}

img[src$='#floatleft']
{
    float:left;
    margin: 0.7rem;      /* this margin is totally up to you */
    /* whatever else styles you fancy here */
}

img[src$='#floatright']
{
    float:right;
    margin: 0.7rem;      /* this margin is totally up to you */
    /* whatever else styles you fancy here */
}

And embedding images using that class:

1
2
3

![your_img](/img/your_img.png#center)
![your_img](/img/your_img.png#floatleft)
![your_img](/img/your_img.png#floatright)

Getting URL slugs to work for content nested in directories by year (i.e. content/posts/<year>/post-name.md in the source code) to work proved harder than I expected. I wanted to organize the source code for my blogs by year (both as a way to reduce clutter/page loads in Github, and because it’s easier to manage in a code editor), but I wanted the URLs to omit the year (i.e. /posts/post-name without the year).

I tried a few different things:

• Using the cascade configuration option to “collapse” URLs
  • This was supposed to move anything in subdirectories under content/posts/** up to the root posts/ path when building the site.
  • It worked, but it also caused /posts/ to return a 404 error.
• Creating a branch bundle with content/posts/<year>/_index.md.

  • This solution also made use of the cascade option, but in a more targeted way:

    1 2 3 4

    --- cascade: url: "/posts/:slug/" ---

  • I originally used headless: true, but this option contributed to my 404 problem, because I use /posts to aggregate all of my posts.

• Adding a slug to each page.
  • I tried adding slug: "url-slug-i-want". I even added it to my posts archetype
  • This apparently has no effect on bundles.

I found that using a slug to manually set the URL path works well. For some pages, the url option worked better. slug is for overriding the last segment of the path, i.e. /page-name/slug-name, while url gives full control over the URL path, even allowing characters that are reserved by the OS, i.e. adding colons : to a URL like http://example.com/my:example.

If both slug and url are set, the url parameter takes precedence

For posts, this looks like:

1
2
3
4
5
6
7
8

# archetypes/posts.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
slug: "/post-name/optional-sub-post-name"
## Settinng a URL too will override the slug
url: "post-name/optional-sub-post-name"

I am sure there will be many other challenges (for instance, I have not tried changing the blog’s theme yet, and that looks like a whole adventure if you rely on theme features), but the community forums are filled with very helpful threads, and it is relatively easy to find help for Hugo online. It’s a popular tool that’s well documented and has an active community. Some of the challenges I’ve faced are quirks or limitations of Hugo, while some are problems I would have had with any static site generator. I’m overall happy with the Hugo experience.

Tools

I am using Mise to handle installing all of the tools I need to develop/build the blog. The .mise.toml file in the repository defines these tools, so I can simply clone the repository, install Mise, and run mise trust && mise install on a new machine to get up and running. Mise is also useful in container environments and CI/CD pipelines, it can ensure I’m installing the same tools in every environment, with version pinning for ones I want to control upgrades for like the hugo CLI.

Taskfile is a new tool I found that lets you write YAML files to define tasks that can be called with the task CLI. It’s a very versatile tool, and because it uses an embedded shell, it’s (pretty much) fully cross platform. This is very useful, because it means the same tasks can run on Windows, Mac, or Linux, in CI/CD pipelines, Dockerfiles, etc. I use it for simplifying some commands I run frequently, like Docker commands or Hugo commands.

Vale is a utility that lets you define a style guide and lint text content against it. You can use predefined styles, like Microsoft or Google’s, and can mix and match. When Vale runs, it will surface writing and readability issues from the chosen style guides.

Lychee is a fast, easy to use link checker. I found it while setting up this blog, tried it once, and immediately added it to the stack. Lychee can scan live sites/URLs, but can also be pointed at the raw Markdown files that comprise this blog, or the rendered HTML. This allows me to catch broken links on the site before deploying, or to detect linkrot.

While setting up the blog I had to make a number of choices that affect the short and long term health of the blog. Deciding where and how to host the code and the static site, what tooling to add, how to structure the repository, etc.

Git Forge

Spoiler: I went with Github.

I considered many options for where to host the source code for the blog. Github is an obvious frontrunner, partially becaause I am already active on Github, but also the network effect. While I don’t promote my blog, I also like the idea that I’m not just shouting into the void with my posts, and discoverability is best where the people are.

Github hit one billion repositories on June 11, 2025, the first public forge to do so, highlighting the sheer amount of attention and usage on the platform. Most of my coding activity is still on Github (although I mirror many of my repositories to codeberg.org), so anyone stopping by my profile is more likely to find my blog.

One of my concerns while setting up the blog was the ability to quickly and easily move to a new Git host. If I want to move the blog to Gitlab or my own self hosted git forge, I don’t to have to labor to get back up and running. I plan to only dip my toes into a given platform; I will take advantage of some of the features, but will prefer external or embedded solutions for most things (sidenote: I need to find a way to keep issues out of Github.)

And so Github it is, for now.

CI/CD

I spent time planning the structure of the git repository for the blog to make it portable. I have seen a number of blogs switch platforms over the years, and the posts they write at the end of a migration have inspired some of the choices made for this blog.

For example, while this project is hosted on Github and I am using Github Actions to do things like lint the content and publish new pages, I also recreated the functionality in Concourse CI pipelines so I am not tied to a specific git platform. I could move the blog’s repository to any other remote, like Gitlab or Codeberg without breaking my CI/CD. At some point I will probably try writing the pipelines in Dagger to make them truly portable.

I also considered Woodpecker CI, which is a fork of Drone, Crow CI which felt a bit too simplistic, and Komodo. I may still integrate Komodo for GitOps like deploying on specific conditions in a PR.

Hosting

As of 01/24/2026, this blog is hosted on Netlify, a platform I have been looking for a reason to try. I disabled Netlify’s automated rebuilds on merges to main so I could write a deployment pipeline of my own, mainly for the experience, but also to ensure I don’t break the site when I’m trying new things. I hit Netlify’s free tier limit in 2 days because of all the pipeline failures…I mean “tests” that I ran…but the team was generous enough to refresh my credits when I reached out for support. +1 to Netlify!

Because the site is just static HTML/JS/CSS, I leave the option open to move the site’s hosting to basically anywhere. I build a production Docker image, so I could deploy a container somewhere and route the techobyte.cc domain to it, or simply copy the static files to any host that can serve files via a web server. This ensures I won’t get “stuck” with a specific host, or with a specific deployment method. I have heard of many bloggers who run their blogs off a Raspberry Pi they have in their house, and there’s really nothing stopping me from doing the same!

I also evaluated Fly, but decided they were more geared at full blown application deployments, Azure Containers, a Hetzner VPS I would have to maintain, DigitalOcean Droplets, and of course hosting it myself on a machine in my home, behind a reverse proxy.

Theme

This was a tough one… Hugo has a lot of themes. Most of them look good, some of them look great, but I had a few requirements in mind:

• Optimized for text-based posts. Most of my posts will be text-heavy, so optimizing layout for reading was an important factor.
• Simplicity, I didn’t want to use a highly customizable theme that would require a lot of configuration and tweaks.
  • I am aware of my tendency to find yaks to shave, and want to focus on writing.
  • Limiting myself to themes that are opinionated and rigid narrowed the selection pretty significantly.
• As generic as possible. Themes like Blowfish are amazing, but you have to go all-in to really take advantage.
  • I am building this blog for the long term. The ability to switch themes/site generators is highly appealing.
  • The more customization I need to do to the blog, the more I am building the site around the theme rather than the content.
• Content is front and center, no landing pages or superflous sections.
• Support RSS (this is officially supported by Hugo, but some themes handle revealing the functionality to readers better than others).

I decided to start with PaperMod as my theme. While it is kind of opinionated and has some theme-specific configurations, they seem easy enough to “rip out” if I ever want to change it later. It has a light and dark mode, and center-aligns the content for distraction-free reading. RSS setup was easy, and the icon is very obvious on pages that support it.

I decided to finally start my blog, becaause each year that passes where I haven’t joined the ranks of nerd bloggers is another year I can’t look back on in this format.

This blog setup series chronicles the process of getting this blog up and running. I will release posts detailing tools I am using, choices I’ve made during setup, and challenges I faced being new to Hugo, the static site generator I’m using to build the blog. I may retroactively edit pages while the series is in progress.

Posts

• Part 1: Choices Made
• Part 2: Tools
• Part 3: Challenges

Git filter-repo plugin

Install the git-filter-repo plugin for Git with Python:

1

pip install git-filter-repo

This plugin is required to run the git filter-repo command. It is ok to install this using “system Python.”

If you are running Linux, you can install it with apt install -y git-filter-repo (or whatever package manager your distribution uses, i.e. dnf for RedHat/Fedora).

Steps

Clone the repository that has the history you want to rewrite using the --bare flag:

1

git clone --bare git@github.com:user/repo.git

Run the following command to replace all instances of the old/wrong name & email with a different Git user:

1
2
3
4
5
6
7
8

git filter-branch --env-filter '
if [ "$GIT_COMMITTER_NAME" = "Old Name" ] && [ "$GIT_COMMITTER_EMAIL" = "old.email@example.com" ]; then
    GIT_COMMITTER_NAME="New Name"
    GIT_COMMITTER_EMAIL="new.email@example.com"
    GIT_AUTHOR_NAME="New Name"
    GIT_AUTHOR_EMAIL="new.email@example.com"
fi
' --tag-name-filter cat -- --branches --tags

Clean the reflog and run Git garbage collection to remove any cached history with the old Git user:

1
2

git reflog expire --expire=now --all
git gc --prune=now

Finally, force push the changes back to the remote:

1
2

git push --force --all
git push --force --tags

Verify the rewrite succeeded by cloning the repository to a new path and search the log for the old user:

1
2
3
4

mkdir ~/tmp
git clone git@github.com:user/repo.git ~/tmp/repo
cd ~/tmp/repo
git log --author="Old Name"

You should not see any results; if you do, look back through the history of your commands to see if there were any errors during the process.

Bash script

On a Linux or Mac system, you can use this Bash script to automate the steps above. Run the script with --help to see the usage menu.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

#!/usr/bin/env bash
set -euo pipefail

## Find a Python interpreter for pip installs
PYTHON_BIN=""
for bin in python3 python py py3 python; do
  if command -v "$bin" >/dev/null 2>&1; then
    PYTHON_BIN=$bin
    break
  fi
done

## Ensure git-filter-repo is installed (try uv first, then pip)
if ! command -v git-filter-repo >/dev/null 2>&1; then
  echo "git-filter-repo not found."

  ## Install with uv, if available
  if command -v uv >/dev/null 2>&1; then
    echo "uv found. Installing git-filter-repo as a tool..."
    uv tool install git-filter-repo
    export PATH="$HOME/.local/bin:$PATH"
  fi

  if [[ -z "$PYTHON_BIN" ]]; then
    echo "No Python interpreter found. Please install Python or uv."
    exit 1
  fi

  ## Fallback to Python
  echo "Using $PYTHON_BIN to install git-filter-repo via pip..."
  "$PYTHON_BIN" -m pip install --user git-filter-repo
  export PATH="$HOME/.local/bin:$PATH"
fi

## Test git-filter-repo was installed correctly
if ! command -v git-filter-repo >/dev/null 2>&1; then
  echo "git-filter-repo still not found after installation attempts."
  exit 1
fi

## Function to print help menu/usage
usage() {
  echo ""
  echo "Usage: $0 [--force] \\"
  echo "          --repo-url git@github.com:user/repo.git \\"
  echo "          --source-email 'old.email@example.com' \\"
  echo "          --target-email 'new.email@example.com' \\"
  echo "          [--source-name 'Old Name'] \\"
  echo "          [--target-name 'New Name']"
  echo ""

  exit 1
}

## Default vars
REPO_URL=""
SRC_EMAIL=""
TGT_EMAIL=""
SRC_NAME=""
TGT_NAME=""
FORCE_PUSH=""

## Parse arguments
while [[ $# -gt 0 ]]; do
  case $1 in
  --repo-url)
    REPO_URL="$2"
    shift 2
    ;;
  --source-email)
    SRC_EMAIL="$2"
    shift 2
    ;;
  --target-email)
    TGT_EMAIL="$2"
    shift 2
    ;;
  --source-name)
    SRC_NAME="$2"
    shift 2
    ;;
  --target-name)
    TGT_NAME="$2"
    shift 2
    ;;
  --force)
    FORCE_PUSH=1
    shift
    ;;
  -h | --help)
    usage
    ;;
  *)
    echo "Invalid argument: $1"
    usage
    ;;
  esac
done

if [[ -z "$REPO_URL" || -z "$SRC_EMAIL" || -z "$TGT_EMAIL" ]]; then
  echo "Missing required arguments."
  usage
fi

echo "Repo URL: $REPO_URL"
echo "Replacing source email <$SRC_EMAIL> with target email <$TGT_EMAIL>"

if [[ -n "$SRC_NAME" ]]; then
  echo "Source name: $SRC_NAME"
fi
if [[ -n "$TGT_NAME" ]]; then
  echo "Target name: $TGT_NAME"
fi

## Create temporary directory to clone repo into
TMP_DIR=$(mktemp -d)
echo "Mirror cloning repository into temporary directory: $TMP_DIR"
git clone --mirror "$REPO_URL" "$TMP_DIR/repo"
cd "$TMP_DIR/repo"

echo "Rewriting commit history emails with git-filter-repo..."
## Read history with source username/email, replace with target
COMMIT_CALLBACK="
if commit.author_email.decode('utf-8') == '$SRC_EMAIL':
    commit.author_email = b'$TGT_EMAIL'
"
if [[ -n "$TGT_NAME" ]]; then
    COMMIT_CALLBACK+="
    commit.author_name = b'$TGT_NAME'
"
fi

COMMIT_CALLBACK+="
if commit.committer_email.decode('utf-8') == '$SRC_EMAIL':
    commit.committer_email = b'$TGT_EMAIL'
"
if [[ -n "$TGT_NAME" ]]; then
    COMMIT_CALLBACK+="
    commit.committer_name = b'$TGT_NAME'
"
fi

echo "Generated callback:"
echo "$COMMIT_CALLBACK"

## Rewrite history
git filter-repo --force --commit-callback "$COMMIT_CALLBACK"

echo "git filter-repo completed successfully"
echo "Verifying first few commits after rewrite..."
git log --all --pretty=format:"%h %ad %an <%ae>" --date=iso -5

echo "Removing backup refs..."
##  Remove all refs with old data
git for-each-ref --format='%(refname)' refs/original | xargs -r git update-ref -d
git for-each-ref --format='%(refname)' refs/backup | xargs -r git update-ref -d

echo "Expiring reflogs and pruning unreachable objects..."
## Expire old data locally before pushing
git reflog expire --expire=now --all
git gc --prune=now --aggressive

echo "Verifying no lingering commits with source email anywhere..."

## Get list of commits with source email
SOURCE_COMMITS=$(git for-each-ref --format='%(refname)' | while read -r ref; do
  git log "$ref" --pretty=format:"%H%x09%ad%x09%an%x09%ae%x09%cN%x09%cE" --date=iso |
    awk -v src_email="$SRC_EMAIL" '
        $4 == src_email || $6 == src_email {
            print FILENAME "\t" $0
        }' FILENAME="$ref"
done)

## If any commits remain with source email, exit
if [[ -n "$SOURCE_COMMITS" ]]; then
  echo ""
  echo "[ERROR] Some commits still contain the source email <$SRC_EMAIL>:"
  echo ""
  echo -e "Ref\tCommit\tDate\tAuthorName\tAuthorEmail\tCommitterName\tCommitterEmail"
  echo "$SOURCE_COMMITS"
  echo ""
  echo "Aborting push."

  exit 2
fi

echo "Removing local refs under refs/merge-requests/ to avoid push errors..."
## Remove all refs under refs/merge-requests/
git for-each-ref --format='%(refname)' refs/merge-requests | xargs -r -n 1 git update-ref -d || true

echo "Adding remote origin after filter-repo cleanup..."
## Re-add origin (git-filter-repo removes it)
git remote add origin "$REPO_URL"

echo "Pushing all branches and tags to origin forcibly..."
## Push rewritten histories back up
if [[ -n "${FORCE_PUSH:-}" ]]; then
  if ! git push origin --force --all; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi

  if ! git push origin --force --tags; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi

else
  if ! git push origin --force --all; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi

  if ! git push origin --force --tags; then
    echo ""
    echo "[ERROR] Failed to push rewritten commits to origin."

    exit 1
  fi
fi

echo "Successfully rewrote all commits and pushed to remote."
echo "Temporary repo location: $TMP_DIR/repo"

exit 0

Static sites are perfect for many different kinds of websites, from personal blogs like this site to product sites (i.e. Brave browser’s website) to an organization’s home page (i.e. the LetsEncrypt project’s site) to documentation sites (i.e. DigitalOcean’s documentation). With a static site generator, you do not have to deal with web code like HTML or Javascript, but you still have the option of creating your own custom themes if that appeals to you.

When Hugo renders your source code into a website, it outputs everything you need to start serving the site to a public/ directory, allowing you to host the page in Docker, or on a VPS you control, or with a service like Netlify. You could even host your site on a Raspberry Pi you own (although I would recommend looking into running the site in a Docker container, instead of a Canonical Snap). Anywhere that can serve HTML should be able to serve your compiled Hugo website.

This blog will run through the basic steps to initialize a Hugo project, host it on Github, and setup hosting with Netlify.

Requirements

• Hugo
  • You should also pick a Hugo theme, i.e. PaperMod
• Go (optional)
  • You can add themes as a Hugo module instead of using Git submodules.
• Git
• Github account
• Netlify account

Initialize Hugo repository

There are different ways of structuring the repository, like putting the site’s content in a src/ directory or storing multiple Hugo sites in a single monorepo. This guide assumes you follow the default steps for initializing a Hugo project, where all source code is in the “root” of the repository.

First, cd to a path where you want to initialize your Hugo site, i.e. ~/git or just ~/ and initialize the site with:

1

hugo new site <your-blog-name>

Replace <your-blog-name> above with the name of your blog. The documentation uses quickstart as an example. You can name the site whatever you want, and can change it later by editing the hugo.toml/hugo.yml file the hugo new site command creates. When you run the Hugo command, you will see output with some first steps and instructions for editing the hugo.toml to change the site’s configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$> hugo new site your-site-name
Congratulations! Your new Hugo site was created in /home/username/git/your-site-name.

Just a few more steps...

1. Change the current directory to /home/username/git/your-site-name.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

This is an example of the files hugo new site creates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

your-site-name/
├── themes
├── static
├── layouts
├── i18n
├── hugo.toml
├── data
├── content
├── assets
└── archetypes
    └── default.md

Since this blog post is not meant to be an in-depth tutorial of how to build a website with Hugo, we will not go into detail on every single file and folder this command creates, but some important things to know are:

• The themes/ directory is where you store themes added as Git submodules.
  • This guide assumes you are using Hugo modules to install themes, instead of the old Git submodule way, so you will not need to interact with the themes/ directory.
  • This is also where you would store a custom theme, if you wanted to create your own Hugo theme for your site.
• The static/ directory is where you would store static assets for your site, including images and a favicon.ico for the site.
  • Although counter-intuitive, it is generally considered best practice to include the binaries for your static resources in the Git repository.
  • Save your favicon.ico to static/favicon.ico (if you have one), and any images you use in your posts in static/img (this directory doesn’t exist by default, you have to create it).
• The layouts/ directory is where you can create Hugo templates for finer-grained control of how content is displayed on your site.

The hugo.toml file is the main configuration file for your site. If you prefer YAML, you can copy the contents of hugo.toml into convertsimple.com, delete or rename hugo.toml to hugo.yaml/hugo.yml, and paste the converted configuration into the YAML file. Hugo will detect a file named hugo.yml or hugo.toml wherever you run hugo commands from. This guide assumes you are using YAML for your configuration.

1

hugo new site site-name --format yaml

Convert Site to Hugo Module

Next, initialize your site as a Hugo module:

1

hugo mod init github.com/username/your-site-name

After running this, you will see a go.mod file. This allows Go to mannage your site so you can install themes like they are Go packages. For example, to install the PaperMod theme by editing your hugo.yml file and adding the following block of code:

1
2
3

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod

The full hugo.yml should now look like this:

1
2
3
4
5
6
7

baseURL: 'https://example.org/'
languageCode: en-us
title: My New Hugo Site

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod

Run Local Hugo Development Server

Now you can test running the server with hugo serve, which will compile the site and start serving it at http://localhost:1313/ by default. To change the host address, i.e. to access it from another machine on the network, use --bind 0.0.0.0, and to change the port use -p <port>. This is Hugo’s development server. As you edit files, the server will ‘hot reload,’ re-compiling the Markdown you write and restarting the server.

Hugo does this very quickly. Each page takes mere milliseconds to render, even those with images or a lot of text, and it caches between rebuilds, only re-rendering the new content. This leads to a pleasant “change something and see it instantly” writing experience.

If you start the server with -D, Hugo will also render your drafts in the development server.

Git Repository Setup

Run git init -b main in your Hugo site’s directory to initialize a new Git repository. Before committing any code, add a .gitignore that ignores Hugo’s public/ and resources/ directories that it creates when you run the development server:

1
2

/public/
/resources/

Then, do your initial commit:

1
2

git add *
git commit -m "Initial commit"

Create a repository on Github for your Hugo site. This should match the URL you used when you create the Hugo module with hugo mod init github.com/user/your-site-name. Add the remote to your local repository:

1

git remote set origin git@github.com:username/your-site-name.git

And push your code with git push -u origin main.

Netlify Setup

Create an account on Netlify. During the setup process, you will be asked to create a project. Allow Netlify to integrate with your Github and find the repository with your Hugo site. If you already have a Netlify site, add a new project and use “Import an existing project” and find your Hugo repository.

When you are prompted to input build settings like the base directory/package directory, the build command, the publish directory, etc, leave all of these blank. You can optionally leave the functions directory as netlify/functions. If you set values here, the site will fail to build because the hugo.yml interferes with these settings. Do your site configuration in hugo.yml, not Netlify.

When asked which branch to trigger Netlify deploys on, you have a decision to make: do you want your site to deploy every single time you open a PR to the main branch, including times where you are doing small cleanup chores like updating the .gitignore, or setting up a new pipeline? Or do you want to have more control over deploys, i.e. only when merging into a branch named netlify?

I chose the latter, and created a netlify branch, then configured Netlify to deploy from the netlify branch instead of main. I also turned off deployment previews, so any PR into netlify will trigger a deploy.

netlify.toml Config

After finishing the setup, create a netlify.toml file in the root of your Hugo repository :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[build.environment]
HUGO_BASEURL = "https://netlify-project-name.netlify.app"
HUGO_VERSION = "0.152.2"
HUGO_ENV = "production"
NODE_VERSION = "24"
HUGO_ENABLEGITINFO = "true"

[build]
command = "hugo --gc --minify"
publish = "public"

This file tells Netlify how to build your Hugo site. Commit it to git with git add * && git commit -m "Add netlify config" and push to main with git push. Even better, create a new branch before adding/committing your code, i.e. git switch -c feat/netlify-setup, then add the files and commit message. When you push, use git push -u origin feat/netlify-setup. Merge the branch into the main branch in Github.

Example Production Hugo Dockerfile

If you plan to host your Hugo site yourself, you can set up a Dockerfile to build your site and serve it behind a proxy like Caddy or NGINX.

You can use a multi-stage Docker build to have a smaller final image that only has your rendered HTML and the Caddy server to serve it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

FROM hugomods/hugo:exts AS builder

WORKDIR /src

## Copy Hugo site files & config
COPY archetypes/ archetypes/
COPY assets/ assets/
COPY content/ content/
COPY layouts/ layouts/
COPY static/ static/
COPY hugo.yml go.mod go.sum .hugo_build.lock ./

ARG HUGO_BASEURL=http://localhost/

RUN hugo \
  --minify \
  --gc \
  --baseURL="${HUGO_BASEURL}" \
  --destination /output/public

FROM caddy:alpine

COPY --from=builder /output/public /usr/share/caddy

COPY ./Caddyfile /etc/caddy/Caddyfile

EXPOSE 80 443

CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"]

Create a Caddyfile the container will use to configure the Caddy server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  # debug
  email {$CADDY_EMAIL}
}

{$CADDY_SITE_ADDRESS} {
  root * /usr/share/caddy
  file_server
  encode gzip

  header {
    X-Content-Type-Options nosniff
    X-Frame-Options DENY
  }
}

When you build the container, you will need to set environment variables for CADDY_EMAIL (for automated LetsEncrypt SSL certificates) and CADDY_SITE_ADDRESS (for handling connections coming to the Caddy URL). The 2 env vars are “build arguments”, which you can inject in your docker build command using --build-arg ARG_NAME=value. For example, to build this Dockerfile:

1

docker build --build-arg CADDY_EMAIL="youremail@address.com" --build-arg CADDY_SITE_ADDRESS="myblog.com" .

Check Links with Lychee

Lychee is a fast link checker you can use to check your site for broken links. You can install it locally and point it at your live site, or you can run it against the public/ directory after Hugo builds to check your links before deploying.

Lychee’s syntax is simple:

1
2
3
4
5

## Check links on your live site
lychee https://your-site-name.com

## Check links in the public/ directory after a Hugo build
lychee public/

As a Github action:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
name: "Test Blog Links"

on:
  ## Allow manual runs
  workflow_dispatch:
  
  ## Every 6 hours
  schedule:
    - cron: "0 */6 * * *"

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Test live site links
        uses: lycheeverse/lychee-action@v1
        with:
          args: >-
            --base-verification false 
            --no-progress 
            "${{ vars.HUGO_BASEURL }}"/*

Or in a full pipeline that builds the site and then tests the public/ directory (this is useful to do before deploying):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

---
name: "PR checks"

on:
  pull_request:
    branches: [netlify]
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

env:
  HUGO_VERSION: "0.154.3"

jobs:
  test:
    name: Build & test Hugo site
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Vale prose linting
        uses: errata-ai/vale-action@v2.1.1
        with:
          files: '["content/**.{md}"]'

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      - name: Build site
        run: hugo --gc --minify

      - name: Check links with Lychee
        uses: lycheeverse/lychee-action@v1
        with:
          args: "public/**/*.html --base ."
          fail: false

Closing

Building a blog with Hugo is fun, and relatively quick and easy to get up and running. You can build a complex site for your product, or a simple blog you update a couple times a year, all with the same tooling. The minimal amount of configuration you need to get started lends itself to quick development, while still allowing you to build up a more complex configuration over time. Hugo modules make it even easier to install themes and site extensions, and the ability to host the site anywhere that can serve static web files gives you a ton of flexibility to where you put the site online.

This guide did not go in-depth on configuring and customizing Hugo, nor did it walk through creating content for the site. The Hugo quickstart guide will do a better job of walking you through building your first blog, and I highly recommend keeping this site open and using the search bar at the top as you’re learning to find new ways of using Hugo.

I write about tools I use and projects I work on in my homelab, and share the knowledge on this blog. In my free time I like to try new technologies and tools, and I love to share that knowledge with others. I hope the hours I spend struggling on certain things and choose to write about can get you over a hump.

You can subscribe to the RSS feed, a feed of the entire site. Add /index.xml to individual pages/sections on the site to subscribe to content of that type. For example, check the posts feed to see a feed of only the posts made on this site (omitting notes).

Techobyte is a Hugo static site. Feel free to check out the source code for this blog!

I have been very interested in Linux since my entry into the Wonderful World of Unix in 2006. I found Ubuntu and installed it on a crappy Dell desktop computer I was given when I was doing online schooling. The computer originally came with Windows, and one day while I was browsing, I decided to search for “alternative to Windows.” Linux popped up right away. I had never heard of Linux before, but after voraciously reading article after article, I decided Linux was the path for my future.

Like most Linux newbies, Ubuntu was the first distribution I found. Back in 2006, Ubuntu wasn’t ugly, necessarily, but it definitely was not a pretty distribution. When I first found Ubuntu, they were on version 6.10, “Edgy Eft.” My initial thoughts were that their naming convention was stupid (Ubuntu picks an animal for each release and creates an adjective-noun alliteration for it), but it looked interesting, and I decided to try it. I downloaded the image and burnt it to a CD (I’ve since moved to multibooting Linux images from a USB stick), popped it in my CD tray, and jumped straight down the rabbit hole.

I was always interested in computers as a kid, but I had never entered into the world of partition and driver hell that was such a reality back in 2006. When I booted the disk, I was presented with an installer (back then, I believe it was still a command line installer of sorts…it was graphical, but not like today’s installers; there was a lot of room for error). Before I started the installation, I had printed out a “how to install Ubuntu” guide, but I didn’t read very much of it previous to my first attempt. At that point, I had not had much trouble in figuring out how to install, configure, and use software in the Windows world.

During my first attempt, I completely wiped out my Windows partition and deleted everything I had on my computer, because I had no idea what “format” meant, or what a partition even was. I also did not successfully install Linux on my first attempt. I thought I had destroyed my computer.

I had no idea what I did wrong, but I read through the guide I printed, and realized retroactively that I should have done that initially. I learned about partitions, and realized with my skillset, there was no way to get the data I had lost back. I accepted that truth, and realized I had no hope of restoring a Windows install, because I had not been sent a recovery disk with the computer. I wiped the tears off my face and resolved to get Linux installed on my computer, no matter how difficult the task was.

I put the Ubuntu CD I had made back in the tray, cracked my knuckles like I saw people on TV do, and braced for impact. The installation window came back up, and this time, armed with my handy installation guide, managed to install Ubuntu. I didn’t do any fancy partitioning or anything, seems how I had just learned partitioning was even a thing, so Ubuntu was on my entire disk. I booted up my computer, and all was right in the world.

Actually, that’s not the case at all. Back in 2006, Linux was awesome, but had a ton of driver problems. My computer was a low end Dell with an Ethernet driver that was not included in the installation image. After many hours of developing my troubleshooting skills without an Internet connection, I used my brother’s working Windows computer (and I’d be lying if I said I wasn’t envious of his working computer, or that he had not decided to be adventurous with me) to research installing the driver for Ubuntu. I found some documentation for the model of Dell I was using, and found that there were a few other driver problems as well. I downloaded the drivers, put them on a USB stick, and printed the guide for installing the drivers on Ubuntu (what a year 2006 was, where we didn’t have smartphones to just pull up the guides when we needed them. So much wasted paper…).

Let’s recap. At this point, I had a CD burnt with the Ubuntu live image on it, a USB stick with a few drivers, and about 25 pages worth of documentation. I had failed the installation initially, destroyed my Windows partition, lost some data that was pretty important at the time (I had to redo a few assignments), and scared myself a little into thinking Linux might not be for me. Luckily, I am a bit (ok, very) defiant when it comes to computers besting me, and I was not about to let this low end Dell tell me who’s boss. This stupid computer was going to run Linux whether it liked it or not, and based on my experience trying to install Linux and getting the proper drivers, it did not want to run Ubuntu. Tough luck, you stupid Optiplex.

Back to the story! I popped the USB stick into the computer to install the drivers I had found online…only to find that in 2006, Ubuntu did not support FAT formatted drives out of the box. I punched myself in the face in frustration, and went back to my brother’s computer to learn about different file systems. I didn’t understand any of what I was reading, but it boiled down to me learning what the “Format” option does when right clicking a drive on Windows. I formatted the drive, and in my young stupidity, forgot to back up the drivers. After curling up in a ball and rolling around the floor in frustration, on the verge of giving up and accepting that my computer was currently as useful as an uncomfortable footrest, I decided this was all a learning process, and shifting my mentality from “why in the world do so many people love Linux” to “there must be a reason so many people love Linux,” I got back on my brother’s computer, downloaded the drivers again, and took my newly formatted EXT3 drive back to my room. I sat at the computer, prayed to any gods who were listening, and put the USB stick into the slot on my computer.

A wave of relief rushed over me as I saw a neat little animation pop up on my desktop, confirming that my disk had properly mounted (of course, I didn’t know what “mounting” a disk was, but thankfully I didn’t have to play around in my FSTAB file, or else I would probably not be enjoying Linux today, stuck instead with Windows in Microsoft Land). I opened the drive, found my drivers, and moved them to my Downloads folder in Ubuntu. I double clicked them to install, just like you would on Windows, right?

Of course it wouldn’t be that simple! What was I even thinking? Linux is a complex beast, and until you know what you’re doing and see the efficiency, Linux’s simplicity feels like complexity. Through my tears of frustration, I consulted the guide I had printed for installing the drivers on Ubuntu. Some thoughts running through my head while reading were “Shell? Terminal? Why do I have to type something in this weird program, just to install a driver?! What have I gotten myself into…” I decided not to think, and just to follow the guide. I found the Terminal program, opened it up, and noticed it looked a lot like the command prompt on Windows. I previously used the command prompt for the ping command exclusively, because on my Windstream connection (little plug: Windstream sucks. Don’t use.), pinging could help me determine if my computer was the problem, or if our connection was out, and based on past experiences with Windstream, it was usually the latter.

Anyway, with the terminal opened, the guide told me to “cd” to the Downloads folder, and use a command called “chmod +x” to tell the computer the driver files were executable. “Hold up…the computer doesn’t just know I want to run something? I have to actually tell it this file can be executed? Good lord, I hate Linux.” I think that is a more common thought for newbies than people realize/remember. It’s honestly a miracle and a testament to how great Linux is that any converters actually stay with it.

Getting Back on the Internet, and Next Steps

So, my computer was finally ready to install the drivers. I had to type some weird command with a dot in front of it (./[driver name]) to get the driver to install. I later learned that the “./” portion of the command tells the computer to run whatever input you’re giving it through the shell.

A bunch of text started flying through the terminal, and I thought for sure I had either broken my computer again, or that I had learned how to hack, since this is how it looked in the movies. Of course, neither of those scenarios were my reality, but I let the commands run with faith that my computer would not catch fire in front of my eyes.

When the command finally stopped running and the terminal was dutifully waiting for more commands, my network connection icon in the statusbar started spinning, and I got a little popup that my network connection was active. I sat stunned for a minute that I’d Forrest Gump’d my way into a working Linux installation. I opened an Internet browser (I had been using Firefox on Windows, so this was one thing I was familiar with in this new land), went to Google, and danced with joy that I had a working Internet connection.

I could go into more detail about the troubles I had learning Linux, but suffice it to say, learning Linux coming from never even hearing about it before was a long, arduous process of trial and extremely frustrating error. The thought of adjusting to the command line alone was daunting enough to keep me wondering if I had made a huge mistake, but after a couple days of using Ubuntu, I was captivated by the uniqueness and simultaneous familiarity. I love change, and I love experimenting with computers, and this was a whole new world for me. I got comfortable with the command line, and found it to be far superior to the click and drag interface I was used to, although people new to Linux will be happy to hear you can do pretty much everything graphically, especially on Ubuntu. No scary terminal window necessary!

My Time with Linux Since Then

It didn’t take me very long to learn that Linux was just the core of the operating system, and there were loads of different “flavors,” or “distributions,” of Linux. I had started on Ubuntu, which I learned was an offshoot of the great Debian distribution, plus a few enhancements. Once I traced Ubuntu’s roots back to Debian, I found that there were many, many different offshoots of Debian, and even some that came from Ubuntu. The more I searched, the more I found that Linux is one hell of an ecosystem, with distributions for just about anything you can want. There are distributions crafted to be run solely as a server; distributions that value security and stability over cutting edge technology; distributions like Arch Linux that are always up to date, to the point of being unstable at times; and distributions with a nice mix of stability and freshness, like Fedora.

I decided to try Fedora out, and found that Gnome 3 looked much nicer than Ubuntu’s desktop, which was based on the older Gnome 2. Ubuntu eventually created their own entirely unique environment, called Unity, and caused quite a divide in the community: some people loved the fresh, unique take on the desktop, and some people despised the fact that Ubuntu tried to pigeon hole them into change. One thing I’ve learned about the Linux community is that people really, really value their freedom of choice, and when a distribution makes an executive decision, they will hear loud and clear the displeasure of the people they pissed off.

Since trying Ubuntu and Fedora out, I have become what the community dubbed a “distro hopper.” Distro hoppers want to get their feet wet with as many distributions as they can find. I’ve tried ’em all, starting with Ubuntu, moving to Fedora, and from there travelling swiftly through Linux Mint, to Debian when I felt I had learned enough about Linux to try the mother distribution; I tried ZorinOS because it promised to be familiar to people coming from Windows, and they were right; I installed openSUSE because I liked the green lizard, but I eventually made my way back to Debian-land and settled on Linux Mint. It felt fresh and clean, but still offered the simplicity and idiot-proof nature of Ubuntu. I stuck with Mint for a long time, but eventually the itch hit me again, and I started hopping around.

When I got bored of the safeness of Linux Mint, I branched out into fringe and new distributions. I found elementaryOS, which was, at the time, a very new branch from Ubuntu. Its main offering was a positively gorgeous interface, taking obvious inspiration from Apple’s Mac OS X (they deny that they were inspired by Apple’s OS, but it’s pretty apparent to anyone that they at least valued OS X’s clean, consistent interface and color scheme). I bounced from elementaryOS over to DeepinOS, which is a Chinese distribution that’s doing a lot of new and exciting things to the Ubuntu desktop world.

Eventually I got tired of hopping around and not finding the one distribution that fit all my needs. I wanted something that was stable, had up to date packages so I could try new things, was easy to manage, and was modifiable in a way I had not found yet. I am a compulsive modder, changing things just for the sake of change. I had heard of Arch Linux, a distribution that the community likes to tout as “for hardcore users only.” There is surely a steep learning curve, but the documentation and community is so passionate about their distribution that the entire process of installing and maintaining an Arch Linux install is very demystified at this point. I had read about how customizable Arch Linux is, and decided this was surely the next step in my journey.

I downloaded the net install (a very small image that requires you to be connected to the Internet, where it then downloads the rest of the installation) and set to work. And good lord did I mess a lot of things up. Setting Arch Linux up is to this day one of the hardest, most time consuming, and frustrating things I have ever done. It took me weeks to get a working installation. After failing the first 5 times, I decided to try in a virtual machine. I would go through the Arch installer, get a system up and running, delete the virtual machine, and try again. I probably did this 20 times before I felt comfortable trying again on my computer.

And I still failed. I’ve only ever had 1 working Arch install, and at that point I was too scared to mess with it and screw things up even more. I read around, and a lot of people suggested Antergos, which is essentially a simple, graphical installer for Arch Linux that adds a repository for themes.

The Cnchi graphical installer for Antergos was beautiful, and worked like a charm. I had a working Arch Linux install on my computer within 15 minutes. And as it turns out, Arch Linux is the absolute perfect distribution for me. It’s stable, it’s faaaast, it’s customizable beyond belief, and most importantly for me, it’s as up to date as you can be. As soon as a program is updated, it gets added to Arch Linux’s central repository, or its indescribably useful User Repository (AUR), and you can download it with a simple pacman -S command. I could write a whole post about my journey with Antergos, and perhaps I will…but for now, suffice it to say I had found my home.

With Arch Linux, I had everything I wanted. No more distro hopping to get a package update I wanted, or a theme that only worked with a certain base (Debian or Redhat, for instance). No more obliterating my installation with a simple update, which happened far too frequently in my time with openSUSE. Antergos was it for me. I grew to love how configurable it was, which initially was a very daunting task (pretty much everything is configured through the command line by editing text files).

Where I Am Now with Linux

This post is getting long, as I forgot how passionate I am about Linux until I took this nostalgic trip down Linux-Hell memory lane.

Since I first accidentally wiped out my Windows installation, I have been treading deeper and deeper into the Linux forest. I have learned more about computers and their inner workings in my ~10 years with Linux than I ever knew with a Windows installation. I have lost data, formatted my hard drive every which way hundreds of times, found new uses for Linux in my everyday life, and set up my own home server using an ESXi host running a few Linux virtual machines (another post for another time).

I took the plunge and decided to use Linux as my main operating system a couple years ago, booting into Windows infrequently to use a couple of programs I simply can’t use to their full potential in Linux (namely FL Studio and a couple of Windows only games). It’s true that at first, Linux is scary. You have to learn the command line if you want to do anything besides basic Internet browsing and word processing; you have to read a lot of documentation and forum posts to learn how you stupidly messed up your installation, and you have to develop a tough skin to deal with the community, which is made up of some really grumpy old timers and a disproportionately large group of newcomers who ask a lot of questions. It’s a testament to Linux’s greatness that so many people put up with all of that, just to use the operating system on their computer.

Because of my love for Linux, I am now working towards learning what I need to learn to become a Linux Systems Administrator, where I will get to work with Linux computers and servers for a living, and learn even more about this wonderful software project that has broken so much ground over the years. I’m sure there will be many more long nights spent figuring out where I went wrong in an update, or why my configuration files aren’t working as intended, but I look forward to being tired the next day from staying up too late playing on my computer, feeling satisfied that I fixed whatever went wrong, and that I am still loving the Linux Life.