Act as a local network reverse proxy

cloudflared/DOCS.md

@@ -126,6 +126,10 @@ chunked transfer encoding. This is useful if you are running a WSGI server,
 like Proxmox for example. Visit [Cloudflare Docs][disablechunkedencoding] for
 further information.
 
+When `use_builtin_proxy` is enabled, you can also add `internalOnly: true` to a
+hostname to only allow access to it from within your local network. When this
+service is accessed from Cloudflare, it will return a 403 Forbidden.
+
 Please find below an example entry for three additional hosts:
 
 ```yaml
@@ -215,6 +219,69 @@ in Cloudflare by adding a CNAME record with `*` as name.
 Finally, you have to set-up your proxy hosts in Nginx Proxy Manager and forward
 them to wherever you like.
 
+### Option: `use_builtin_proxy`
+
+If enabled, the connection to Home Assistant and additional hosts will be made
+through the built-in Caddy proxy. This allows a unified access to Home
+Assistant and additional hosts even within your local network.
+
+**Note**: _This option is disabled by default._
+
+Here is how you can leverage the built-in Caddy proxy for local access:
+
+1. These additional add-on ports needs to be exposed through the add-on
+   _Configuration_ page > _Network_:
+   - `80/tcp` for HTTP access
+   - `443/tcp` for HTTPS access (this will also enable automatic HTTPS
+     certificates and HTTP to HTTPS redirection)
+   - `443/udp` for HTTP/3 QUIC access
+
+   To expose them, click _Show disabled ports_ and repeat their port numbers in
+   each of them:
+   - `80` for the `80/tcp` port
+   - `443` for the `443/tcp` port
+   - `443` for the `443/udp` port
+
+1. Set your local DNS server to resolve the `external_hostname` and any
+   `hostname` of `additional_hosts` to the local IP of your Home Assistant
+   instance.
+
+   Example: set `ha.example.com` and `router.example.com` to resolve to
+   `192.168.1.10`.
+
+   If you are using OpenWRT, you can do it from _Network_ > _DHCP and DNS_ >
+   _DNS Records_ > _Hostnames_.
+
+   If you are using AdGuard Home, you can do it from _Filters_ > _DNS rewrites_.
+
+   If you are using some other DNS server, please refer to its documentation.
+
+1. Confirm that the `external_hostname` and any `hostname` of `additional_hosts`
+   are resolving to the local IP of your Home Assistant.
+
+   Example: run `nslookup ha.example.com` and `nslookup router.example.com` in
+   your terminal and check that the output shows the local IP of your Home
+   Assistant instance, and not Cloudflare's IP addresses.
+
+1. Access your Home Assistant instance via the `external_hostname` or access
+   your additional hosts via their `hostname`s defined in `additional_hosts` in
+   your browser.
+
+   Example: `https://ha.example.com/` or `https://router.example.com/`.
+
+   And confirm everything works as expected.
+
+1. Optionally, you can set `additional_hosts` entries with `internalOnly: true`
+   to only allow access to them from within your local network. When such
+   service is accessed from Cloudflare, it will return a _403 Forbidden_. Don't
+   forget to set the DNS entries for these hosts too.
+
+Congratulations! You are now using the built-in proxy to access your Home
+Assistant instance and additional hosts locally, through a unified URL without
+having to swap between internal and external URLs. Also, you saved a lot of
+time by not having to set up a reverse proxy like Nginx Proxy Manager yourself,
+including handling the HTTPS certificates and HTTP to HTTPS redirection.
+
 ### Option: `post_quantum`
 
 If you want Cloudflared to use post-quantum cryptography for the tunnel,

cloudflared/Dockerfile

@@ -2,12 +2,16 @@ FROM ghcr.io/hassio-addons/base:19.0.0
 
 # Set S6 verbosity level
 ENV S6_VERBOSITY="1"
