Automating Caddy Reverse Proxy Deployments with GitHub Actions

Sun, 08 Nov 2026 00:00:00 GMT

One of the most dangerous anti-patterns in self-hosting is editing live reverse proxy configurations directly on production hosts via SSH. A single misplaced bracket or invalid directive can take down all subdomains simultaneously.

To prevent outages, the ExCloudVault.com private cloud enforces a strict GitOps deployment model for Caddy using GitHub Actions.

The GitOps Workflow Lifecycle

sequenceDiagram
    autonumber
    actor Dev as Engineer
    participant GH as GitHub Repository (mbabros/homelab)
    participant Runner as GitHub Actions CI
    participant OCI as OCI Caddy Gateway

    Dev->>GH: git push (Changes to Caddyfile)
    GH->>Runner: Trigger CI/CD Pipeline
    Note over Runner: Step 1: Caddy Syntax Validation (caddy validate)<br/>Step 2: Security Linting & Policy Check
    alt Validation Fails
        Runner-->>Dev: Pipeline Failed ❌ (Deployment aborted)
    else Validation Passes
        Runner->>OCI: SSH Deploy (rsync Caddyfile & trigger reload)
        OCI->>OCI: caddy reload --config /etc/caddy/Caddyfile
        OCI-->>Runner: Reload Successful (HTTP 200 OK)
        Runner-->>Dev: Deployment Successful ✅ (Zero downtime)
    end

1. Automated Syntax Validation in CI

Before any Caddyfile change reaches production, GitHub Actions validates the syntax using the official Caddy Docker image:

name: Validate Caddyfile

on:
  pull_request:
    paths:
      - 'Caddyfile'
  push:
    branches:
      - main
    paths:
      - 'Caddyfile'

jobs:
  validate:
    name: Lint & Validate Syntax
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Validate Caddyfile Syntax
        run: |
          docker run --rm -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile:ro \
            caddy:2-alpine caddy validate --config /etc/caddy/Caddyfile

If a typo or syntax error exists, the pipeline halts immediately, preventing broken configurations from ever being deployed.

2. Zero-Downtime Hot Reloading

Unlike Nginx, which often requires process restarts or complex signal handling, Caddy features a native API and CLI command for dynamic, zero-downtime configuration reloads:

docker exec caddy caddy reload --config /etc/caddy/Caddyfile

Caddy parses the new configuration in memory. If valid, it hot-swaps active listener sockets without dropping in-flight TCP connections or terminating active WebSocket sessions. If the new config contains an operational error, Caddy rolls back immediately to the previous running configuration in memory.

3. Production Deployment Step

Once the syntax is verified, the deployment job connects to the OCI gateway via SSH (using GitHub Secrets for private keys):

  deploy:
    name: Deploy to Edge Gateway
    needs: validate
    if: github.ref == 'refs/heads/main'
    runs-on: self-hosted # Or ubuntu-latest with Tailscale action
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Sync Caddyfile & Reload
        env:
          SSH_KEY: ${{ secrets.OCI_SSH_KEY }}
          HOST: ${{ secrets.OCI_HOST }}
        run: |
          echo "$SSH_KEY" > key.pem && chmod 600 key.pem
          scp -i key.pem Caddyfile ubuntu@$HOST:/opt/caddy/Caddyfile
          ssh -i key.pem ubuntu@$HOST "docker exec caddy caddy reload --config /etc/caddy/Caddyfile"
          rm -f key.pem

Summary

With automated syntax checking, zero-downtime hot reloading, and GitOps versioning, our team can add new services or modify routing rules with complete confidence. Every change is peer-reviewed in pull requests, and production remains reliable and resilient.

Building an Enterprise-Grade Zero-Trust Private Cloud

Sat, 07 Nov 2026 00:00:00 GMT

For years, self-hosting at home came with unavoidable compromises: noisy enterprise server racks, surging electric bills, fragile dynamic DNS scripts, and the inherent security risks of opening ports on your home router.

Today, modern networking and virtualization primitives have completely reshaped the self-hosting landscape. In this post, we explain how we designed and deployed ExCloudVault.com—a zero-trust, high-density private cloud infrastructure running on an Apple Silicon Mac mini and an Oracle Cloud Always-Free edge gateway.

The Core Design Requirements

When we set out to re-architect our private cloud, we established non-negotiable architectural requirements:

Zero Open Ports at Home: No port forwarding on the residential NAT router. Immunity to port scanning, brute-force bots, and ISP CGNAT limitations.
Instant Wildcard SSL: Automated Let’s Encrypt certificates for *.mbabros.com without relying on HTTP port 80 domain validation.
HTTP/3 (QUIC) Acceleration: Accelerated page loading and WebSocket reliability over UDP.
Low Power Consumption: Sub-20W average power draw to maintain whisper-quiet operation and negligible electricity cost.
100% Codified GitOps: Zero manual configuration drifts. All Caddy routing rules, firewall tables, and Docker stacks version-controlled in Git.

The Architecture at a Glance

flowchart LR
    Client["Client Browser"] -->|"HTTPS / QUIC"| OCI["Oracle Cloud Gateway<br/>(Caddy + Cloudflare DNS-01)"]
    OCI -->|"Tailscale WireGuard Mesh<br/>(Encrypted 100.x.y.z Tunnel)"| MacMini["Mac mini Node<br/>(OrbStack + Coolify PaaS)"]
    MacMini --> Apps["Nextcloud · Shlink · Immich · Paperless"]

1. The Cloud Ingress Edge: Oracle Cloud + Caddy

Rather than exposing our home IP, we provisioned an OCI Always Free ARM Ampere A1 instance. With 4 OCPUs and 24GB of RAM permanently free of charge, it acts as an unyielding cloud bastion.

On this VM, we run Caddy compiled with the Cloudflare DNS module (caddy-dns/cloudflare). Caddy interacts directly with Cloudflare’s API to solve DNS-01 ACME challenges, issuing Let’s Encrypt wildcard certificates (*.mbabros.com) seamlessly in the background.

2. The Private Mesh: Tailscale WireGuard

To bridge the OCI gateway to the Mac mini in our home office, we use Tailscale. Tailscale creates an encrypted point-to-point WireGuard mesh. Traffic never touches an unauthenticated public interface. The Mac mini establishes an outbound UDP connection; no inbound ports are opened on the router.

3. The Powerhouse: Mac mini M2 & Coolify PaaS

At the center of our home network sits an Apple Silicon Mac mini running OrbStack. With ultra-low memory overhead and instant container boot times, it hosts Coolify, our self-hosted PaaS controller.

Coolify orchestrates our application inventory—Nextcloud, Microbin, Immich, Karakeep, and Paperless-ngx—while handling database provisioning, environment variables, and daily encrypted S3 backups.

Lessons Learned & Key Takeaways

Wildcard DNS-01 is a Game Changer: Managing per-container SSL certificates inside your local network is complex and error-prone. By terminating wildcard TLS once at the cloud edge, internal apps can operate over secure HTTP within the WireGuard mesh.
Apple Silicon is the Future of Homelabs: Replacing bulky x86 server hardware with an M-series Mac mini reduced our idle power consumption from 180 Watts to under 7 Watts, with zero fan noise.

In our next article, we will dive deep into how we automate Caddy testing and deployments using GitHub Actions!

ExCloudVault.com | Engineering Blog