Forem: Danylo Mikula

Building My Personal Website: From Idea to Automated Deployment (Part 2)

Danylo Mikula — Thu, 04 Dec 2025 15:50:39 +0000

In the first part of this series, I covered the high-level architecture and the tools I chose for building my personal website. Now let's dive deeper into the technical implementation, starting with the Terraform modules.

Infrastructure Overview

To deploy the minimal infrastructure with everything needed on Hetzner Cloud, we need to configure the following components:

Network — private network for internal communication
Firewall — security rules to restrict traffic
SSH Key — authentication for server access
Server — the actual compute instance

I created Terraform modules for each of these components. Let's go through them one by one.

Network Module

The first piece of infrastructure we need is a private network. For this, I created the terraform-hcloud-network module.

This module provides comprehensive network management for Hetzner Cloud:

Optional creation of a new network or reuse of an existing one
Support for multiple subnets across different network zones and types (server, cloud, or vswitch)
Optional custom routes for advanced scenarios like VPN gateways
Consistent outputs for easy integration with other modules

Here's my network configuration:

module "network" {
  source  = "danylomikula/network/hcloud"
  version = "1.0.0"

  create_network = true
  name           = local.project_slug
  ip_range       = "10.100.0.0/16"

  labels = local.common_labels

  subnets = {
    web = {
      type         = "cloud"
      network_zone = "eu-central"
      ip_range     = "10.100.1.0/24"
    }
  }
}

I chose the eu-central network zone because it offers the best pricing. This configuration creates a network with a /16 CIDR block (10.100.0.0/16) and a single subnet with a /24 block (10.100.1.0/24). For a single server, this is more than enough address space.

Firewall Module

Next, we need to set up a firewall to restrict external traffic. As I mentioned in the first part, I only allow HTTP/HTTPS traffic from Cloudflare IP addresses and SSH access from my home IP.

For this, I created the terraform-hcloud-firewall module. It supports:

Creating multiple firewalls with custom rules
Both inbound and outbound rules
Flexible port and IP restrictions
Common labels across all firewalls

Here's my firewall configuration:

module "firewall" {
  source  = "danylomikula/firewall/hcloud"
  version = "1.0.0"

  firewalls = {
    "${local.resource_names.website}" = {
      rules = [
        {
          direction   = "in"
          protocol    = "tcp"
          port        = "22"
          source_ips  = [var.my_homelab_ip]
          description = "allow ssh"
        },
        {
          direction   = "in"
          protocol    = "tcp"
          port        = "80"
          source_ips  = local.cloudflare_all_ips
          description = "allow http from cloudflare"
        },
        {
          direction   = "in"
          protocol    = "tcp"
          port        = "443"
          source_ips  = local.cloudflare_all_ips
          description = "allow https from cloudflare"
        },
        {
          direction   = "in"
          protocol    = "icmp"
          source_ips  = ["0.0.0.0/0", "::/0"]
          description = "allow ping"
        }
      ]
      labels = {
        service = "firewall"
      }
    }
  }

  common_labels = local.common_labels
}

Dynamic Cloudflare IP Fetching

Cloudflare publishes their IP ranges publicly, so I fetch them dynamically using Terraform's http data source:

data "http" "cloudflare_ips_v4" {
  url = "https://www.cloudflare.com/ips-v4"
}

data "http" "cloudflare_ips_v6" {
  url = "https://www.cloudflare.com/ips-v6"
}

locals {
  cloudflare_ipv4_cidrs = split("\n", trimspace(data.http.cloudflare_ips_v4.response_body))
  cloudflare_ipv6_cidrs = split("\n", trimspace(data.http.cloudflare_ips_v6.response_body))
  cloudflare_all_ips    = concat(local.cloudflare_ipv4_cidrs, local.cloudflare_ipv6_cidrs)
}

This approach ensures that whenever Cloudflare updates their IP ranges, a simple terraform apply will update the firewall rules automatically.

Important: For this setup to work, you need to enable the Proxy toggle on your A and AAAA records in Cloudflare DNS settings.

SSH Key Module

Before creating the server, we need an SSH key for authentication. I created the terraform-hcloud-ssh-key module for this purpose.

This module is quite flexible and supports:

Automated key generation (ED25519, RSA, or ECDSA)
Automatic local save of generated keys
Uploading existing public keys
Referencing keys already in Hetzner Cloud by ID or name

Here's my configuration:

module "ssh_key" {
  source  = "danylomikula/ssh-key/hcloud"
  version = "1.0.0"

  create_key = true
  name       = local.project_slug

  save_private_key_locally = true
  local_key_directory      = path.module

  labels = local.common_labels
}

This generates an ED25519 key pair (the default and recommended algorithm) and saves both the private and public keys locally for easy access.

Server Module

Finally, let's create the server itself using the terraform-hcloud-server module. Like the others, it's designed to be flexible and supports:

Multi-server management with a single module invocation
Private network attachments with static IPs
Firewall integration at creation time
Placement groups for high availability
All hcloud_server resource attributes

Here's my server configuration:

module "servers" {
  source  = "danylomikula/server/hcloud"
  version = "1.0.0"

  servers = {
    "${local.resource_names.website}" = {
      server_type  = "cx23"
      location     = "hel1"
      image        = data.hcloud_image.rocky.name
      user_data    = local.cloud_init_config
      ssh_keys     = [module.ssh_key.ssh_key_id]
      firewall_ids = [module.firewall.firewall_ids[local.resource_names.website]]
      networks = [{
        network_id = module.network.network_id
        ip         = "10.100.1.10"
      }]
      labels = {
        service = "website"
      }
    }
  }

  common_labels = local.common_labels
}

I chose the cx23 server type as it's the cheapest option available and costs me less than $5 per month in the Helsinki (hel1) region. Its specifications are more than enough for a static website.

Notice how I'm passing variables from previous modules dynamically — the SSH key ID, firewall ID, and network ID are all referenced from their respective module outputs. This eliminates manual configuration and reduces the chance of errors.

Complete Configuration

Here's the full Terraform configuration with all the pieces together:

locals {
  project_slug = "mikula-dev"

  common_labels = {
    environment = "production"
    project     = local.project_slug
    managed_by  = "terraform"
  }

  resource_names = {
    website = "${local.project_slug}-web"
  }

  cloud_init_config = templatefile("${path.module}/cloud-init.tpl", {
    ansible_ssh_public_key = var.ansible_user_ssh_public_key
  })

  cloudflare_ipv4_cidrs = split("\n", trimspace(data.http.cloudflare_ips_v4.response_body))
  cloudflare_ipv6_cidrs = split("\n", trimspace(data.http.cloudflare_ips_v6.response_body))
  cloudflare_all_ips    = concat(local.cloudflare_ipv4_cidrs, local.cloudflare_ipv6_cidrs)
}

# Fetch Cloudflare IP ranges for firewall rules
data "http" "cloudflare_ips_v4" {
  url = "https://www.cloudflare.com/ips-v4"
}

data "http" "cloudflare_ips_v6" {
  url = "https://www.cloudflare.com/ips-v6"
}

module "network" {
  source  = "danylomikula/network/hcloud"
  version = "1.0.0"

  create_network = true
  name           = local.project_slug
  ip_range       = "10.100.0.0/16"

  labels = local.common_labels

  subnets = {
    web = {
      type         = "cloud"
      network_zone = "eu-central"
      ip_range     = "10.100.1.0/24"
    }
  }
}

module "ssh_key" {
  source  = "danylomikula/ssh-key/hcloud"
  version = "1.0.0"

  create_key = true
  name       = local.project_slug

  save_private_key_locally = true
  local_key_directory      = path.module

  labels = local.common_labels
}

module "firewall" {
  source  = "danylomikula/firewall/hcloud"
  version = "1.0.0"