+# Enable Caddy service only if enabled in config
+ENV S6_STAGE2_HOOK="/etc/s6-overlay/s6-rc.d/caddy/condition_caddy.sh"
 
 # Setup base
 ARG BUILD_ARCH="amd64"
 
 # renovate: datasource=repology depName=yq packageName=alpine_3_22/yq-go versioning=loose
 ARG YQ_VERSION="4.47.2-r1"
+# renovate: datasource=github-releases depName=caddy packageName=caddyserver/caddy
+ARG CADDY_VERSION="2.10.2"
 # renovate: datasource=github-releases depName=cloudflared packageName=cloudflare/cloudflared versioning=loose
 ARG CLOUDFLARED_VERSION="2025.11.1"
 

cloudflared/config.yaml

@@ -22,15 +22,23 @@ options:
   additional_hosts: []
 ports:
   36500/tcp: null
+  80/tcp: null
+  443/tcp: null
+  443/udp: null
+privileged:
+  # https://hub.docker.com/_/caddy#linux-capabilities:~:text=caddy_container_id%20caddy%20reload-,Linux%20capabilities,-Caddy%20ships%20with
+  - NET_ADMIN
 schema:
   external_hostname: str?
   additional_hosts:
     - hostname: str
       service: str
       disableChunkedEncoding: bool?
+      internalOnly: bool?
   tunnel_name: str?
   catch_all_service: str?
   nginx_proxy_manager: bool?
+  use_builtin_proxy: bool?
   tunnel_token: str?
   post_quantum: bool?
   run_parameters:

cloudflared/rootfs/build.sh

@@ -10,6 +10,22 @@ set -eux
 # yq is to avoid depending on Home Assistant API on startup
 apk add --no-cache yq-go="${YQ_VERSION}"
 
+# Adapt the architecture to the caddy specific names if needed
+# see HA archs: https://developers.home-assistant.io/docs/add-ons/configuration/#:~:text=the%20add%2Don.-,arch,-list
+# see Caddy archs: https://github.com/caddyserver/caddy/releases
+case "${BUILD_ARCH}" in
+"aarch64")
+    caddy_arch="arm64"
+    ;;
+*)
+    caddy_arch="${BUILD_ARCH}"
+    ;;
+esac
+
+# Download the caddy bin
+wget -q -O- "https://github.com/caddyserver/caddy/releases/download/v${CADDY_VERSION}/caddy_${CADDY_VERSION}_linux_${caddy_arch}.tar.gz" |
+    tar -xzf- -C /usr/bin caddy
+
 # Adapt the architecture to the cloudflared specific names if needed
 # see HA archs: https://developers.home-assistant.io/docs/add-ons/configuration/#:~:text=the%20add%2Don.-,arch,-list
 # see Cloudflared archs: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation

cloudflared/rootfs/etc/caddy/Caddyfile.gtpl

