feat: add configurations for local TLS

damienwebdev · damienwebdev · commit 87835cb36991 · 2026-02-02T13:40:54.000-05:00
diff --git a/certs/snakeoil.crt b/certs/snakeoil.crt
@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDazCCAlOgAwIBAgIUSup+N3PQMdK7N17zAjEDsy76/h8wDQYJKoZIhvcNAQEL
+BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM
+GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yMjA4MTcxODUyNTFaFw0yMzA4
+MTcxODUyNTFaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw
+HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwggEiMA0GCSqGSIb3DQEB
+AQUAA4IBDwAwggEKAoIBAQDOGerIzu+AfOEKhIgr//G+/DI8MKCk8NN+B/7jcar1
+7V376R/ZXvRikEyGOAe/pmEnjDQoI+3jL8S2hE3/1GT9mzPUXgvWBKewTeuuLRJp
+VXZud8BNUHrnnJ0HrZ0bzam4SRSS8cjkxX5fRnOHt9lebpvX6SdZGilYiTiyRFF+
+cWxBXcUNtleYVE64WX5XYQlZ5ky1VphXikQPuR94ueGCg1AYiq5hy9CjoREs3GD3
+gqUU5WPH4hoi7dkis+88lvaRrXNM+GL1a4q1JGqyMlng+xqfsej7r5D2MCItS81a
+jnYZaYLNCD1F6/QRd/VNUKgsmEPrIr+bHnLbM6JtnG+1AgMBAAGjUzBRMB0GA1Ud
+DgQWBBTDmrBsPUW9brDp+AIGiLajfJCoLjAfBgNVHSMEGDAWgBTDmrBsPUW9brDp
++AIGiLajfJCoLjAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQAs
+5sd9XXHr3rbgEvVyAapYlCG9H6q51d5CP4NP/kjSO5T/pKx1nAv/a1N2tjAoB0q8
+LQHIoPu1lYphLIukCKL1z7RanyG7KY1nKdVP4Od2fkwxXTiZsJaMRCBgFcMxLMzO
+fo/xTldP2pXCZGUECIkIFk/BCswHqchnbaNvzsZqSzPzTvvLhJ2MmdU6db0X4YLS
+NDv4LBLiraE6ovbGOO5CpN7QOEYF7mrKg8ptN66lNGyioSD1+XNVkbS2zkQUPa50
+f+RFcHj6IzNErKnTUARs4wQ1y0mf4GLwK/Fte/oUdyvhCrB3MrM0ovy9dYq8GuWJ
+Wq0Ystan3d1BHas3KJh4
+-----END CERTIFICATE-----
diff --git a/certs/snakeoil.key b/certs/snakeoil.key
@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDOGerIzu+AfOEK
+hIgr//G+/DI8MKCk8NN+B/7jcar17V376R/ZXvRikEyGOAe/pmEnjDQoI+3jL8S2
+hE3/1GT9mzPUXgvWBKewTeuuLRJpVXZud8BNUHrnnJ0HrZ0bzam4SRSS8cjkxX5f
+RnOHt9lebpvX6SdZGilYiTiyRFF+cWxBXcUNtleYVE64WX5XYQlZ5ky1VphXikQP
+uR94ueGCg1AYiq5hy9CjoREs3GD3gqUU5WPH4hoi7dkis+88lvaRrXNM+GL1a4q1
+JGqyMlng+xqfsej7r5D2MCItS81ajnYZaYLNCD1F6/QRd/VNUKgsmEPrIr+bHnLb
+M6JtnG+1AgMBAAECggEACLx8gUqUSGQCvglkJElTG/9gucBt7s/uhxcbrNRypL4N
+D9KP8QzfWxY2yDGz0mHhGGYPB+yN9uVdd0cgb0m3hjB//+6EnevQl96VsOpkL2ba
+AFC/LAfPTeYLmfm4ASe0nAUtBBWPqHLeqnc4Cna2lhQmMv7FFjfPrNsUNipDMhLV
+NcDBcg5HwobkY2d0EcpUKBHO/zLkoSnZISB1nHCvmv9G7lphlBVPoOqbSYWZvf4/
+9IqPjAZ8xgo3KJYzLtKbuYxjP89WRKkIxKiAcOHNwEssor8Q+UrkOF0Cv4L5DN6r
+2+D24sf+B8EEomzWZ7wakh4oDqDgdnNOcaLWuRzzQQKBgQD4MY0qEdbCJTtGh2Jy
+ooR3MhabPPvbHE3X97rVVGd0ypzxHqclXUGCt6N2gqopCVnYKF3q2BH18Axj+THJ
+2n/Frli6VSEPRSKZQQ7wujw/N1FG+ZHbjNxkVTtEWpe0clN//3IpoVHfLPI0MWQz
+cpXXJgmKG8SccWHAaF4Qs/dDXQKBgQDUlXB40Aizar50KraWX60GallFX9ocJLTu
+TsUWROqoGAahi155H+t1tfewCEtaEHDeXCuuJaCEW4Vg/7ru6zuiCXjF2e39P+xK
+USIXmzu2k3YiuSLXxFreLvFDJI+Nlj15ddvQ/hupIhgfw+1YYQqXr67HYFRz82Np
+MUmmANEwOQKBgQDWwPF3nHXqCZMvpMefj1X1WUbMTklSvzvwCnAEVQMrwIFp9W8F
+Wprrw4BSdB9OYMP30H3rTcjEuE/QVXgqQ8DZSNGHcU+oydZ1KyEFVO/6dyABvMLj
+aQ/uVP1yWLz5qw7rKxoaQXb5GAf+91nPVm+m+Ue50+scvtKpTOVPqJjkFQKBgQCT
+fEpXxx0CPSB9P9UFZsOIG+hrdSDBPcY5P3UFCjMzA9g145dbuYWGWQTKoDaG+bkU
+zCWR4JEIwuY6cbGjaJgqxx9/RL8UYHDy7m8UqaI3/P6NAJznzVatpyvDRW5C8OUd
+i2NCD8npAbpy71+PXWQX8M71jCOLfmSN6qAKB68aIQKBgBgG4BZJkvljcgBoaZTY
+zuzCjnK/CrSZxkn1Hn6eM7vdj6xZ8iqsqeNKMinE9YUkJbw82CB3r3fTr9vNclZW
+Cmvs7pEIR/gApKP/x2/Cu5LI07D1q2p/1pOoqfUsplyBHlhauwefFCQSK8D7P0oG
+K85oJaYqz32qAjQQQ4HGX39W
+-----END PRIVATE KEY-----
diff --git a/compose/2.4.6/docker-compose.yml b/compose/2.4.6/docker-compose.yml
@@ -21,6 +21,8 @@ services:
       - MAGENTO2_UPSTREAM_PORT=9000
       - NGINX_PORT=8000
       - NGINX_TLS_PORT=8443