  firewalls = {
    "${local.resource_names.website}" = {
      rules = [
        {
          direction   = "in"
          protocol    = "tcp"
          port        = "22"
          source_ips  = [var.my_homelab_ip]
          description = "allow ssh"
        },
        {
          direction   = "in"
          protocol    = "tcp"
          port        = "80"
          source_ips  = local.cloudflare_all_ips
          description = "allow http from cloudflare"
        },
        {
          direction   = "in"
          protocol    = "tcp"
          port        = "443"
          source_ips  = local.cloudflare_all_ips
          description = "allow https from cloudflare"
        },
        {
          direction   = "in"
          protocol    = "icmp"
          source_ips  = ["0.0.0.0/0", "::/0"]
          description = "allow ping"
        }
      ]
      labels = {
        service = "firewall"
      }
    }
  }

  common_labels = local.common_labels
}

module "servers" {
  source  = "danylomikula/server/hcloud"
  version = "1.0.0"

  servers = {
    "${local.resource_names.website}" = {
      server_type  = "cx23"
      location     = "hel1"
      image        = data.hcloud_image.rocky.name
      user_data    = local.cloud_init_config
      ssh_keys     = [module.ssh_key.ssh_key_id]
      firewall_ids = [module.firewall.firewall_ids[local.resource_names.website]]
      networks = [{
        network_id = module.network.network_id
        ip         = "10.100.1.10"
      }]
      labels = {
        service = "website"
      }
    }
  }

  common_labels = local.common_labels
}

With this configuration, running terraform apply provisions the complete infrastructure in just a few minutes.

Server Bootstrapping with Ansible

Now let's look at bootstrapping the actual website. For this, I'm using an Ansible collection that I also created and published publicly: ansible-hugo-deploy.

For the operating system, I chose Rocky Linux 10. For the web server — Caddy.

The Ansible collection handles the complete deployment pipeline:

Hugo Static Site Deployment — automated cloning and building of Hugo websites
Custom Caddy Build — compiles Caddy with custom plugins from source
SSL/TLS Automation — automatic HTTPS certificates via Let's Encrypt with Cloudflare DNS challenge
Built-in Rate Limiting — protection against bots and abuse
Cloudflare Integration — DNS-01 ACME challenge support
GitHub Deploy Key Generation — automatic SSH key generation for secure repository access
Automated Updates — systemd timer for periodic Git pulls and site rebuilds
Firewall Configuration — automated firewalld setup with sensible defaults
Version Pinning — full control over Hugo, Caddy, and Go versions

My Ansible Configuration

Here's my complete configuration:

---
# Domain configuration.
domain: "mikula.dev"
admin_email: "admin@{{ domain }}"

# Git repository for website source.
website_repo_url: "git@github.com:danylomikula/mikula.dev.git"
website_repo_branch: "master"

# Web content paths.
website_root: "/var/www/{{ domain }}"
caddy_log_path: "/var/log/caddy"
website_public_dir: "{{ website_root }}/public"

# Deploy SSH key configuration.
deploy_ssh_key_user: "caddy"
deploy_ssh_key_group: "{{ deploy_ssh_key_user }}"
deploy_ssh_key_dir: "/var/lib/{{ deploy_ssh_key_user }}/.ssh"
deploy_ssh_key_path: "{{ deploy_ssh_key_dir }}/deploy_key"
deploy_ssh_key_type: "ed25519"
deploy_ssh_key_comment: "{{ domain }}-deploy-key"

# Website rebuild configuration.
webrebuild_schedule: "*-*-* 04:00:00"
webrebuild_boot_delay: "180"
webrebuild_service_user: "caddy"
webrebuild_service_group: "caddy"
webrebuild_commands:
  - "git pull origin {{ website_repo_branch }}"
  - "hugo --gc --minify"

hugo_version: "0.152.2"

# Caddy configuration.
caddy_version: "2.10.2"
caddy_go_version: "1.25.4"
caddy_modules:
  - github.com/mholt/caddy-ratelimit
  - github.com/caddy-dns/cloudflare

caddy_rate_limit:
  enabled: true
  events: 60
  window: "1m"

caddy_compression_formats:
  - gzip
  - zstd

# DNS / ACME configuration.
cloudflare_api_token: "{{ vault_cloudflare_api_token }}"
caddy_acme_ca: "https://acme-v02.api.letsencrypt.org/directory"

# Firewall configuration.
firewall_zone: "public"
firewall_allowed_services:
  - ssh
  - http
  - https
firewall_allowed_ports: []
firewall_allowed_icmp: true
firewall_allowed_icmp_types:
  - echo-request

Custom Caddy Build with Plugins

Since I'm using Cloudflare with proxy enabled, the standard Caddy build isn't enough for automatic certificate provisioning. I need the caddy-dns/cloudflare module to pass the DNS-01 ACME challenge for certificate verification.

Since I'm already building a custom Caddy binary, I decided to add another useful module — caddy-ratelimit for rate limiting protection against bots and scanners.

The configuration for these modules is available in my Ansible playbook. If you don't want to use one of them or want to add additional modules, you can easily customize the caddy_modules list.

Automated Content Updates

We can now deploy the website, but one problem remains: how do we update the content automatically without manually logging into the server? I want to simply push to Git and have the website update itself after some time.

To solve this, I'm using GitHub deploy keys. These keys are read-only, meaning all they can do is read the content of the Git repository — nothing more.

The Ansible playbook generates this key automatically, outputs the public part to the console, and waits for your confirmation while you configure your GitHub repository. After confirmation, it clones the content, builds it, and starts the Hugo server.

systemd Timer for Periodic Updates

For periodic content updates, I use a simple systemd timer that runs every morning and updates the website with new content.

webrebuild.service:

[Unit]
Description=Rebuild website from Git repository
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User={{ webrebuild_service_user }}
Group={{ webrebuild_service_group }}
WorkingDirectory={{ website_root }}
Environment=PATH={{ caddy_webserver_rebuild_path }}
{% for command in webrebuild_commands %}
ExecStart=/usr/bin/env bash -c "{{ command }}"
{% endfor %}
StandardOutput=journal
StandardError=journal

webrebuild.timer:

[Unit]
Description=Rebuild website daily
RefuseManualStart=no
RefuseManualStop=no

[Timer]
# Run {{ webrebuild_boot_delay }} seconds after boot for the first time.
OnBootSec={{ webrebuild_boot_delay }}
# Run daily at scheduled time.
OnCalendar={{ webrebuild_schedule }}
Unit=webrebuild.service

[Install]
WantedBy=timers.target

With this setup, every morning at 4:00 AM the timer triggers, pulls the latest changes from the repository, and rebuilds the site with Hugo. If I need an immediate update, I can always trigger it manually with sudo systemctl start webrebuild.service.

Caddyfile Configuration

The Caddy server is configured using a config file called Caddyfile. Here's the complete template:

# Caddyfile for {{ domain }}
# Managed by Ansible - do not edit manually.

{% if (cloudflare_api_token | length > 0) or (caddy_acme_ca | length > 0) %}
{
{% if caddy_acme_ca | length > 0 %}
    acme_ca {{ caddy_acme_ca }}
{% endif %}
{% if cloudflare_api_token | length > 0 %}
    acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
{% endif %}
}
{% endif %}

www.{{ domain }} {
    # Redirect www to non-www domain.
    redir https://{{ domain }}{uri} permanent
}

