From e61d96d154d6dc49a393c214184f8b59bde0d8da Mon Sep 17 00:00:00 2001
From: Donal McBreen <donal@37signals.com>
Date: Wed, 18 Jun 2025 11:09:13 +0100
Subject: [PATCH] Update custom cert docs

Remove ssl: ..., reword some of the docs and ensure the formatting is
correct.
---
 lib/kamal/configuration/docs/proxy.yml | 24 ++++++++++--------------
 lib/kamal/configuration/validator.rb   |  6 +++---
 2 files changed, 13 insertions(+), 17 deletions(-)

diff --git a/lib/kamal/configuration/docs/proxy.yml b/lib/kamal/configuration/docs/proxy.yml
index 3eed868b..201e6083 100644
--- a/lib/kamal/configuration/docs/proxy.yml
+++ b/lib/kamal/configuration/docs/proxy.yml
@@ -45,27 +45,23 @@ proxy:
   # unless you explicitly set `forward_headers: true`
   #
   # Defaults to `false`:
-  ssl: ...
+  ssl: true
 
   # Custom SSL certificate
   #
   # In some cases, using Let's Encrypt for automatic certificate management is not an
-  # option, for example if you are running from host than one host. Or you may already
-  # have SSL certificates issued by a different Certificate Authority (CA).
-  # Kamal supports loading custom SSL certificates
-  # directly from secrets.
+  # option, for example if you are running from host than one host.
   #
-  # Examples:
-  #   ssl: true              # Enable SSL with Let's Encrypt
-  #   ssl: false             # Disable SSL
-  #   ssl:                   # Enable custom SSL
-  #     certificate_pem: CERTIFICATE_PEM
-  #     private_key_pem: PRIVATE_KEY_PEM
+  # Or you may already have SSL certificates issued by a different Certificate Authority (CA).
   #
+  # Kamal supports loading custom SSL certificates directly from secrets. You should
+  # pass a hash mapping the `certificate_pem` and `private_key_pem` to the secret names.
+  ssl:
+    certificate_pem: CERTIFICATE_PEM
+    private_key_pem: PRIVATE_KEY_PEM
   # ### Notes
-  # - If the certificate or key is missing or invalid, kamal-proxy will fail to start.
-  # - Always handle SSL certificates and private keys securely. Avoid hard-coding them in deploy.yml files or source control.
-  # - For automated certificate management, consider using the built-in Let's Encrypt integration instead.
+  # - If the certificate or key is missing or invalid, deployments will fail.
+  # - Always handle SSL certificates and private keys securely. Avoid hard-coding them in source control.
 
   # SSL redirect
   #
diff --git a/lib/kamal/configuration/validator.rb b/lib/kamal/configuration/validator.rb
index 7d3d9315..6389d793 100644
--- a/lib/kamal/configuration/validator.rb
+++ b/lib/kamal/configuration/validator.rb
@@ -24,11 +24,11 @@ class Kamal::Configuration::Validator
             example_value = example[key]
 
             if example_value == "..."
-              if key.to_s == "ssl"
-                validate_type! value, TrueClass, FalseClass, Hash
-              elsif key.to_s != "proxy" || !boolean?(value.class)
+              unless key.to_s == "proxy" && boolean?(value.class)
                 validate_type! value, *(Array if key == :servers), Hash
               end
+            elsif key.to_s == "ssl"
+                validate_type! value, TrueClass, FalseClass, Hash
             elsif key == "hosts"
               validate_servers! value
             elsif example_value.is_a?(Array)