+      - MAGENTO_TLS_CERT=snakeoil.crt
+      - MAGENTO_TLS_KEY=snakeoil.key
     ports:
       - "80:8000"
       - "443:8443"
diff --git a/compose/2.4.7/docker-compose.yml b/compose/2.4.7/docker-compose.yml
@@ -21,6 +21,8 @@ services:
       - MAGENTO2_UPSTREAM_PORT=9000
       - NGINX_PORT=8000
       - NGINX_TLS_PORT=8443
+      - MAGENTO_TLS_CERT=snakeoil.crt
+      - MAGENTO_TLS_KEY=snakeoil.key
     ports:
       - "80:8000"
       - "443:8443"
diff --git a/compose/2.4.8/docker-compose.yml b/compose/2.4.8/docker-compose.yml
@@ -21,6 +21,8 @@ services:
       - MAGENTO2_UPSTREAM_PORT=9000
       - NGINX_PORT=8000
       - NGINX_TLS_PORT=8443
+      - MAGENTO_TLS_CERT=snakeoil.crt
+      - MAGENTO_TLS_KEY=snakeoil.key
     ports:
       - "80:8000"
       - "443:8443"
diff --git a/compose/2.4.9/docker-compose.yml b/compose/2.4.9/docker-compose.yml
@@ -21,6 +21,8 @@ services:
       - MAGENTO2_UPSTREAM_PORT=9000
       - NGINX_PORT=8000
       - NGINX_TLS_PORT=8443
+      - MAGENTO_TLS_CERT=snakeoil.crt
+      - MAGENTO_TLS_KEY=snakeoil.key
     ports:
       - "80:8000"
       - "443:8443"
diff --git a/docker-compose.overrides.yml.sample b/docker-compose.overrides.yml.sample
@@ -9,4 +9,4 @@ services:
       - MAGE_ROOT_DIR=/workspace
     volumes:
       - ../:/workspace:cached