{{ domain }} {
    # Root directory for static files.
    root * {{ website_public_dir }}

    # Enable static file server.
    file_server

{% if caddy_rate_limit.enabled | default(false) %}
    # Basic rate limiting per client IP to slow down bots/scanners.
    rate_limit {
        zone per_client {
            key {remote_ip}
            events {{ caddy_rate_limit.events }}
            window {{ caddy_rate_limit.window }}
        }
    }
{% endif %}

    # Enable compression.
    encode {% for format in caddy_compression_formats %}{{ format }} {% endfor %}

    # TLS configuration with admin email.
    tls {{ admin_email }}

    # Access logging.
    log {
        output file {{ caddy_log_path }}/access.log {
            roll_size 100MiB
            roll_local_time
            roll_keep_for 15d
        }
    }

    # Security headers.
    header {
        Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com https://static.cloudflareinsights.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https://static.cloudflareinsights.com; font-src 'self' data:; frame-ancestors 'none'; object-src 'none'; base-uri 'self'; form-action 'self'; connect-src 'self' https://www.google-analytics.com https://www.googletagmanager.com https://static.cloudflareinsights.com https://cloudflareinsights.com"
        Referrer-Policy "strict-origin-when-cross-origin"
    }
}

This configuration includes:

www to non-www redirect — all traffic to www.mikula.dev is permanently redirected to mikula.dev
Static file serving — serves files from the Hugo build output directory
Rate limiting — limits requests per client IP to protect against abuse
Compression — gzip and zstd compression for better performance
Automatic TLS — certificates via Let's Encrypt with Cloudflare DNS challenge
Access logging — with automatic log rotation
Security headers — HSTS, CSP, and other security-related headers

Conclusion

That's it! With this setup, I can deploy a fully functional, secure, and automated website infrastructure in about 15 minutes. The entire workflow is:

Run terraform apply to provision the infrastructure
Push content to the repository
Run the Ansible playbook to configure the server
Add the deploy key to GitHub

From that point on, the website updates itself automatically every day.

I hope this guide helps you set up your own website even faster than I did. Feel free to use my ready-made configurations as a starting point.

All the code is open source:

Terraform Modules:
Ansible Collection:
- ansible-hugo-deploy

Have questions or suggestions? Feel free to reach out or open an issue on GitHub.

Building My Personal Website: From Idea to Automated Deployment (Part 1)

Danylo Mikula — Fri, 28 Nov 2025 21:58:57 +0000

The idea of creating my own personal website—a place where I could share projects I'm working on and document my technical journey—has been on my mind for a long time. But as with many personal projects, it kept getting pushed aside. Finally, I found the time, and here it is: mikula.dev. In this post, I want to share how I built it, what tools I chose, and why.

Choosing the Right Static Site Generator

When looking for a site generator, I had a few requirements in mind: it needed to be simple yet flexible, fast, and shouldn't require hours of configuration just to get started. After evaluating several options, I settled on Hugo.

Hugo is one of the fastest static site generators out there. Written in Go, it can build thousands of pages in seconds. But speed isn't the only advantage—it generates pure static HTML files, which makes hosting incredibly straightforward. No databases, no server-side processing, no complex runtime dependencies. Just files that can be served by any web server.

The fact that Hugo outputs static files also brings security benefits—there's simply no dynamic attack surface. Combined with its extensive templating capabilities and active community, it was an easy choice.

Finding the Perfect Theme

I didn't want to spend weeks developing my own theme from scratch. Instead, I looked for something that matched my aesthetic preferences and could be customized easily. I found Terminal by Radek Kozieł, and it was exactly what I was looking for.

The theme has a clean, retro terminal-inspired look with beautiful syntax highlighting powered by Chroma. It uses Fira Code as the default monospace font, is fully responsive, and supports customizable color schemes. While it covered most of my needs out of the box, I did extend it with some additional functionality—like better post organization and a dedicated resume page.

Where to Host?

Since Hugo generates static files, I had several hosting options to consider: GitHub Pages, AWS S3 with CloudFront, or a small cloud server. Each has its merits, but I went with a dedicated server on Hetzner Cloud.

Why? Flexibility. While GitHub Pages and S3 are excellent for simple static hosting, having my own server gives me complete control over the infrastructure. I can configure custom caching rules, set up rate limiting, add custom header and run additional services if needed. Plus, Hetzner offers excellent performance at very competitive prices.

Caddy: The Modern Web Server

For the web server, I evaluated a few options—nginx, Apache, and Caddy. I chose Caddy for several compelling reasons.

First, automatic HTTPS. Caddy handles SSL certificate provisioning and renewal through Let's Encrypt completely automatically. No more manual certificate management, no cron jobs for renewal, no forgetting to renew and having your site go down. It just works.

Second, simplicity. Caddy's configuration format (the Caddyfile) is remarkably straightforward compared to nginx or Apache configurations. A basic site configuration can be just a few lines, yet it still offers powerful customization options when you need them.

I'm also using a custom Caddy build with additional plugins: caddy-dns/cloudflare for DNS-01 ACME challenges (so I can get certificates even before DNS propagation completes) and caddy-ratelimit to protect against bots and abuse.

DNS and Security with Cloudflare

For DNS management, I'm using Cloudflare. But it's not just about DNS—I have Cloudflare Proxy enabled, which means all traffic to my site goes through Cloudflare's network first. This provides several benefits: DDoS protection, CDN caching, and most importantly, it hides my server's real IP address from the public.

To take security a step further, I configured firewall rules directly in Hetzner Cloud to only allow incoming HTTP/HTTPS traffic from Cloudflare's IP ranges. This means even if someone discovers my server's actual IP address, they can't connect to the web server directly—all requests must go through Cloudflare. This setup effectively creates an additional security layer and ensures that all traffic benefits from Cloudflare's protection.

Cloudflare publishes their IP ranges publicly, so keeping the firewall rules updated is straightforward. Combined with Caddy's rate limiting, this gives me a solid defense-in-depth approach without adding complexity to the daily operations.

Infrastructure as Code with Terraform

As someone who believes in automating everything, I needed proper Infrastructure as Code for my cloud setup. I looked for existing Terraform modules for Hetzner Cloud but didn't find anything that met my standards for flexibility and maintainability. So I built my own.

I created a set of reusable Terraform modules that cover the essential Hetzner Cloud resources:

terraform-hcloud-server — Multi-server management with support for private networks and firewalls.
terraform-hcloud-network — VPC and subnet management
terraform-hcloud-firewall — Firewall rules configuration
terraform-hcloud-ssh-key — SSH key management with support for key generation

These modules are designed to work together seamlessly while remaining flexible enough for various use cases. They're all open source and available on both GitHub and the Terraform Registry.

Configuration Management with Ansible

With infrastructure sorted out, I needed a way to automate the actual server configuration and site deployment. For this, I created an Ansible collection: ansible-hugo-deploy.

This collection handles the complete deployment pipeline:

Installing and configuring Caddy with custom builds (including the Cloudflare DNS and rate limiting plugins)
Generating SSH deploy keys for secure repository access
Cloning the Hugo site from GitHub
Building the site with Hugo
Obtaining and managing SSL certificates
Configuring rate limiting and security headers
Setting up automated content updates via systemd timer

The systemd timer runs daily, pulling the latest changes from the repository and rebuilding the site. This means I can just push a new post to GitHub, and within a day (or I can trigger it manually), the site updates automatically. No SSH-ing into the server, no manual deployments.

The Complete Picture

Here's how everything fits together:

Terraform provisions the infrastructure on Hetzner Cloud—server, network, firewall rules (allowing only Cloudflare IPs), and SSH keys
Ansible configures the server—installs Caddy, Hugo, sets up the deployment pipeline
Hugo generates the static site from Markdown content
Caddy serves the site with automatic HTTPS, compression, and rate limiting
Cloudflare handles DNS, proxies all traffic, provides DDoS protection and CDN caching
systemd timer keeps the content automatically updated

The entire setup—from bare server to fully functional website—takes about 15 minutes. And once it's running, I never need to touch the server for content updates. Write a post in Markdown, push to GitHub, and the site updates itself.

What's Next?

In the second part of this series, I'll dive deeper into the technical details of both the Terraform modules and the Ansible collection. I'll walk through the code, explain the design decisions, and show how you can use these tools for your own projects.

All the code is open source and available on my GitHub:

Feel free to use them, contribute, or just take inspiration for your own automation journey!

Automated macOS Setup with Dotfiles

