feat: easier way to disable HTTPS and pass global options

dunglas · Oct 10, 2021 · 71657c4 · 71657c4
1 parent f38a12d
commit 71657c4
Show file tree

Hide file tree

Showing 8 changed files with 69 additions and 71 deletions.
diff --git a/Caddyfile b/Caddyfile
@@ -1,34 +1,27 @@
 # Learn how to configure the Mercure.rocks Hub on https://mercure.rocks/docs/hub/config
 {
-    # Debug mode (disable it in production!)
-    {$DEBUG}
-    # HTTP/3 support
-    servers {
-        protocol {
-            experimental_http3
-        }
-    }
+	{$GLOBAL_OPTIONS}
 }
 
 {$SERVER_NAME:localhost}
 
 log
 
 route {
-    encode zstd gzip
+	encode zstd gzip
 
-    mercure {
-        # Transport to use (default to Bolt)
-        transport_url {$MERCURE_TRANSPORT_URL:bolt://mercure.db}
-        # Publisher JWT key
-        publisher_jwt {env.MERCURE_PUBLISHER_JWT_KEY} {env.MERCURE_PUBLISHER_JWT_ALG}
-        # Subscriber JWT key
-        subscriber_jwt {env.MERCURE_SUBSCRIBER_JWT_KEY} {env.MERCURE_SUBSCRIBER_JWT_ALG}
-        # Extra directives
-        {$MERCURE_EXTRA_DIRECTIVES}
-    }
+	mercure {
+		# Transport to use (default to Bolt)
+		transport_url {$MERCURE_TRANSPORT_URL:bolt://mercure.db}
+		# Publisher JWT key
+		publisher_jwt {env.MERCURE_PUBLISHER_JWT_KEY} {env.MERCURE_PUBLISHER_JWT_ALG}
+		# Subscriber JWT key
+		subscriber_jwt {env.MERCURE_SUBSCRIBER_JWT_KEY} {env.MERCURE_SUBSCRIBER_JWT_ALG}
+		# Extra directives
+		{$MERCURE_EXTRA_DIRECTIVES}
+	}
 
-    respond /healthz 200
+	respond /healthz 200
 
-    respond "Not Found" 404
+	respond "Not Found" 404
 }
diff --git a/Caddyfile.dev b/Caddyfile.dev
@@ -1,41 +1,34 @@
 # Learn how to configure the Mercure.rocks Hub on https://mercure.rocks/docs/hub/config
 {
-    # Debug mode (disable it in production!)
-    {$DEBUG:debug}
-    # HTTP/3 support
-    servers {
-        protocol {
-            experimental_http3
-        }
-    }
+	{$GLOBAL_OPTIONS}
 }
 
 {$SERVER_NAME:localhost}
 
 log
 
 route {
-    redir / /.well-known/mercure/ui/
-    encode zstd gzip
+	redir / /.well-known/mercure/ui/
+	encode zstd gzip
 
-    mercure {
-        # Transport to use (default to Bolt)
-        transport_url {$MERCURE_TRANSPORT_URL:bolt://mercure.db}
-        # Publisher JWT key
-        publisher_jwt {env.MERCURE_PUBLISHER_JWT_KEY} {env.MERCURE_PUBLISHER_JWT_ALG}
-        # Subscriber JWT key
-        subscriber_jwt {env.MERCURE_SUBSCRIBER_JWT_KEY} {env.MERCURE_SUBSCRIBER_JWT_ALG}
-        # Permissive configuration for the development environment
-        cors_origins *
-        publish_origins *
-        demo
-        anonymous
-        subscriptions
-        # Extra directives
-        {$MERCURE_EXTRA_DIRECTIVES}
-    }
+	mercure {
+		# Transport to use (default to Bolt)
+		transport_url {$MERCURE_TRANSPORT_URL:bolt://mercure.db}
+		# Publisher JWT key
+		publisher_jwt {env.MERCURE_PUBLISHER_JWT_KEY} {env.MERCURE_PUBLISHER_JWT_ALG}
+		# Subscriber JWT key
+		subscriber_jwt {env.MERCURE_SUBSCRIBER_JWT_KEY} {env.MERCURE_SUBSCRIBER_JWT_ALG}
+		# Permissive configuration for the development environment
+		cors_origins *
+		publish_origins *
+		demo
+		anonymous
+		subscriptions
+		# Extra directives
+		{$MERCURE_EXTRA_DIRECTIVES}
+	}
 
-    respond /healthz 200
+	respond /healthz 200
 
-    respond "Not Found" 404
+	respond "Not Found" 404
 }
diff --git a/charts/mercure/templates/configmap.yaml b/charts/mercure/templates/configmap.yaml
@@ -5,6 +5,6 @@ metadata:
   labels:
     {{- include "mercure.labels" . | nindent 4 }}
 data:
-  debug: "{{ if .Values.debug }}debug{{ end }}"
+  global-options:  {{ .Values.globalOptions | quote }}
   publisher-jwt-alg: {{ .Values.publisherJwtAlg | quote }}
   subscriber-jwt-alg: {{ .Values.subscriberJwtAlg | quote }}
diff --git a/charts/mercure/templates/deployment.yaml b/charts/mercure/templates/deployment.yaml
@@ -40,11 +40,11 @@ spec:
           env:
             - name: SERVER_NAME
               value: :80
-            - name: DEBUG
+            - name: GLOBAL_OPTIONS
               valueFrom:
                 configMapKeyRef:
                   name: {{ include "mercure.fullname" . }}
-                  key: debug
+                  key: global-options
             - name: MERCURE_TRANSPORT_URL
               valueFrom:
                 secretKeyRef:

diff --git a/charts/mercure/values.yaml b/charts/mercure/values.yaml
@@ -2,13 +2,13 @@
 # This is a YAML-formatted file.
 # Declare variables to be passed into your templates.
 
-# -- Enable the debug mode.
-debug: false
+# -- Inject global options in the Caddyfile.
+globalOptions: ""
 # -- Enable the development mode, including the debug UI and the demo.
 dev: false
 # -- The URL representation of the transport to use.
 transportUrl: bolt:///data/mercure.db
-# -- Extra Mercure directives to include in the Caddyfile.
+# -- Inject extra Mercure directives in the Caddyfile.
 extraDirectives: ""
 
 # -- The JWT key to use for publishers, a random key will be generated if empty.

diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md
@@ -1,5 +1,9 @@
 # Upgrade
 
+## 0.13
+
+The `DEBUG` environment variable has gone. The the `GLOBAL_OPTIONS` environment variable to `debug` instead.
+
 ## 0.11
 
 The Mercure.rocks Hub is now available as a module for the [Caddy web server](https://caddyserver.com/).

diff --git a/docs/hub/config.md b/docs/hub/config.md
@@ -4,7 +4,7 @@ The Mercure.rocks hub is a custom build of the [Caddy web server](https://caddys
 
 Read [Caddy web server's getting started guide](https://caddyserver.com/docs/getting-started) to learn the basics.
 
-While all supported way to configure Caddy are also supported by the Mercure.rocks Hub, the easiest one is [to use a `Caddyfile`](https://caddyserver.com/docs/quick-starts/caddyfile).
+While all supported ways to configure Caddy are also supported by the Mercure.rocks Hub, the easiest one is [to use a `Caddyfile`](https://caddyserver.com/docs/quick-starts/caddyfile).
 A default `Caddyfile` is provided in [the archive containing the Mercure.rocks Hub](install.md).
 
 A minimal `Caddyfile` for the Mercure hub looks like this:
@@ -25,17 +25,23 @@ route {
 }
 ```
 
-Caddy will automatically generate a Let's Encrypt TLS certificate automatically for you! So you can use HTTPS.
-To disable HTTPS entirely, explicitly set a different port than `443`:
+Caddy will automatically generate a Let's Encrypt TLS certificate for you! So you can use HTTPS.
+To disable HTTPS entirely, set the [`auto_https`](https://caddyserver.com/docs/caddyfile/options#auto-https) global option to off:
 
 ```Caddyfile
-:80, my-domain.test:3000
+{
+    auto_https off
+}
+
+my-domain.test:3000
 
 route {
     # ...
 }
 ```
 
+Note that HTTPS is automatically disabled if you set the server port to 80.
+
 ## Directives
 
 The following Mercure-specific directives are available:
@@ -62,17 +68,17 @@ See also [the list of built-in Caddyfile directives](https://caddyserver.com/doc
 
 The provided `Caddyfile` and the Docker image provide convenient environment variables:
 
-| Environment variable         | Description                                                                        | Default value       |
-|------------------------------|------------------------------------------------------------------------------------|---------------------|
-| `DEBUG=debug`                | enable the debug mode                                                              |                     |
-| `SERVER_NAME`                | the server name or address, set it to `:80` (or use another port) to disable HTTPS | `localhost`         |
-| `MERCURE_TRANSPORT_URL`      | the value passed to the `transport_url` directive                                  | `bolt://mercure.db` |
-| `MERCURE_PUBLISHER_JWT_KEY`  | the JWT key to use for publishers                                                  |                     |
-| `MERCURE_PUBLISHER_JWT_ALG`  | the JWT algorithm to use for publishers                                            | `HS256`             |
-| `MERCURE_SUBSCRIBER_JWT_KEY` | the JWT key to use for subscribers                                                 |                     |
-| `MERCURE_SUBSCRIBER_JWT_ALG` | the JWT algorithm to use for subscribers                                           | `HS256`             |
-| `MERCURE_EXTRA_DIRECTIVES`   | a list of extra Mercure directives to pass, one per line                           |                     |
-| `MERCURE_LICENSE`            | the license to use ([only applicable for the HA version](cluster.md)               |                     |
+| Environment variable         | Description                                                                                                                          | Default value       |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
+| `GLOBAL_OPTIONS`             | the [global options block](https://caddyserver.com/docs/caddyfile/options#global-options) to inject in the `Caddyfile`, one per line |
+| `SERVER_NAME`                | the server name or address                                                                                                           | `localhost`         |
+| `MERCURE_TRANSPORT_URL`      | the value passed to the `transport_url` directive                                                                                    | `bolt://mercure.db` |
+| `MERCURE_PUBLISHER_JWT_KEY`  | the JWT key to use for publishers                                                                                                    |                     |
+| `MERCURE_PUBLISHER_JWT_ALG`  | the JWT algorithm to use for publishers                                                                                              | `HS256`             |
+| `MERCURE_SUBSCRIBER_JWT_KEY` | the JWT key to use for subscribers                                                                                                   |                     |
+| `MERCURE_SUBSCRIBER_JWT_ALG` | the JWT algorithm to use for subscribers                                                                                             | `HS256`             |
+| `MERCURE_EXTRA_DIRECTIVES`   | a list of extra Mercure directives inject in the Caddy file, one per line                                                            |                     |
+| `MERCURE_LICENSE`            | the license to use ([only applicable for the HA version](cluster.md)                                                                 |                     |
 
 ## JWT Verification
 
@@ -164,7 +170,7 @@ When using environment variables, list must be space separated. As flags paramet
 | `read_timeout`             | maximum duration for reading the entire request, including the body, set to `0s` to disable                                                                                                                                                                                                                                                                                              | `5s`                                                     |
 | `subscriber_jwt_key`       | must contain the secret key to valid subscribers' JWT, can be omitted if `jwt_key` is set                                                                                                                                                                                                                                                                                                |                                                          |
 | `subscriber_jwt_algorithm` | the JWT verification algorithm to use for subscribers, e.g. `HS256` or `RS512`                                                                                                                                                                                                                                                                                                           | `HS256`                                                  |
-| `transport_url`            | URL representation of the history database. Provided database are `null` to disabled history, `bolt` to use [bbolt](https://github.com/etcd-io/bbolt) (example `bolt:///var/run/mercure.db?size=100&cleanup_frequency=0.4`)                                                                                                                                                              | `bolt://updates.db`                                      |
+| `transport_url`            | URL representation of the history database. Provided database are `null` to disable history, `bolt` to use [bbolt](https://github.com/etcd-io/bbolt) (example `bolt:///var/run/mercure.db?size=100&cleanup_frequency=0.4`)                                                                                                                                                               | `bolt://updates.db`                                      |
 | `use_forwarded_headers`    | use the `X-Forwarded-For`, and `X-Real-IP` for the remote (client) IP address, `X-Forwarded-Proto` or `X-Forwarded-Scheme` for the scheme (http or https), `X-Forwarded-Host` for the host and the RFC 7239 `Forwarded` header, which may include both client IPs and schemes. If this option is enabled, the reverse proxy must override or remove these headers or you will be at risk | `false`                                                  |
 | `write_timeout`            | maximum duration before closing the connection, set to `0s` to disable                                                                                                                                                                                                                                                                                                        | `600s`                                                   |
 

diff --git a/docs/hub/debug.md b/docs/hub/debug.md
@@ -14,6 +14,8 @@ To enable the profiler, add the `debug` global directive to your `Caddyfile`:
 # ...
 ```
 
+If you use the default `Caddyfile`,  you can also set the `GLOBAL_OPTIONS` environment variable to `debug`.
+
 The route exposing profiling data is now available at `http://localhost:2019/debug/pprof/`.
 You can use [the `pprof` tool](https://golang.org/pkg/net/http/pprof/) to visualize it.