-      - ./magento2-devcontainer/nginx:/etc/nginx/templates
+      - ./magento2-devcontainer/nginx/default:/etc/nginx/templates
diff --git a/docs/tls.md b/docs/tls.md
@@ -0,0 +1,113 @@
+# TLS Configuration
+
+> **Note:** This configuration is only relevant when running devcontainers locally. If you're using GitHub Codespaces, HTTPS is handled automatically and you can skip this setup.
+
+When working locally, it's important to consider the end-user experience. To mimic production as closely as possible for debugging purposes, you can setup a local TLS certificate. This devcontainer supports optional TLS (HTTPS) for local development.
+
+## Configuration Options
+
+Two nginx configurations are provided:
+
+| Directory        | Description                       |
+| ---------------- | --------------------------------- |
+| `nginx/default/` | HTTP only (port 80)               |
+| `nginx/tls/`     | HTTP (port 80) + HTTPS (port 443) |
+
+## Enabling TLS
+
+To enable TLS, modify your `docker-compose.overrides.yml` to:
+
+1. Mount the TLS nginx config (as opposed to the default config)
+2. Mount your certificates directory
+3. Set the certificate filenames
+
+```yaml
+services:
+  nginx:
+    environment:
+      - MAGENTO_TLS_CERT=magento2.test.pem
+      - MAGENTO_TLS_KEY=magento2.test-key.pem
+    volumes:
+      - ./magento2-devcontainer/nginx/tls:/etc/nginx/templates
+      - ./certs:/etc/nginx/certs
+```
+
+## Certificates
+
+### Using Default Snakeoil Certificates
+
+Default self-signed certificates are included in `magento2-devcontainer/certs/`:
+
+- `snakeoil.crt`
+- `snakeoil.key`
+
+These work out of the box but will trigger browser security warnings.
+
+```yaml
+services:
+  nginx:
+    environment:
+      - MAGENTO_TLS_CERT=snakeoil.crt
+      - MAGENTO_TLS_KEY=snakeoil.key
+    volumes:
+      - ./magento2-devcontainer/nginx/tls:/etc/nginx/templates
+      - ./magento2-devcontainer/certs:/etc/nginx/certs
+```
+
+### Using mkcert (Recommended)
+
+[mkcert](https://github.com/FiloSottile/mkcert) generates locally-trusted certificates that work without browser warnings.
+
+1. Install mkcert on your system:
+
+   ```bash
+   # macOS
+   brew install mkcert
+
+   # Linux
+   sudo apt install mkcert
+   # or
+   sudo pacman -S mkcert
+
+   # Windows
+   choco install mkcert
+   ```
+
+2. Install the local CA (this registers mkcert's root certificate with your system):
+
+   ```bash
+   mkcert -install
+   ```
+
+3. Generate certificates for your domain and place them in the certs directory:
+
+   ```bash
+   YOUR_TEST_DOMAIN=magento2.test
+   mkdir -p .devcontainer/magento2/certs
+   cd .devcontainer/magento2/certs
+   mkcert -key-file $YOUR_TEST_DOMAIN-key.pem -cert-file $YOUR_TEST_DOMAIN.pem $YOUR_TEST_DOMAIN
+   ```
+
+4. Update your `docker-compose.overrides.yml` with the cert filenames as shown above.
+
+At this point, you should have a working TLS cert covering the `$YOUR_TEST_DOMAIN` domain.
+
+## Environment Variables
+
+| Variable           | Default        | Description                                  |
+| ------------------ | -------------- | -------------------------------------------- |
+| `MAGENTO_TLS_CERT` | `snakeoil.crt` | Certificate filename in `/etc/nginx/certs`   |
+| `MAGENTO_TLS_KEY`  | `snakeoil.key` | Private key filename in `/etc/nginx/certs`   |
+
+## Troubleshooting
+
+### Browser still shows certificate warnings with mkcert
+
+Make sure you ran `mkcert -install` before generating the certificates. If you generated certs first, delete them and regenerate after running the install command.
+
+### Certificate not found errors
+
+Verify that:
+
+- The certs directory is mounted to `/etc/nginx/certs`
+- The `MAGENTO_TLS_CERT` and `MAGENTO_TLS_KEY` environment variables match the actual filenames in your certs directory
diff --git a/nginx/default/default.conf.template b/nginx/default/default.conf.template
diff --git a/nginx/tls/default.conf.template b/nginx/tls/default.conf.template
@@ -0,0 +1,26 @@
+## This nginx configuration should serve as an example for a production configuration of nginx.
+## Do note that this configuration only serves non-encrypted connections. This is intentional;
+## traffic within the DMZ should not need to be encrypted unless absolutely required.
+
+upstream fastcgi_backend {
+  server  ${MAGENTO2_UPSTREAM}:${MAGENTO2_UPSTREAM_PORT};
+}
+
+server {
+  listen ${NGINX_PORT};
+
+  set $MAGE_ROOT ${MAGE_ROOT_DIR};
+
+  include ${MAGE_ROOT_DIR}/nginx[.]conf*;
+}
+
+server {
+  listen ${NGINX_TLS_PORT} ssl;
+
+  ssl_certificate /etc/nginx/certs/${MAGENTO_TLS_CERT};
+  ssl_certificate_key /etc/nginx/certs/${MAGENTO_TLS_KEY};
+
+  set $MAGE_ROOT ${MAGE_ROOT_DIR};
+
+  include ${MAGE_ROOT_DIR}/nginx[.]conf*;
+}