Danylo Mikula — Sat, 15 Nov 2025 05:28:13 +0000

A comprehensive automation solution for setting up macOS development environments. This dotfiles repository handles everything from Homebrew package installation to SSH/GPG key generation and GitHub integration – all through an interactive bootstrap script.

Repository: github.com/danylomikula/dotfiles

The Problem

Every DevOps engineer knows the pain:

New laptop arrives – 4-8 hours of manual setup
Switching between personal/work machines – different configs everywhere
Team onboarding – "just install these 50 things..."
Disaster recovery – scrambling to remember every tool and setting

Traditional approaches fall short:

Manual installation: Error-prone, inconsistent, undocumented
Basic dotfiles: Only manage config files, not installation
Homebrew Brewfile: Doesn't handle SSH/GPG keys or directory structures
Ansible playbooks: Overkill for personal use, slow iteration

The Solution: Intelligent Bootstrap Script

I built a comprehensive dotfiles repository that handles everything through a single bootstrap.sh script with interactive prompts using gum for a beautiful TUI experience.

What It Does

Core Installation:

Homebrew + analytics disabled
Nerd Fonts (Hack, Ubuntu Mono, Fira Code, Courier Prime)
Oh-My-Zsh with plugins (autosuggestions, syntax highlighting, you-should-use)
Modern CLI tools: eza, zoxide, fzf, starship, zellij
Python via pyenv with latest version auto-installed

Applications:

Productivity: Zen, Obsidian, Maccy, BetterDisplay, Grammarly
Communication: Signal, Telegram, Slack, Discord
Development: VSCode, Alacritty, Fork, Lens
DevOps/Cloud: AWS CLI, kubectl, helm, terraform, vault, argocd, ansible
Security: Mullvad VPN, Tailscale, GPG Suite
Utilities: AldDente, Bartender, AppCleaner, Shottr

Git Configuration:

Global .gitconfig with sane defaults
Separate directories for personal/work repos with automatic context switching
includeIf directives for email/name per directory
Global .gitignore setup
Branch sorting by commit date, auto column UI

SSH Key Generation:

Ed25519 keys with modern crypto
Automatic GitHub CLI integration
Adds key to GitHub via API
Tests SSH connection to GitHub

GPG Key Generation:

Ed25519 + Curve25519 keys for signing/encryption
Configures pinentry-mac for macOS Keychain integration
Automatic GitHub integration via API
Sets global signing key in Git

Dotfiles Management:

GNU Stow for symlink management
Configs for: zsh, starship, alacritty, zellij, k9s, docker, git, gh
Alacritty themes auto-cloned (200+ colorschemes)

AI Agents Configuration:

Configures Codex and Claude for development workflow
Installs Context7 MCP server for automatic library documentation
Sets up global Copilot instructions at ~/.config/Code/User/prompts/context7.instructions.md
Enables AI agents to automatically fetch library docs during code generation
Configured via standalone configure-ai-agents.sh script

Architecture

Directory Structure

dotfiles/
├── bootstrap.sh              # Main installation script
├── configure-git.sh          # Standalone Git config tool
├── configure-ai-agents.sh    # Standalone AI agents setup
├── generate-gpg-key.sh       # Standalone GPG key generator
├── generate-ssh-key.sh       # Standalone SSH key generator
├── alacritty/
│   └── .config/alacritty/
│       ├── alacritty.toml
│       └── themes/           # 200+ themes via git submodule
├── claude/                   # Claude Code AI agent config
│   └── .claude/
│       └── CLAUDE.md
├── codex/                    # Codex AI agent config
│   └── .codex/
│       ├── AGENTS.md
│       └── config.toml
├── docker/.docker/
│   └── config.json
├── git/
│   ├── .gitconfig
│   └── .gitignore_global
├── github-cli/.config/gh/
├── k9s/.config/k9s/
├── starship/.config/
│   └── starship.toml
├── zellij/.config/zellij/
│   └── config.kdl
└── zshrc/
    └── .zshrc

Key Design Decisions

1. Interactive Prompts with Gum

Instead of environment variables or config files, I use charmbracelet/gum for beautiful TUI prompts:

gum style --foreground "#00FF00" --bold "Do you want to generate a GPG key?"
CHOICE=$(gum choose "Yes" "No")

This makes the script:

