Doc updates

lib/kamal/configuration/docs/builder.yml

@@ -2,10 +2,6 @@
 #
 # The builder configuration controls how the application is built with `docker build`
 #
-# If no configuration is specified, Kamal will:
-# 1. Create a buildx context called `kamal-local-docker-container`, using the docker-container driver
-# 2. Use `docker build` to build a multiarch image for linux/amd64,linux/arm64 with that context
-#
 # See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information
 
 # Builder options
@@ -78,7 +74,7 @@ builder:
 
   # Build secrets
   #
-  # Values are read from the .kamal/secrets.
+  # Values are read from .kamal/secrets.
   #
   secrets:
     - SECRET1

lib/kamal/configuration/docs/configuration.yml

@@ -36,6 +36,8 @@ image: my-image
 labels:
   my-label: my-value
 
+# Volumes
+#
 # Additional volumes to mount into the container
 volumes:
   - /path/on/host:/path/in/container:ro
@@ -58,7 +60,7 @@ servers:
 env:
   ...
 
-# Asset Bridging
+# Asset Path
 #
 # Used for asset bridging across deployments, default to `nil`
 #
@@ -74,6 +76,8 @@ env:
 # To configure this, set the path to the assets:
 asset_path: /path/to/assets
 
+# Hooks path
+#
 # Path to hooks, defaults to `.kamal/hooks`
 # See https://kamal-deploy.org/docs/hooks for more information
 hooks_path: /user_home/kamal/hooks
@@ -83,7 +87,7 @@ hooks_path: /user_home/kamal/hooks
 # Whether deployments require a destination to be specified, defaults to `false`
 require_destination: true
 
-# The primary role
+# Primary role
 #
 # This defaults to `web`, but if you have no web role, you can change this
 primary_role: workers

lib/kamal/configuration/docs/env.yml

@@ -12,18 +12,31 @@ env:
   DATABASE_HOST: mysql-db1
   DATABASE_PORT: 3306
 
-# Using .kamal/secrets file to load required environment variables
+# Secrets
 #
-# Kamal uses dotenv to automatically load environment variables set in the .kamal/secrets file.
+# Kamal uses dotenv to automatically load environment variables set in the `.kamal/secrets` file.
 #
-# This file can be used to set variables like KAMAL_REGISTRY_PASSWORD or database passwords.
+# If you are using destinations, secrets will instead be read from `.kamal/secrets-<DESTINATION>` if
+# it exists.
+#
+# Common secrets across all destinations can be set in `.kamal/secrets-common`.
+#
+# This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords.
 # You can use variable or command substitution in the secrets file.
 #
 # ```
 # KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
 # RAILS_MASTER_KEY=$(cat config/master.key)
 # ```
 #
+# You can also use [secret helpers](../commands/secrets) for some common password managers.
+# ```
+# SECRETS=$(kamal secrets fetch ...)
+#
+# REGISTRY_PASSWORD=$(kamal secrets extract REGISTRY_PASSWORD $SECRETS)
+# DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS)
+# ```
+#
 # If you store secrets directly in .kamal/secrets, ensure that it is not checked into version control.
 #
 # To pass the secrets you should list them under the `secret` key. When you do this the

lib/kamal/configuration/docs/proxy.yml

@@ -91,7 +91,7 @@ proxy:
 
   # Forward headers
   #
-  # Whether to forward the X-Forwarded-For and X-Forwarded-Proto headers (defaults to false)
+  # Whether to forward the X-Forwarded-For and X-Forwarded-Proto headers.
   #
   # If you are behind a trusted proxy, you can set this to true to forward the headers.
   #

lib/kamal/configuration/docs/role.yml

@@ -26,8 +26,12 @@ servers:
   #
   # When there are other options to set, the list of hosts goes under the `hosts` key
   #
-  # By default only the primary role uses a proxy, but you can set `proxy` to change
-  # it.
+  # By default only the primary role uses a proxy.
+  #
+  # For other roles, you can set it to `proxy: true` enable it and inherit the root proxy
+  # configuration or provide a map of options to override the root configuration.
+  #
+  # For the primary role, you can set `proxy: false` to disable the proxy.
   #
   # You can also set a custom cmd to run in the container, and overwrite other settings
   # from the root configuration.