@@ -0,0 +1,74 @@
+{
+	# We don't use the admin API
+	admin off
+	# There is no need to persist the generate json configuration
+	persist_config off
+	# There is no need to attempt installing the root CA
+	skip_install_trust
+	{{ if not .auto_https }}
+	# Disable automatic generation of Let's Encrypt certificates
+	local_certs
+	{{ end }}
+	log {
+		# More friendly logging format than the default json
+		format console
+	}
+}
+
+# Used for communication between Cloudflared and Caddy
+https://caddy.localhost {
+  tls internal
+
+	# Used to ensure Caddy is ready before starting Cloudflared
+	respond /healthz 200
+
+	respond 403
+}
+
+{{ if .ha_external_hostname }}
+{{ .ha_external_hostname }} {
+	@cloudflared remote_ip 127.0.0.1
+
+	reverse_proxy @cloudflared {{ .ha_service_url }} {
+		# https://developers.cloudflare.com/support/troubleshooting/restoring-visitor-ips/restoring-original-visitor-ips/#caddy
+		header_up X-Forwarded-For {http.request.header.CF-Connecting-IP}
+		{{ if hasPrefix "https://" .ha_service_url }}
+		transport http {
+			tls_insecure_skip_verify
+		}
+		{{ end }}
+	}
+
+	reverse_proxy {{ .ha_service_url }} {{ if hasPrefix "https://" .ha_service_url }}{
+		transport http {
+			tls_insecure_skip_verify
+		}
+	}{{ end }}
+}
+{{ end }}
+
+{{ range $i, $e := .additional_hosts }}
+{{ $e.hostname }} {
+	@cloudflared remote_ip 127.0.0.1
+	{{ if $e.internalOnly }}
+	# Block connections from Cloudflared as service is internal only
+	handle @cloudflared {
+		respond 403
+	}
+	{{ else }}
+	reverse_proxy @cloudflared {{ $e.service }} {
+		header_up X-Forwarded-For {http.request.header.CF-Connecting-IP}
+		{{ if hasPrefix "https://" $e.service }}
+		transport http {
+			tls_insecure_skip_verify
+		}
+		{{ end }}
+	}
+	{{ end }}
+	reverse_proxy {{ $e.service }} {{ if hasPrefix "https://" $e.service }}{
+		transport http {
+			tls_insecure_skip_verify
+		}
+	}{{ end }}
+}
+{{ end }}

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/check_readiness.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+exec curl --fail --silent --output /dev/null --max-time 1 \
+    --cacert /data/caddy/pki/authorities/local/root.crt \
+    https://caddy.localhost/healthz

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/condition_caddy.sh

@@ -0,0 +1,11 @@
+#!/command/with-contenv bashio
+# shellcheck shell=bash
+# ==============================================================================
+# Home Assistant Add-on: Cloudflared
+#
+# Decides whether to run Caddy based on the use_builtin_proxy setting or not.
+# ==============================================================================
+
+if bashio::config.true 'use_builtin_proxy'; then
+    touch /etc/s6-overlay/s6-rc.d/user/contents.d/caddy
+fi

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/finish

@@ -0,0 +1,30 @@
+#!/command/with-contenv bashio
+# shellcheck shell=bash
+# ==============================================================================
+# Home Assistant Add-on: Cloudflared
+# Take down the S6 supervision tree when Caddy fails
+# ==============================================================================
+
+readonly exit_code_service="${1}"
+readonly exit_code_signal="${2}"
+exit_code_container=$(cat /run/s6-linux-init-container-results/exitcode)
+readonly exit_code_container
+readonly service="caddy"
+
+bashio::log.info \
+    "Service ${service} exited with code ${exit_code_service}" \
+    "(by signal ${exit_code_signal})"
+
+if [[ "${exit_code_service}" -eq 256 ]]; then
+    if [[ "${exit_code_container}" -eq 0 ]]; then
+        echo $((128 + exit_code_signal)) >/run/s6-linux-init-container-results/exitcode
+    fi
+    if [[ "${exit_code_signal}" -eq 15 ]]; then
+        exec /run/s6/basedir/bin/halt
+    fi
+elif [[ "${exit_code_service}" -ne 0 ]]; then
+    if [[ "${exit_code_container}" -eq 0 ]]; then
+        echo "${exit_code_service}" >/run/s6-linux-init-container-results/exitcode
+    fi
+    exec /run/s6/basedir/bin/halt
+fi

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/notification-fd

@@ -0,0 +1 @@
+3

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/run

@@ -0,0 +1,6 @@
+#!/command/with-contenv bashio
+# shellcheck shell=bash
+
+bashio::log.info "Starting Caddy..."
+exec s6-notifyoncheck -c /etc/s6-overlay/s6-rc.d/caddy/check_readiness.sh \
+    env XDG_DATA_HOME=/data caddy run --config /etc/caddy/Caddyfile

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/timeout-kill

@@ -0,0 +1 @@
+15000

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/timeout-up

@@ -0,0 +1 @@
+15000

cloudflared/rootfs/etc/s6-overlay/s6-rc.d/caddy/type

@@ -0,0 +1 @@
+longrun