Self-documenting (you see what's being configured)
Flexible (skip sections you don't need)
Beginner-friendly (no prior knowledge required)

2. Conditional Directory Creation

The script offers to create separate Git directories:

~/git/
├── personal/    # Personal projects with personal email
└── work/        # Work projects with work email

Git automatically switches context using includeIf:

[includeIf "gitdir:~/git/personal/**"]
    path = ~/git/personal/.gitconfig

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

3. Modern Crypto Defaults

SSH: Ed25519 (fast, secure, small keys)
GPG: Ed25519 for signing + Curve25519 for encryption
No RSA 2048/4096 bloat

4. GitHub API Integration

Keys aren't just generated–they're automatically added to GitHub:

# SSH key
gh ssh-key add "$SSH_KEY_PATH.pub" --title "$(hostname)"

# GPG key  
gh gpg-key add <(gpg --armor --export "$KEY_ID")

5. Stow for Symlink Management

GNU Stow creates symlinks from dotfiles/ to $HOME:

stow zshrc starship alacritty zellij k9s docker git github-cli

This keeps your actual configs in Git while making them available system-wide.

6. AI Agents with Context7 MCP

The configure-ai-agents.sh script sets up AI development assistants:

Codex CLI: Command-line AI agent for shell tasks
Claude Integration: Configured for VS Code with Copilot
Context7 MCP Server: Provides automatic library documentation via Model Context Protocol
Global Instructions: Creates ~/.config/Code/User/prompts/context7.instructions.md with rule to always use Context7 for docs

This enables AI agents to automatically fetch up-to-date documentation when generating code, reducing hallucinations and improving accuracy.

Usage

Quick Start (Full Bootstrap)

git clone https://github.com/danylomikula/dotfiles.git ~/dotfiles
cd ~/dotfiles
chmod +x bootstrap.sh
./bootstrap.sh

The script will:

Install Homebrew and packages (5-10 min)
Configure Oh-My-Zsh and plugins
Sync dotfiles via Stow
Prompt for Git configuration (optional)
Offer to generate SSH key (optional)
Offer to generate GPG key (optional)
Offer to configure AI agents (optional)

Standalone Scripts

Each script can run independently:

# Just configure Git
./configure-git.sh

# Just generate SSH key
./generate-ssh-key.sh

# Just generate GPG key  
./generate-gpg-key.sh

# Just configure AI agents
./configure-ai-agents.sh

Customization

Add/Remove Packages:

Edit the brew install lines in bootstrap.sh:

# Add your tools here
brew install --cask your-app-here

Add New Dotfiles:

Create directory: mkdir -p newtool/.config/newtool
Add config: newtool/.config/newtool/config.yaml
Stow it: stow newtool

Change Alacritty Theme:

# ~/.config/alacritty/alacritty.toml
[general]
import = [
    "~/.config/alacritty/themes/themes/tokyo-night.toml"
]

Customize AI Agents:

Edit ~/.config/Code/User/prompts/context7.instructions.md:

---
applyTo: "**"
name: "Global-Context7-Rule"
---

Always use context7 when I need code generation, setup steps, or library docs.

You can add more rules or change the applyTo pattern to scope instructions to specific file types.

Real-World Usage

New Machine Setup

Time to productive workstation: ~15 minutes (mostly package downloads)

# On new Mac
git clone https://github.com/danylomikula/dotfiles.git ~/dotfiles
cd ~/dotfiles
./bootstrap.sh

# Answer prompts:
# - Configure Git? Yes
# - Personal dir? ~/git/personal
# - Work dir? ~/git/work  
# - Generate SSH? Yes
# - Generate GPG? Yes
# - Add to GitHub? Yes
# - Configure AI agents? Yes

Result: Fully configured machine with:

All dev tools installed
SSH key in GitHub
GPG signing configured
Git context switching working
Terminal customized
AI agents with Context7 MCP ready
Ready to git clone and start working

Disaster Recovery

Laptop dies or needs rebuild:

# On replacement machine
git clone https://github.com/danylomikula/dotfiles.git ~/dotfiles
cd ~/dotfiles
./bootstrap.sh

Back to 100% productivity in under an hour (including restoring data from backups).

Technical Deep Dive

GPG Key Generation with Batch Mode

I use GPG's batch mode to avoid interactive prompts:

GPG_BATCH_FILE=$(mktemp)
cat > "$GPG_BATCH_FILE" <<EOF
%echo Generating a GPG key
Key-Type: eddsa
Key-Curve: ed25519
Subkey-Type: ecdh
Subkey-Curve: cv25519
Name-Real: ${GPG_OWNER_NAME}
Name-Email: ${GPG_OWNER_EMAIL}
Expire-Date: 0
Passphrase: ${GPG_PASSWORD}
%commit
%echo done
EOF

gpg --batch --gen-key "$GPG_BATCH_FILE"
rm "$GPG_BATCH_FILE"

This creates:

Primary key: Ed25519 for signing
Subkey: Curve25519 for encryption
No expiration: Suitable for long-term code signing

Detecting New GPG Key After Generation

Since we generate the key non-interactively, we need to find the new key ID:

# Capture existing keys before generation
EXISTING_KEYS=$(gpg --list-secret-keys --keyid-format=long \
  | awk '/^sec/ {print $2}' | cut -d'/' -f2)

# Generate key...

# Find the new key
NEW_KEYS=$(gpg --list-secret-keys --keyid-format=long \
  | awk '/^sec/ {print $2}' | cut -d'/' -f2)

KEY_ID=$(comm -13 <(echo "$EXISTING_KEYS" | sort) \
                   <(echo "$NEW_KEYS" | sort) | head -n 1)

This uses comm to find the set difference–the new key ID.

GitHub CLI Integration

Adding keys to GitHub via API:

# Authenticate (opens browser for OAuth)
gh auth login

# Add SSH key
gh ssh-key add "$HOME/.ssh/id_ed25519.pub" \
  --title "$(hostname)" --type authentication

# Test connection
ssh -T git@github.com

# Add GPG key  
gh gpg-key add <(gpg --armor --export "$KEY_ID")

# Configure Git to use it
git config --global user.signingkey "$KEY_ID"
git config --global commit.gpgsign true
git config --global tag.gpgSign true

No manual copying of keys into GitHub UI!

Pinentry Configuration for macOS

macOS Keychain integration requires pinentry-mac:

brew install pinentry-mac

# Configure GPG agent
echo "pinentry-program $(which pinentry-mac)" \
  >> ~/.gnupg/gpg-agent.conf

# Restart agent
killall gpg-agent

Now GPG passphrase prompts use macOS Keychain–enter once, cached securely.

AI Agents Configuration Deep Dive

The configure-ai-agents.sh script sets up CLI and desktop AI coding assistants with Context7 MCP integration.

1. Tools Installation:

brew install node codex           # Codex CLI
brew install --cask claude-code   # Claude desktop app

2. Codex CLI Configuration:

Creates ~/.codex/AGENTS.md with global instructions:

# Global instructions

## context7 instructions
- Always use context7 when I need code generation, setup or configuration 
  steps, or library/API documentation. This means you should automatically 
  use the Context7 MCP tools to resolve library id and get library docs 
  without me having to explicitly ask.

Creates ~/.codex/config.toml with MCP server configuration:

model = "gpt-5.1-codex"
model_reasoning_effort = "high"

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

3. Claude Desktop Configuration:

Creates ~/.claude/CLAUDE.md with Context7 usage instructions:

# Context7 MCP usage
- Always use context7 when I need code generation, setup or configuration 
  steps, or library/API documentation. This means you should automatically 
  use the Context7 MCP tools to resolve library id and get library docs 
  without me having to explicitly ask.

Enables MCP server for Claude:

claude mcp add context7 -- npx -y @upstash/context7-mcp

4. How It Works:

Both agents can now automatically fetch library documentation via Context7 MCP:

# Codex CLI usage
$ codex "Add authentication with Supabase"
[Codex automatically fetches Supabase docs via Context7 MCP]
"Installing supabase-js and configuring auth..."

# Claude Desktop usage
User: "Add authentication with Supabase"
Claude: [fetches Supabase docs via Context7]
        "I'll help you set up Supabase authentication..."

This eliminates manual documentation lookups and reduces hallucinations by grounding AI responses in actual library docs.

Conclusion

This dotfiles setup has saved me countless hours across:

5+ fresh installs on new machines
Daily context switching between personal/work
Team onboarding

Resources

Have questions or improvements? Open an issue or PR on the dotfiles repo!

Build a Highly Available Pi-hole Cluster with Ansible (VRRP)

Danylo Mikula — Fri, 07 Nov 2025 00:55:34 +0000

Step-by-step guide to prepare two Linux hosts, then use Ansible to deploy a highly available Pi-hole pair with keepalived (VRRP) and a Virtual IP, plus config sync and validation - powered by my open-source playbook: ansible-pihole-cluster

Download & flash the OS for Raspberry Pi

Both ansible-bootstrap and ansible-pihole-cluster support the following distributions:

Debian 13 (Trixie)
Ubuntu 24.04 (Noble Numbat)
Rocky Linux 10

This guide uses Rocky Linux as an example, but feel free to pick whichever you prefer.

1) Get the Raspberry Pi image

Go to the official Rocky Linux Download page: pick ARM (aarch64).
Scroll to the Raspberry Pi Images section and download the image for your Pi.

2) Flash the image to a microSD card

You can use balenaEtcher (what I use below), or Raspberry Pi Imager—both work.

Option A — balenaEtcher

Install/open balenaEtcher.
Flash from file → pick the Rocky Linux RPi image.
Select target → choose your microSD card.
Flash! → wait for completion.

Option B — Raspberry Pi Imager

Open Raspberry Pi Imager.
Click Choose OS → Use custom and select the Rocky Linux RPi image.
Choose your microSD card and Next.
When asked “Would you like to apply OS customisation settings?” click No (we’ll configure users/SSH/hostname later).
You’ll get a Warning that all data on the card will be erased — click Yes.

Repeat this flashing process for both microSD cards (one per Raspberry Pi), then boot each Pi and make sure it gets a DHCP address on your network.

Bootstrap: admin user, SSH keys, SSH hardening, networking, filesystem expansion

Before deploying Pi-hole, each node needs initial setup — an admin user with SSH key access, hardened SSH, static IP configuration, firewall rules, and the filesystem expanded to use the full microSD card. You can automate all of this with ansible-bootstrap:

Creates admin user with passwordless sudo
Generates and deploys SSH keys
Hardens SSH (disables password authentication and root login)
Configures static IPv4/IPv6 addresses, gateway, and DNS
Sets up firewall (firewalld) with custom zones and services
Expands the filesystem to use all available disk space

1) Install the collection

ansible-galaxy collection install danylomikula.ansible_bootstrap

2) Create the inventory

Create inventory.ini with your nodes. The ansible_host should be the current DHCP address of each Pi, while bootstrap_static_ip and bootstrap_gateway define the static network configuration that will be applied:

[servers]
pihole-master ansible_host=10.20.160.251 bootstrap_static_ip=10.20.0.50/16 bootstrap_gateway=10.20.0.1
pihole-backup ansible_host=10.20.200.39 bootstrap_static_ip=10.20.0.51/16 bootstrap_gateway=10.20.0.1

[servers:vars]
ansible_user=rocky

Note: On first run, ansible_user is the default OS user (e.g., rocky for Rocky Linux). After bootstrap completes, the new admin user is created and the nodes are accessible via SSH keys.

