Support TLS for ingress (#27)

* Swap to caddy and support TLS

* Add logging

* test pass

* check if timing was issue

* Raf style AI review

- Added `os.Remove(d.paths.CaddyPIDFile())` when `waitForAdmin` times out to prevent stale PID files

- Changed `append(redirectRoutes, routes...)` to `slices.Concat(redirectRoutes, routes)` to avoid mutating original slices

- Created `DNSProvider` type with constants `DNSProviderNone`, `DNSProviderCloudflare`, `DNSProviderRoute53`
- Added `ParseDNSProvider()` function that returns an error for unknown providers
- Server now fails to start if an invalid DNS provider is configured

- Updated `tls` field description: "Use with match.port=443 for standard HTTPS"

- Replaced Envoy references with Caddy
- Added `CADDY_STOP_ON_SHUTDOWN` with note to set `false` for production
- Added TLS Ingress section documenting ACME configuration for Cloudflare/Route53
- Added all new environment variables to the table

- Created `waitForProcessExit()` helper that polls every 100ms
- `Stop()` now uses polling instead of `time.Sleep(2 * time.Second)`

- Added debug logging when `Process.Kill()` fails in `Stop()`

- `TestCreateIngress_TLSWithoutACME` verifies error when TLS requested but ACME not configured

- Removed separate `logging` section from Caddy JSON config
- Caddy now writes JSON logs to stderr, captured to `caddy.log` by `daemon.go`
- Log forwarder now tails `CaddyLogFile()` instead of separate `CaddySystemLog()`
- Removed unused `CaddySystemLog()` path method

- `TestGenerateConfig_MixedTLSAndNonTLS` verifies correct behavior with both TLS and non-TLS rules in the same ingress

- Removed unused `ErrCaddyNotRunning`

* More review

Summary of Changes

1. Fixed non-deterministic listenAddrs order (`lib/ingress/config.go`)
- Ports are now collected and sorted before building listen addresses
- Added `TestGenerateConfig_DeterministicOrder` test to verify consistent output

2. Fixed DNS challenge config for Caddy modules (`lib/ingress/config.go`)
- Updated `buildDNSChallengeConfig()` to use correct Caddy DNS module format
- Consolidated propagation settings to apply to all providers:
  - `DNS_PROPAGATION_TIMEOUT` - works for both Cloudflare and Route53
  - `DNS_RESOLVERS` - custom resolvers for propagation checking

3. Updated Makefile for xcaddy builds
- Changed from downloading pre-built Caddy to building with xcaddy
- Added `build-caddy` and `build-caddy-binaries` targets
- Includes `github.com/caddy-dns/cloudflare` and `github.com/caddy-dns/route53` modules

4. Added test for XDG_DATA_HOME / storage paths (`lib/ingress/config_test.go`)
- `TestGenerateConfig_StoragePath` verifies storage configuration is correct
- Updated `TestGenerateConfig_EmptyIngresses` to check storage section

5. Used slices.Concat for safer append (`lib/ingress/manager.go`)
- Changed `append(existingIngresses, ingress)` to `slices.Concat(existingIngresses, []Ingress{ingress})`

6. Match config path in findCaddyPID (`lib/ingress/daemon.go`)
- Now matches both "caddy run" and the specific config path
- Prevents collision with other Caddy/hypeman instances

7. Reduced admin API timeout to 10s (`lib/ingress/daemon.go`)
- Changed from 30s to 10s for faster failure detection

8. Fixed CaddyStopOnShutdown default (`cmd/api/config/config.go`)
- Default is now `false` (Caddy persists through hypeman restarts)
- Removed "(default: X)" comments from struct fields

9. Updated .env.example
- Added all CADDY_* and ACME_* variables
- Documented all three Route53 auth methods

10. AWS Route53 authentication methods (`lib/ingress/config.go`)
- **Method 1**: Explicit credentials (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
- **Method 2**: Named profile (`AWS_PROFILE`)
- **Method 3**: IAM role/instance profile (leave credentials empty)

* fix build

* error handle port taken

* 404 hint: didn't match hostname

* version check

* Fix caddy shutdown

* Configurable allowed domains

* Domain allow list

* Match ingress by partial id and name

* Use SNI in test

* Tls integration tests passes locally

* Add a few logs

* Use DNS for discovery and support instance name matching

* Accept using sudo for tests, get caching and parallelism

* Remove route53 for now

* Docker login work when run tests with root

* Fix one more spot with unauth'd docker pull

* Review

Summary of Changes

1. Wildcard & Pattern Matching Logic (`lib/ingress/config.go`)
- Added handling for global wildcard `*` pattern that matches any domain
- Added comprehensive documentation explaining wildcard behavior
- Restructured code for clarity with detailed comments

2. Edge Case Tests (`lib/ingress/config_test.go`)
- Added 12 new test cases covering:
  - Global `*` wildcard matching
  - Single-char subdomains
  - Hyphenated and numeric subdomains
  - Empty prefix handling
  - Apex domain + wildcard combination
  - Empty patterns in lists

3. DNS Provider Constants (`lib/ingress/config.go`)
- Added `caddyProviderCloudflare` constant for Caddy module name
- Added `SupportedDNSProviders()` helper function for future-proof error messages
- Updated `ParseDNSProvider()` to use dynamic error message
- Updated `buildDNSChallengeConfig()` to use constant and log warnings for unknown providers

4. Context Propagation (`lib/dns/server.go`)
- Added `ctx` field to Server struct to store base context
- Store context from `Start()` for use in resolver calls
- Updated `handleAQuery()` to use stored context instead of `context.Background()`
- Improved AAAA comment explaining intentional empty response behavior

5. Duration Validation (`lib/providers/providers.go`)
- Added validation for `DNS_PROPAGATION_TIMEOUT` at startup
- Validates Go duration format (e.g., `2m`, `120s`, `1h`)
- Provides helpful error message with expected format examples

6. Consistency Improvements
- **`lib/ingress/manager.go`**: Replaced slice comparison with `strings.HasPrefix()` for ID prefix matching
- **`lib/ingress/daemon.go`**: Added documented constants for polling intervals (`adminPollInterval`, `processExitPollInterval`)

7. TLS Documentation (`lib/ingress/README.md`)
- Expanded TLS/HTTPS section with:
  - TLS requirements section
  - Detailed `TLS_ALLOWED_DOMAINS` documentation with pattern matching table
  - Wildcard behavior explanation
  - Example configurations
  - Warning scenarios documentation
- Updated ACME/TLS Settings table with new variables

* Address review comments

1. Removed Route53 Documentation (.env.example)
- Removed the AWS Route53 DNS provider documentation section since it's not actually implemented
- Updated ACME_DNS_PROVIDER comment to only mention cloudflare

2. Changed Default Ports to 0 for Random Assignment
- lib/dns/server.go: Changed DefaultPort from 5353 to 0 with a comment explaining this prevents conflicts on shared dev machines
- cmd/api/config/config.go: Changed CADDY_ADMIN_PORT default from 2019 to 0 with an explanatory comment
- Updated .env.example to reflect the new default

3. Fixed DNS Server Context Handling (lib/dns/server.go)
- Removed the stored ctx field from the Server struct
- Added a new resolverTimeout constant (5 seconds)
- Updated handleAQuery to create a fresh context.Background() with timeout for each DNS query
- This ensures DNS queries don't fail if the parent context is cancelled during shutdown

4. Added Comment in lib/ingress/daemon.go
- Added a comment explaining why context.Background() is intentionally used for the startup wait (to ensure it isn't cancelled if the parent context times out)

5. Simplified Test Code (lib/instances/manager_test.go)
- Removed the confusing if envPath := ...; true construct
- Simplified to just the directory walk loop for loading .env files

6. Added Startup Warning (lib/ingress/manager.go)
- Added a check in Initialize() that warns if any existing TLS ingress has a hostname not in the allowed domains list
- Logs the ingress name, hostname, and allowed domains for easier debugging

Author: sjmiller609

.air.toml

@@ -16,14 +16,14 @@ tmp_dir = "tmp"
   include_dir = []
   include_ext = ["go", "tpl", "tmpl", "html", "yaml"]
   include_file = []
-  kill_delay = "0s"
+  kill_delay = "5s"
   log = "build-errors.log"
   poll = false
   poll_interval = 0
   post_cmd = []
   rerun = false
   rerun_delay = 500
-  send_interrupt = false
+  send_interrupt = true
   stop_on_error = false
 
 [color]

.env.example

@@ -1,2 +1,78 @@
+# Required
 JWT_SECRET='your-secret-key-here'
-DATA_DIR=/home/your-user/hypeman/.datadir # or leave unset to default to /var/lib/hypeman
+
+# Data directory (default: /var/lib/hypeman)
+DATA_DIR=/var/lib/hypeman
+
+# Server configuration
+# PORT=8080
+
+# Network configuration
+# BRIDGE_NAME=vmbr0
+# SUBNET_CIDR=10.100.0.0/16
+# SUBNET_GATEWAY=         # empty = derived from SUBNET_CIDR
+# UPLINK_INTERFACE=       # empty = auto-detect from default route
+# DNS_SERVER=1.1.1.1
+
+# Logging
+# LOG_LEVEL=info          # debug, info, warn, error
+
+# Caddy / Ingress configuration
+# CADDY_LISTEN_ADDRESS=0.0.0.0
+# CADDY_ADMIN_ADDRESS=127.0.0.1
+# CADDY_ADMIN_PORT=0               # 0 = random port (prevents conflicts on shared dev machines)
+# CADDY_STOP_ON_SHUTDOWN=false   # Set to true if you want Caddy to stop when hypeman stops
+
+# =============================================================================
+# TLS / ACME Configuration (for HTTPS ingresses)
+# =============================================================================
+# Required for TLS ingresses:
+# [email protected]
+# ACME_DNS_PROVIDER=cloudflare
+
+# IMPORTANT: You must specify which domains are allowed for TLS certificates.
+# This prevents typos and ensures you only request certificates for domains you control.
+# TLS_ALLOWED_DOMAINS=*.example.com,api.other.com
+# Supports:
+#   - Exact matches: api.example.com
+#   - Wildcard subdomains: *.example.com (matches foo.example.com, NOT foo.bar.example.com)
+# If not set, no TLS ingresses are allowed.
+
+# Optional ACME settings:
+# ACME_CA=                       # empty = Let's Encrypt production
+                                 # Use https://acme-staging-v02.api.letsencrypt.org/directory for testing
+
+# DNS propagation settings (applies to all providers):
+# DNS_PROPAGATION_TIMEOUT=2m     # Max time to wait for DNS propagation
+# DNS_RESOLVERS=1.1.1.1,8.8.8.8  # Custom DNS resolvers for propagation checking
+
+# -----------------------------------------------------------------------------
+# Cloudflare DNS Provider (ACME_DNS_PROVIDER=cloudflare)
+# -----------------------------------------------------------------------------
+# CLOUDFLARE_API_TOKEN=your-api-token
+# Token needs Zone:DNS:Edit permissions for the domains you want certificates for
+# =============================================================================
+# OpenTelemetry Configuration
+# =============================================================================
+# OTEL_ENABLED=false
+# OTEL_ENDPOINT=127.0.0.1:4317
+# OTEL_SERVICE_NAME=hypeman
+# OTEL_SERVICE_INSTANCE_ID=          # default: hostname
+# OTEL_INSECURE=true
+# ENV=dev                             # deployment environment
+
+# =============================================================================
+# Resource Limits
+# =============================================================================
+# Per-instance limits
+# MAX_VCPUS_PER_INSTANCE=16
+# MAX_MEMORY_PER_INSTANCE=32GB
+
+# Aggregate limits (0 or empty = unlimited)
+# MAX_TOTAL_VCPUS=0
+# MAX_TOTAL_MEMORY=
+# MAX_TOTAL_VOLUME_STORAGE=
+
+# Other limits
+# MAX_CONCURRENT_BUILDS=1
+# MAX_OVERLAY_SIZE=100GB

.github/workflows/test.yml

@@ -35,4 +35,14 @@ jobs:
         run: make build
 
       - name: Run tests
+        env:
+          # Docker auth for tests running as root (sudo)
+          DOCKER_CONFIG: /home/debianuser/.docker
+          # TLS/ACME testing (optional - tests will skip if not configured)
+          ACME_EMAIL: ${{ secrets.ACME_EMAIL }}
+          ACME_DNS_PROVIDER: "cloudflare"
+          ACME_CA: "https://acme-staging-v02.api.letsencrypt.org/directory"
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          TLS_TEST_DOMAIN: "test.hypeman-development.com"
+          TLS_ALLOWED_DOMAINS: '*.hypeman-development.com'
         run: make test

.gitignore

@@ -22,5 +22,5 @@ cloud-hypervisor/**
 lib/system/exec_agent/exec-agent
 
 # Envoy binaries
-lib/ingress/binaries/envoy/*/*/envoy
+lib/ingress/binaries/**
 dist/**

Makefile

@@ -1,5 +1,5 @@
 SHELL := /bin/bash
-.PHONY: oapi-generate generate-vmm-client generate-wire generate-all dev build test install-tools gen-jwt download-ch-binaries download-ch-spec ensure-ch-binaries download-envoy-binaries ensure-envoy-binaries release-prep
+.PHONY: oapi-generate generate-vmm-client generate-wire generate-all dev build test install-tools gen-jwt download-ch-binaries download-ch-spec ensure-ch-binaries build-caddy-binaries build-caddy ensure-caddy-binaries release-prep
 
 # Directory where local binaries will be installed
 BIN_DIR ?= $(CURDIR)/bin
@@ -12,6 +12,7 @@ OAPI_CODEGEN ?= $(BIN_DIR)/oapi-codegen
 AIR ?= $(BIN_DIR)/air
 WIRE ?= $(BIN_DIR)/wire
 GODOTENV ?= $(BIN_DIR)/godotenv
+XCADDY ?= $(BIN_DIR)/xcaddy
 
 # Install oapi-codegen
 $(OAPI_CODEGEN): | $(BIN_DIR)
@@ -29,7 +30,11 @@ $(WIRE): | $(BIN_DIR)
 $(GODOTENV): | $(BIN_DIR)
 	GOBIN=$(BIN_DIR) go install github.com/joho/godotenv/cmd/godotenv@latest
 
-install-tools: $(OAPI_CODEGEN) $(AIR) $(WIRE) $(GODOTENV)
+# Install xcaddy for building Caddy with plugins
+$(XCADDY): | $(BIN_DIR)
+	GOBIN=$(BIN_DIR) go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
+
+install-tools: $(OAPI_CODEGEN) $(AIR) $(WIRE) $(GODOTENV) $(XCADDY)
 
 # Download Cloud Hypervisor binaries
 download-ch-binaries:
@@ -49,18 +54,46 @@ download-ch-binaries:
 	@chmod +x lib/vmm/binaries/cloud-hypervisor/v*/*/cloud-hypervisor
 	@echo "Binaries downloaded successfully"
 
-# Download Envoy binaries
-download-envoy-binaries:
-	@echo "Downloading Envoy binaries..."
-	@mkdir -p lib/ingress/binaries/envoy/v1.36/{x86_64,aarch64}
-	@echo "Downloading Envoy v1.36.3 for x86_64..."
-	@curl -L -o lib/ingress/binaries/envoy/v1.36/x86_64/envoy \
-		https://github.com/envoyproxy/envoy/releases/download/v1.36.3/envoy-1.36.3-linux-x86_64
-	@echo "Downloading Envoy v1.36.3 for aarch64..."
-	@curl -L -o lib/ingress/binaries/envoy/v1.36/aarch64/envoy \
-		https://github.com/envoyproxy/envoy/releases/download/v1.36.3/envoy-1.36.3-linux-aarch_64
-	@chmod +x lib/ingress/binaries/envoy/v1.36/*/envoy
-	@echo "Envoy binaries downloaded successfully"
+# Caddy version and modules
+CADDY_VERSION := v2.10.2
+CADDY_DNS_MODULES := --with github.com/caddy-dns/cloudflare
+
+# Build Caddy with DNS modules using xcaddy
+# xcaddy builds Caddy from source with the specified modules
+build-caddy-binaries: $(XCADDY)
+	@echo "Building Caddy $(CADDY_VERSION) with DNS modules..."
+	@mkdir -p lib/ingress/binaries/caddy/$(CADDY_VERSION)/x86_64
+	@mkdir -p lib/ingress/binaries/caddy/$(CADDY_VERSION)/aarch64
+	@echo "Building Caddy $(CADDY_VERSION) for x86_64..."
+	GOOS=linux GOARCH=amd64 $(XCADDY) build $(CADDY_VERSION) \
+		$(CADDY_DNS_MODULES) \
+		--output lib/ingress/binaries/caddy/$(CADDY_VERSION)/x86_64/caddy
+	@echo "Building Caddy $(CADDY_VERSION) for aarch64..."
+	GOOS=linux GOARCH=arm64 $(XCADDY) build $(CADDY_VERSION) \
+		$(CADDY_DNS_MODULES) \
+		--output lib/ingress/binaries/caddy/$(CADDY_VERSION)/aarch64/caddy
+	@chmod +x lib/ingress/binaries/caddy/$(CADDY_VERSION)/*/caddy
+	@echo "Caddy binaries built successfully with DNS modules"
+
+# Build Caddy for current architecture only (faster for development)
+build-caddy: $(XCADDY)
+	@echo "Building Caddy $(CADDY_VERSION) with DNS modules for current architecture..."
+	@ARCH=$$(uname -m); \
+	if [ "$$ARCH" = "x86_64" ]; then \
+		CADDY_ARCH=x86_64; \
+		GOARCH=amd64; \
+	elif [ "$$ARCH" = "aarch64" ] || [ "$$ARCH" = "arm64" ]; then \
+		CADDY_ARCH=aarch64; \
+		GOARCH=arm64; \
+	else \
+		echo "Unsupported architecture: $$ARCH"; exit 1; \
+	fi; \
+	mkdir -p lib/ingress/binaries/caddy/$(CADDY_VERSION)/$$CADDY_ARCH; \
+	GOOS=linux GOARCH=$$GOARCH $(XCADDY) build $(CADDY_VERSION) \
+		$(CADDY_DNS_MODULES) \
+		--output lib/ingress/binaries/caddy/$(CADDY_VERSION)/$$CADDY_ARCH/caddy; \
+	chmod +x lib/ingress/binaries/caddy/$(CADDY_VERSION)/$$CADDY_ARCH/caddy
+	@echo "Caddy binary built successfully"
 
 # Download Cloud Hypervisor API spec
 download-ch-spec:
@@ -107,12 +140,20 @@ ensure-ch-binaries:
 		$(MAKE) download-ch-binaries; \
 	fi
 
-# Check if Envoy binaries exist, download if missing
-.PHONY: ensure-envoy-binaries
-ensure-envoy-binaries:
-	@if [ ! -f lib/ingress/binaries/envoy/v1.36/x86_64/envoy ]; then \
-		echo "Envoy binaries not found, downloading..."; \
-		$(MAKE) download-envoy-binaries; \
+# Check if Caddy binaries exist, build if missing
+.PHONY: ensure-caddy-binaries
+ensure-caddy-binaries:
+	@ARCH=$$(uname -m); \
+	if [ "$$ARCH" = "x86_64" ]; then \
+		CADDY_ARCH=x86_64; \
+	elif [ "$$ARCH" = "aarch64" ] || [ "$$ARCH" = "arm64" ]; then \
+		CADDY_ARCH=aarch64; \
+	else \
+		echo "Unsupported architecture: $$ARCH"; exit 1; \
+	fi; \
+	if [ ! -f lib/ingress/binaries/caddy/$(CADDY_VERSION)/$$CADDY_ARCH/caddy ]; then \
+		echo "Caddy binary not found, building with xcaddy..."; \
+		$(MAKE) build-caddy; \
 	fi
 
 # Build exec-agent (guest binary) into its own directory for embedding
@@ -121,7 +162,7 @@ lib/system/exec_agent/exec-agent: lib/system/exec_agent/main.go
 	cd lib/system/exec_agent && CGO_ENABLED=0 go build -ldflags="-s -w" -o exec-agent .
 
 # Build the binary
-build: ensure-ch-binaries ensure-envoy-binaries lib/system/exec_agent/exec-agent | $(BIN_DIR)
+build: ensure-ch-binaries ensure-caddy-binaries lib/system/exec_agent/exec-agent | $(BIN_DIR)
 	go build -tags containers_image_openpgp -o $(BIN_DIR)/hypeman ./cmd/api
 
 # Build exec CLI
@@ -132,45 +173,18 @@ build-exec: | $(BIN_DIR)
 build-all: build build-exec
 
 # Run in development mode with hot reload
-dev: $(AIR)
+dev: ensure-ch-binaries ensure-caddy-binaries lib/system/exec_agent/exec-agent $(AIR)
 	$(AIR) -c .air.toml
 
-# Run tests
-# Compile test binaries and grant network capabilities (runs as user, not root)
+# Run tests (as root for network capabilities, enables caching and parallelism)
 # Usage: make test                              - runs all tests
 #        make test TEST=TestCreateInstanceWithNetwork  - runs specific test
-test: ensure-ch-binaries ensure-envoy-binaries lib/system/exec_agent/exec-agent
-	@echo "Building test binaries..."
-	@mkdir -p $(BIN_DIR)/tests
-	@for pkg in $$(go list -tags containers_image_openpgp ./...); do \
-		pkg_name=$$(basename $$pkg); \
-		go test -c -tags containers_image_openpgp -o $(BIN_DIR)/tests/$$pkg_name.test $$pkg 2>/dev/null || true; \
-	done
-	@echo "Granting capabilities to test binaries..."
-	@for test in $(BIN_DIR)/tests/*.test; do \
-		if [ -f "$$test" ]; then \
-			sudo setcap 'cap_net_admin,cap_net_bind_service=+eip' $$test 2>/dev/null || true; \
-		fi; \
-	done
-	@echo "Running tests as current user with capabilities..."
+test: ensure-ch-binaries ensure-caddy-binaries lib/system/exec_agent/exec-agent
 	@if [ -n "$(TEST)" ]; then \
 		echo "Running specific test: $(TEST)"; \
-		for test in $(BIN_DIR)/tests/*.test; do \
-			if [ -f "$$test" ]; then \
-				echo ""; \
-				echo "Checking $$(basename $$test) for $(TEST)..."; \
-				$$test -test.run=$(TEST) -test.v -test.timeout=60s 2>&1 | grep -q "PASS\|FAIL" && \
-				$$test -test.run=$(TEST) -test.v -test.timeout=60s || true; \
-			fi; \
-		done; \
+		sudo env "PATH=$$PATH" "DOCKER_CONFIG=$${DOCKER_CONFIG:-$$HOME/.docker}" go test -tags containers_image_openpgp -run=$(TEST) -v -timeout=180s ./...; \
 	else \
-		for test in $(BIN_DIR)/tests/*.test; do \
-			if [ -f "$$test" ]; then \
-				echo ""; \
-				echo "Running $$(basename $$test)..."; \
-				$$test -test.v -test.parallel=10 -test.timeout=60s || exit 1; \
-			fi; \
-		done; \
+		sudo env "PATH=$$PATH" "DOCKER_CONFIG=$${DOCKER_CONFIG:-$$HOME/.docker}" go test -tags containers_image_openpgp -v -timeout=180s ./...; \
 	fi
 
 # Generate JWT token for testing
@@ -189,5 +203,5 @@ clean:
 
 # Prepare for release build (called by GoReleaser)
 # Downloads all embedded binaries and builds embedded components
-release-prep: download-ch-binaries download-envoy-binaries lib/system/exec_agent/exec-agent
+release-prep: download-ch-binaries ensure-caddy-binaries lib/system/exec_agent/exec-agent
 	go mod tidy

README.md

@@ -60,7 +60,7 @@ getcap ./bin/hypeman
 
 **File Descriptor Limits:**
 
-Envoy (used for ingress) requires a higher file descriptor limit than the default on some systems (root defaults to 1024 on many systems). If you see "Too many open files" errors, increase the limit:
+Caddy (used for ingress) requires a higher file descriptor limit than the default on some systems. If you see "Too many open files" errors, increase the limit:
 
 ```bash
 # Check current limit (also check with: sudo bash -c 'ulimit -n')
@@ -98,11 +98,18 @@ Hypeman can be configured using the following environment variables:
 | `OTEL_ENDPOINT` | OTLP gRPC endpoint | `127.0.0.1:4317` |
 | `OTEL_SERVICE_INSTANCE_ID` | Instance ID for telemetry (differentiates multiple servers) | hostname |
 | `LOG_LEVEL` | Default log level (debug, info, warn, error) | `info` |
-| `LOG_LEVEL_<SUBSYSTEM>` | Per-subsystem log level (API, IMAGES, INSTANCES, NETWORK, VOLUMES, VMM, SYSTEM, EXEC) | inherits default |
-| `ENVOY_LISTEN_ADDRESS` | Address for Envoy ingress listeners | `0.0.0.0` |
-| `ENVOY_ADMIN_ADDRESS` | Address for Envoy admin API | `127.0.0.1` |
-| `ENVOY_ADMIN_PORT` | Port for Envoy admin API | `9901` |
-| `ENVOY_STOP_ON_SHUTDOWN` | Stop Envoy when hypeman shuts down (if false, Envoy continues running) | `false` |
+| `LOG_LEVEL_<SUBSYSTEM>` | Per-subsystem log level (API, IMAGES, INSTANCES, NETWORK, VOLUMES, VMM, SYSTEM, EXEC, CADDY) | inherits default |
+| `CADDY_LISTEN_ADDRESS` | Address for Caddy ingress listeners | `0.0.0.0` |
+| `CADDY_ADMIN_ADDRESS` | Address for Caddy admin API | `127.0.0.1` |
+| `CADDY_ADMIN_PORT` | Port for Caddy admin API | `2019` |
+| `CADDY_STOP_ON_SHUTDOWN` | Stop Caddy when hypeman shuts down (set to `true` for dev) | `false` |
+| `ACME_EMAIL` | Email for ACME certificate registration (required for TLS ingresses) | _(empty)_ |
+| `ACME_DNS_PROVIDER` | DNS provider for ACME challenges: `cloudflare` | _(empty)_ |
+| `ACME_CA` | ACME CA URL (empty = Let's Encrypt production) | _(empty)_ |
+| `TLS_ALLOWED_DOMAINS` | Comma-separated allowed domains for TLS (e.g., `*.example.com,api.other.com`) | _(empty)_ |
+| `DNS_PROPAGATION_TIMEOUT` | Max time to wait for DNS propagation (e.g., `2m`) | _(empty)_ |
+| `DNS_RESOLVERS` | Comma-separated DNS resolvers for propagation checking | _(empty)_ |
+| `CLOUDFLARE_API_TOKEN` | Cloudflare API token (when using `cloudflare` provider) | _(empty)_ |
 
 **Important: Subnet Configuration**
 
@@ -111,7 +118,7 @@ The default subnet `10.100.0.0/16` is chosen to avoid common conflicts. Hypeman
 If you need a different subnet, set `SUBNET_CIDR` in your environment. The gateway is automatically derived as the first IP in the subnet (e.g., `10.100.0.0/16` → `10.100.0.1`).
 
 **Alternative subnets if needed:**
-- `172.30.0.0/16` - Private range between common Docker (172.17.x.x) and AWS (172.31.x.x) ranges
+- `172.30.0.0/16` - Private range between common Docker (172.17.x.x) and cloud provider (172.31.x.x) ranges
 - `10.200.0.0/16` - Another private range option
 
 **Example:**
@@ -144,6 +151,39 @@ ip route show
 ```
 Pick the interface used by the default route (usually the line starting with `default`). Avoid using local bridges like `docker0`, `br-...`, `virbr0`, or `vmbr0` as the uplink; those are typically internal virtual networks, not your actual internet-facing interface.
 
+**TLS Ingress (HTTPS)**
+
+Hypeman uses Caddy with automatic ACME certificates for TLS termination. Certificates are issued via DNS-01 challenges (Cloudflare).
+
+To enable TLS ingresses:
+
+1. Configure ACME credentials in your `.env`:
+```bash
+# Required for any TLS ingress
+[email protected]
+
+# For Cloudflare
+ACME_DNS_PROVIDER=cloudflare
+CLOUDFLARE_API_TOKEN=your-api-token
+```
+
+2. Create an ingress with TLS enabled:
+```bash
+curl -X POST http://localhost:8080/v1/ingresses \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-https-app",
+    "rules": [{
+      "match": {"hostname": "app.example.com", "port": 443},
+      "target": {"instance": "my-instance", "port": 8080},
+      "tls": true,
+      "redirect_http": true
+    }]
+  }'
+```
+
+Certificates are stored in `$DATA_DIR/caddy/data/` and auto-renewed by Caddy.
+
 **Setup:**
 
 ```bash