3) Create the bootstrap playbook

Create site.yml:

---
- name: Bootstrap servers
  hosts: all
  become: true
  vars:
    bootstrap_user: "dan"
    bootstrap_ssh_key_generate: true
    bootstrap_network_enabled: true
    bootstrap_dns4:
      - "1.1.1.1"
      - "1.0.0.1"
    bootstrap_firewall_enabled: true
    bootstrap_firewall_zone: "public"
    bootstrap_firewall_services:
      - ssh
      - http
      - https
      - dns
    bootstrap_firewall_custom_zones:
      - name: ftl
        interface: lo
        ports:
          - port: 4711
            proto: tcp
    bootstrap_firewall_allow_icmp: true
    bootstrap_expand_fs_enabled: true
  roles:
    - danylomikula.ansible_bootstrap.bootstrap

4) Run the bootstrap playbook

On the first run, SSH keys are not yet deployed, so you need to provide the password interactively:

ansible-playbook -i inventory.ini site.yml -k -K

Default credentials for Rocky Linux: User: rocky, Password: rockylinux

After bootstrap completes, the nodes reboot with their new static IPs. SSH keys are generated in the ssh_keys/ directory — you'll reference these keys later in the Pi-hole cluster inventory.

See the ansible-bootstrap README for the full list of configuration options.

Deploy Pi-hole cluster with Ansible

Prerequisites: Ansible installed on your configuration device and both nodes bootstrapped (see previous section).

1) Install the collection

ansible-galaxy collection install danylomikula.ansible_pihole_cluster

2) Create the inventory

Create inventory.ini with your nodes. Point ansible_ssh_private_key_file to the SSH keys generated by ansible-bootstrap:

[master]
pihole-master ansible_host=10.20.0.50 ansible_ssh_private_key_file=../pihole-bootstrap/ssh_keys/pihole-master_ed25519 priority=150

[backup]
pihole-backup ansible_host=10.20.0.51 ansible_ssh_private_key_file=../pihole-bootstrap/ssh_keys/pihole-backup_ed25519 priority=140

[pihole_cluster:children]
master
backup

Note: Adjust the ansible_ssh_private_key_file paths to match where your bootstrap SSH keys are stored.

3) Create the playbook

Create site.yml with all cluster configuration in one place:

---
- name: Deploy Pi-hole HA Cluster
  hosts: pihole_cluster
  become: true
  vars:
    ansible_user: dan
    bootstrap_timezone: "America/New_York"
    keepalived_vip_ipv4: "10.20.0.53/16"           # Virtual IP for failover
    pihole_web_password: "SUPER_SECURE_PASSWORD"    # Use ansible-vault!
    pihole_version: "6.3"
    nebula_sync_version: "v0.11.1"
    pihole_local_domain: "homelab.local"
    local_dns_records: |
      10.20.0.88 node.homelab.local
      10.20.0.96 nas.homelab.local
  roles:
    - role: danylomikula.ansible_pihole_cluster.updates
    - role: danylomikula.ansible_pihole_cluster.bootstrap
    - role: danylomikula.ansible_pihole_cluster.docker
    - role: danylomikula.ansible_pihole_cluster.keepalived
    - role: danylomikula.ansible_pihole_cluster.unbound
    - role: danylomikula.ansible_pihole_cluster.pihole
    - role: danylomikula.ansible_pihole_cluster.pihole_updatelists
    - role: danylomikula.ansible_pihole_cluster.nebula_sync
    - role: danylomikula.ansible_pihole_cluster.status

See the full list of available variables in the group_vars/all.yml example.

What the playbook installs (and why)

keepalived — Provides VRRP and the floating Virtual IP so one node is always the active DNS endpoint. If the master goes down, the backup takes over automatically.
unbound — A local validating, recursive DNS resolver. Pi-hole forwards queries to Unbound on-box instead of public resolvers, improving privacy and reducing external dependency. Pi-hole's official guide
nebula-sync — A lightweight synchronizer that keeps Pi-hole config/state in sync between nodes (lists, local DNS, settings). Project
pihole-updatelists — Automates fetching and applying block/allow lists from remote sources on a schedule. Project

4) (Optional) Quick connectivity test

ansible all -i inventory.ini -m ping

5) Deploy the cluster

ansible-playbook -i inventory.ini site.yml

6) Point your network to the Virtual IP

Update your DHCP/router (or manual client settings) to use the VIP you set in site.yml:

IPv4 DNS: keepalived_vip_ipv4 (e.g., 10.20.0.53)
IPv6 DNS: ipv6_vip (if configured)

7) Verify

On whichever node should be master (higher priority), check that the VIP is present:

ip a show dev eth0

Confirm Pi-hole is answering:

dig @10.20.0.53 example.com +short

If that resolves, you're done — your HA Pi-hole pair is live behind a single Virtual IP.

YubiKey + PGP: Offline Primary, Subkeys, Backups, and Git Signing

Danylo Mikula — Fri, 22 Aug 2025 03:25:38 +0000

What we’ll build

In this guide we’ll set up a modern PGP workflow anchored by a YubiKey. We’ll generate an offline, certification-only primary key and three subkeys for sign, encrypt, and auth.

We’ll also create secure backups before moving anything to hardware, set expiration dates on the subkeys, load the subkeys onto our primary YubiKey with touch policies, and then clone those subkeys to a second YubiKey as a spare. Finally, we’ll integrate the setup with Git commit signing.

This guide is written for macOS, but the steps translate easily to Linux.

Prerequisites

A YubiKey with the OpenPGP applet (e.g., YubiKey 5 series).
macOS with Homebrew installed.
Basic terminal familiarity.

Install the tools (macOS)

brew install gnupg ykman pinentry-mac

Basic GnuPG setup

We’ll work inside a temporary GnuPG home so we don’t touch any existing setup.

1) Create a temporary GNUPGHOME

export GNUPGHOME="$(mktemp -d -t gpg-$(date +%Y.%m.%d))"
chmod 700 "$GNUPGHOME"

2) Create `gpg.conf`

cat > "$GNUPGHOME/gpg.conf" <<'EOF'
# === Crypto preferences ===
personal-cipher-preferences AES256 AES192 AES
personal-digest-preferences SHA512 SHA384 SHA256
personal-compress-preferences ZLIB BZIP2 ZIP Uncompressed
default-preference-list SHA512 SHA384 SHA256 AES256 AES192 AES ZLIB BZIP2 ZIP Uncompressed

# === Strong digests & s2k ===
cert-digest-algo SHA512
s2k-digest-algo SHA512
s2k-cipher-algo AES256

# === Output / UX ===
charset utf-8
no-comments
no-emit-version
no-greeting
keyid-format 0xlong
list-options show-uid-validity
verify-options show-uid-validity
with-fingerprint
use-agent
armor

# === Security hardening ===
require-cross-certification
require-secmem
no-symkey-cache

# === New keys default ===
default-new-key-algo ed25519/cert,sign+cv25519/encr+ed25519/auth
EOF

3) Create `gpg-agent.conf`

cat > "$GNUPGHOME/gpg-agent.conf" <<'EOF'
# === Path to pinentry on macOS/Homebrew (Apple Silicon) ===
pinentry-program /opt/homebrew/bin/pinentry-mac

# === SSH Support ===
enable-ssh-support

# === Cache TTLs ===
default-cache-ttl 86400
max-cache-ttl 86400
EOF

4) Reload agent to pick up the config:

gpgconf --kill gpg-agent

Prepare the YubiKey

If you keep a spare YubiKey, run all steps below on both devices (one at a time).

Insert only one YubiKey at a time to avoid confusion.

1) Enable KDF

KDF (Key Derivation Function) makes the YubiKey store a hash of the PIN and derive it locally, rather than accepting the PIN as plain text.

Older/legacy OpenPGP clients (especially some mobile apps) may not support KDF; those clients will fail PIN checks if KDF is enabled.

Order of operations: Enable KDF before changing PINs or moving subkeys to the card, otherwise you may hit:

gpg: error for setup KDF: Conditions of use not satisfied

Enable KDF:

gpg --card-edit
gpg/card> admin
gpg/card> kdf-setup
# pinentry will prompt for the Admin PIN (default is 12345678 on a fresh card)
gpg/card> quit

Verify:

gpg --card-status | grep 'KDF setting'
# KDF setting ......: on

Do this on each YubiKey (primary and spare) before proceeding to change PINs, set touch policies, or move subkeys.

2) Change the default PINs

Generate random numeric PINs and store these securely:

export ADMIN_PIN=$(LC_ALL=C tr -dc '0-9' </dev/urandom | fold -w8 | head -1)
export USER_PIN=$(LC_ALL=C  tr -dc '0-9' </dev/urandom | fold -w6 | head -1)
printf "\nAdmin PIN: %12s\nUser  PIN: %12s\n\n" "$ADMIN_PIN" "$USER_PIN"

Change the PINs:

gpg --card-edit
gpg/card> admin
gpg/card> passwd
# 1 - Change PIN          (default 123456)     -> enter $USER_PIN
# 3 - Change Admin PIN    (default 12345678)   -> enter $ADMIN_PIN
# Q - quit
gpg/card> quit

Default User PIN = 123456, default Admin PIN = 12345678

3) Set touch policies

# Require touch for every signature
ykman openpgp keys set-touch sig on

# Cache touch after PIN entry for encryption and auth
ykman openpgp keys set-touch enc cached
ykman openpgp keys set-touch aut cached

Verify:

ykman openpgp info

Touch policy modes:

off — no touch required
on — touch required for every operation
fixed — like on, but cannot be changed without resetting the OpenPGP applet
cached — touch once per PIN session (until PIN cache expires or card is removed)
cached-fixed — like cached, but cannot be changed without reset

4) Set key attributes (Ed25519 / cv25519 / Ed25519)

gpg --card-edit
gpg/card> admin
gpg/card> key-attr
# Signature : ECC -> Curve 25519 (Ed25519)
# Encryption: ECC -> Curve 25519 (cv25519 / X25519)
# Authentication: ECC -> Curve 25519 (Ed25519)
gpg/card> quit

5) Cardholder info

gpg --card-edit
gpg/card> admin
gpg/card> name   # Lastname, Firstname
gpg/card> lang   # en
gpg/card> login  # your.email@example.com
gpg/card> quit

Check card status:

gpg --card-status

When finished, repeat the same steps on your spare (if you have one).

Generate the offline Master (Certify) key (Ed25519)

The primary (master) key is the Certify key. It’s used only to issue subkeys for sign, encrypt, and auth.
We keep this key offline at all times and use it only in a dedicated, secure environment to create or revoke subkeys.

Do not set an expiration date on the Certify key.

1) Generate a strong passphrase for the master key

export CERTIFY_PASS=$(LC_ALL=C tr -dc "A-Z2-9" < /dev/urandom | tr -d "IOUS5" | fold -w ${PASS_GROUPSIZE:-4} | paste -sd ${PASS_DELIMITER:--} - | head -c ${PASS_LENGTH:-29})
printf "\n$CERTIFY_PASS\n\n"

We will use it when GnuPG prompts during key creation.

2) Create the Certify-only primary key

gpg --expert --full-generate-key

When prompted:

Key type: choose ECC (set your own capabilities).
Capabilities: leave only “Certify (C)” enabled. Disable Sign/Encrypt/Auth if shown.
Curve: choose Curve 25519 (Ed25519).
Expiration: choose no expiration (enter 0).
User ID: enter your real name and email (comment optional).
Passphrase: enter the passphrase you generated in step 1.

After creation, note the key ID:

export KEYID=$(gpg --list-keys --keyid-format 0xlong --with-colons | awk -F: '/^pub:/ {print $5; exit}')
echo "Primary KEYID: $KEYID"

3) Verify the primary key is Certify-only

gpg -K --keyid-format long

You should see something like:

sec   ed25519/XXXXXXXXXX YYYY-MM-DD [C]
      Key fingerprint = XXXXXXXXXXXXXXXXX
uid   [ultimate] Your Name <you@example.com>

Only [C] should appear on the sec line (no [S], [E], or [A]).

Create subkeys

We’ll add three subkeys to the offline primary key: Sign (Ed25519), Encrypt (cv25519/X25519), and Auth (Ed25519).

Open the key editor:

gpg --expert --edit-key "$KEYID"

1) Sign subkey

gpg> addkey
# Choose: ECC (set your own capabilities)   # number may be (11)
# Curve: 25519 (Ed25519)
# Capabilities: leave ONLY [S] Sign (toggle others off)
# Expiration: 5y (or your preference)

2) Encrypt subkey

gpg> addkey
# Choose: ECC (encrypt only)                # number may be (12)
# Curve: 25519
# Expiration: 5y

3) Auth subkey

gpg> addkey
# Choose: ECC (set your own capabilities)   # number may be (11)
# Capabilities: leave ONLY [A] Authenticate
# Curve: 25519
# Expiration: 5y
gpg> save

4) Verify

gpg -K --keyid-format long

You should see your primary key with [C] only, and three ssb lines:

sec   ed25519/XXXXXXXXXX YYYY-MM-DD [C]
uid   Your Name <you@example.com>
ssb   ed25519/XXXXXXXXXX YYYY-MM-DD [S] [expires: YYYY-MM-DD]
ssb   cv25519/XXXXXXXXXX YYYY-MM-DD [E] [expires: YYYY-MM-DD]
ssb   ed25519/XXXXXXXXXX YYYY-MM-DD [A] [expires: YYYY-MM-DD]

Export backups (master, subkeys, public)

Do this before moving any keys to the YubiKey.

1) Create a private backups folder:

mkdir -p gnupg-backups
chmod 700 gnupg-backups

2) Export the keys:

# Master (primary + subkeys): full secret material
gpg --output "gnupg-backups/${KEYID}-certify-$(date +%F).key" --armor --export-secret-keys "${KEYID}"

# Secret subkeys only (no primary secret) — use for loading to YubiKey / cloning to spare
gpg --output "gnupg-backups/${KEYID}-subkeys-$(date +%F).key" --armor --export-secret-subkeys "${KEYID}"

# Public key (safe to share)
gpg --output "gnupg-backups/${KEYID}-public-$(date +%F).asc" --armor --export "${KEYID}"

Store copies in two separate offline locations (e.g., two encrypted USB drives kept in different places).

3) (Optional) Encrypt the backup files

Symmetric (passphrase-based):

# Encrypt each file with AES256; you’ll be prompted for a passphrase
for f in gnupg-backups/${KEYID}-{certify,subkeys}-*.key gnupg-backups/${KEYID}-public-*.asc; do
  gpg --symmetric --cipher-algo AES256 "$f"
done

(Optional) Quick integrity check of the backups

Spin up a throwaway keyring, import, and list:

TMPVERIFY="$(mktemp -d -t gpg-verify-XXXX)"
chmod 700 "$TMPVERIFY"

GNUPGHOME="$TMPVERIFY" gpg --import gnupg-backups/${KEYID}-public-*.asc
GNUPGHOME="$TMPVERIFY" gpg --import gnupg-backups/${KEYID}-subkeys-*.key
GNUPGHOME="$TMPVERIFY" gpg --list-secret-keys --keyid-format 0xlong

You should see sec# (stub for the primary) and ssb lines for subkeys after the subkeys import.

4) Clean up the temporary directory

rm -rf "$TMPVERIFY"

Transfer subkeys to the YubiKey

Important: Moving subkeys to a YubiKey turns their on-disk copies into stubs (ssb# → ssb>), so they can’t be moved again unless we re-import the secret-subkeys backup. Make sure backups are done.

We’ll need the Certify key passphrase (for decrypting the secret material) and the YubiKey Admin PIN (to write keys to the card).

Keep only one YubiKey inserted at a time.

1) Load the subkeys onto the primary YubiKey

Insert the primary YubiKey, then:

gpg --status-fd=2 --command-fd=0 --expert --edit-key "$KEYID" <<'EOF'
key 1
keytocard
1
save
EOF

gpg --status-fd=2 --command-fd=0 --expert --edit-key "$KEYID" <<'EOF'
key 2
keytocard
2
save
EOF

gpg --status-fd=2 --command-fd=0 --expert --edit-key "$KEYID" <<'EOF'
key 3
keytocard
3
save
EOF

During these steps GnuPG will prompt for:

your master (Certify) passphrase (to unlock the secret subkeys on disk), and
the YubiKey Admin PIN (to write into the OpenPGP applet).

2) Verify subkeys are on the YubiKey

gpg -K --keyid-format long

Each subkey should display as ssb> (stored on smartcard), for example:

sec   ed25519 YYYY-MM-DD [C]
uid   Your Name <you@example.com>
ssb>  ed25519 YYYY-MM-DD [S] [expires: …]
ssb>  cv25519 YYYY-MM-DD [E] [expires: …]
ssb>  ed25519 YYYY-MM-DD [A] [expires: …]

Additionally:

gpg --card-status

Should list the Signature/Encryption/Authentication slots and the touch policies you set earlier.

3) (If you have a spare) Re-import and load to the second YubiKey

Because moving subkeys to the first YubiKey turned local copies into stubs, we’ll clear any existing secret entries and re-import the pre-move secret-subkeys backup.

# Ensure you’re in the same GNUPGHOME you used for the guide
echo "$GNUPGHOME"

# Remove current secret entries (drops stubs)
gpg --delete-secret-keys "$KEYID"

# Re-import secret subkeys
gpg --import gnupg-backups/${KEYID}-subkeys-*.key

# Sanity check — these must be plain `ssb` (not `ssb#` or `ssb>`)
gpg -K --keyid-format long

Insert the spare YubiKey (only this one inserted), then run the same transfer flow:

gpg --status-fd=2 --command-fd=0 --expert --edit-key "$KEYID" <<'EOF'
key 1
keytocard
1
save
EOF

gpg --status-fd=2 --command-fd=0 --expert --edit-key "$KEYID" <<'EOF'
key 2
keytocard
2
save
EOF

gpg --status-fd=2 --command-fd=0 --expert --edit-key "$KEYID" <<'EOF'
key 3
keytocard
3
save
EOF

Pinentry will prompt for your master (Certify) passphrase and the Admin PIN.

4) Verify:

gpg --card-status
gpg -K --keyid-format long

You should see ssb> for all three subkeys again, now on the spare as well.

Done! Both YubiKeys now hold the same Sign/Encrypt/Auth subkeys.

Post-Setup

Publish your public key (keys.openpgp.org) and link it to your YubiKey

Why?
Publishing the public key makes it easy for others (and for your future machines) to discover it.

Upload

1) Go to keys.openpgp.org → Upload Key.
2) Export and upload your public key:

   gpg --armor --export "$KEYID" > pubkey-$KEYID.asc

3) Click Send verification email.
4) Check the inbox for the email on your key and click the verification link.

Put the public key URL on your YubiKey

We’ll store a permalink to your key on the card so any machine can fetch it with one command.

1) Get your full fingerprint and build the permalink:

FPR=$(gpg --with-colons --fingerprint "$KEYID" | awk -F: '/^fpr:/ {print $10; exit}')
echo "Fingerprint: $FPR"
echo "Permalink  : https://keys.openpgp.org/vks/v1/by-fingerprint/$FPR"

2) Write the URL into the card:

gpg --card-edit
gpg/card> admin
gpg/card> url
https://keys.openpgp.org/vks/v1/by-fingerprint/$FPR
gpg/card> quit

Do this for each YubiKey you use (primary and spare).

On a new machine: fetch straight from the card

Insert the YubiKey and run:

gpg --card-edit
gpg/card> admin
gpg/card> fetch
gpg/card> quit

This pulls your public key from the URL stored on the card and imports it into the new machine’s keyring.
You can verify with:

gpg --card-status
gpg -K --keyid-format long

GitHub: sign commits with your YubiKey subkey

We’ll upload your public key to GitHub and configure Git to sign with the Sign subkey that lives on your YubiKey.

1) Get the Sign subkey’s long ID (automatically)

# Prints the first subkey with [S] capability (long 0x… ID)
SUBKEY_SIGN=$(
  gpg -K --with-colons --keyid-format 0xlong "$KEYID" |
  awk -F: '/^ssb/ && $12 ~ /s/ {print $5; exit}'
)
echo "Signing subkey: $SUBKEY_SIGN"

2) Add your public key to GitHub

Export your public key and copy it:

   gpg --armor --export "$KEYID" | pbcopy   # macOS; use xclip/clipboard on Linux

GitHub → Settings → SSH and GPG keys → New GPG key → paste → Add GPG key.

Your commit email must match a verified email on GitHub.

3) Configure Git to use that subkey

git config --global gpg.program gpg
git config --global gpg.format openpgp
git config --global user.signingkey "$SUBKEY_SIGN"
git config --global user.email "yubikey@example.com"  # must be a verified GitHub email
git config --global commit.gpgsign true
git config --global tag.gpgSign true

Forem: Danylo Mikula

Building My Personal Website: From Idea to Automated Deployment (Part 2)

Infrastructure Overview

Network Module

Firewall Module

Dynamic Cloudflare IP Fetching

SSH Key Module

Server Module

Complete Configuration

Server Bootstrapping with Ansible

My Ansible Configuration

Custom Caddy Build with Plugins

Automated Content Updates

systemd Timer for Periodic Updates

Caddyfile Configuration

Conclusion

Building My Personal Website: From Idea to Automated Deployment (Part 1)

Choosing the Right Static Site Generator

Finding the Perfect Theme

Where to Host?

Caddy: The Modern Web Server

DNS and Security with Cloudflare

Infrastructure as Code with Terraform

Configuration Management with Ansible

The Complete Picture

What's Next?

Automated macOS Setup with Dotfiles

The Problem

The Solution: Intelligent Bootstrap Script

What It Does

Architecture

Directory Structure

Key Design Decisions

Usage

Quick Start (Full Bootstrap)

Standalone Scripts

Customization

Real-World Usage

New Machine Setup

Disaster Recovery

Technical Deep Dive

GPG Key Generation with Batch Mode

Detecting New GPG Key After Generation

GitHub CLI Integration

Pinentry Configuration for macOS

AI Agents Configuration Deep Dive

Conclusion

Resources

Build a Highly Available Pi-hole Cluster with Ansible (VRRP)

Download & flash the OS for Raspberry Pi

1) Get the Raspberry Pi image

2) Flash the image to a microSD card

Option A — balenaEtcher

Option B — Raspberry Pi Imager

Bootstrap: admin user, SSH keys, SSH hardening, networking, filesystem expansion

1) Install the collection

2) Create the inventory

3) Create the bootstrap playbook

4) Run the bootstrap playbook

Deploy Pi-hole cluster with Ansible

1) Install the collection

2) Create the inventory

3) Create the playbook

4) (Optional) Quick connectivity test

5) Deploy the cluster

6) Point your network to the Virtual IP

7) Verify

YubiKey + PGP: Offline Primary, Subkeys, Backups, and Git Signing

What we’ll build

Prerequisites

Install the tools (macOS)

Basic GnuPG setup

1) Create a temporary GNUPGHOME

2) Create gpg.conf

3) Create gpg-agent.conf

4) Reload agent to pick up the config:

Prepare the YubiKey

1) Enable KDF

2) Change the default PINs

3) Set touch policies

2) Create `gpg.conf`

3) Create `gpg-agent.conf`