feat: support filtering environment variables

Author: nstapelbroek

README.md

@@ -3,7 +3,7 @@
 # Docker static webserver
 
 A simple nginx docker image that has the ability to insert environment variables. Created so I could re-use an image between prod and staging environments for my frontend builds.
-It replaces environment variables on container startup so you don´t have to rebuild your Docker image or use a server-side language to change some settings.
+It replaces environment variables on container startup, so you don´t have to rebuild your Docker image or use a server-side language to change some settings.
 
 ## Getting Started
 
@@ -18,7 +18,7 @@ COPY ./your-static-content /var/www
 A more modern example where you build your frontend project and ship it:
 
 ```Dockerfile
-FROM node:18 as build
+FROM node:21 as build
 WORKDIR /opt/project
 
 COPY package.json package-lock.json /opt/project/
@@ -62,8 +62,9 @@ You should use the latest available tag in [at in the registry](https://hub.dock
 
 Due to the simple approach of finding & replacing the keywords there are some limitations:
 - Please make sure your environment keys do not contain special characters. Only `a-z`, `A-Z`, `0-9` and `_` are recommended.
-- By default, the script only changes files located in `/var/www`. You can change this by setting the `NGINX_ENVSUBST_WWW_DIR` environment variable. 
-- The project is not meant as a development environment. Don´t mount your code in here as it will only change envioronment variables on the first starutp.
+- By default, the script only changes files located in `/var/www`. You can change this by setting the `NGINX_ENVSUBST_WWW_DIR` environment variable.
+- Using es6 template literals can cause issues. You can fine-tune the replacement by configuring a filter with the `NGINX_ENVSUBST_FILTER` environment variable. This should allow you to set a prefix like `CONFIG_`.
+- The project is not meant as a development environment. Don´t mount your code in here as it will only change environment variables on the first startup.
 
 ## License
 

files/docker-entrypoint.d/40-envsubst-on-www.sh

@@ -6,8 +6,21 @@ set -e
 
 ME=$(basename "$0")
 
+entrypoint_log() {
+    if [ -z "${NGINX_ENTRYPOINT_QUIET_LOGS:-}" ]; then
+        echo "$@"
+    fi
+}
+
 www_envsubst() {
-  local www_dir="${NGINX_ENVSUBST_WWW_DIR:-/var/www/}"
+  local www_dir filter defined_envs
+  www_dir="${NGINX_ENVSUBST_WWW_DIR:-/var/www/}"
+  filter="${NGINX_ENVSUBST_FILTER:-}"
+  defined_envs=$(printf '${%s} ' $(awk "END { for (name in ENVIRON) { print ( name ~ /${filter}/ ) ? name : \"\" } }" < /dev/null ))
+
+  if [ -n "$filter" ]; then
+    entrypoint_log "$ME: envsubst filter is set to: $filter"
+  fi
 
   [ -d "$www_dir" ] || return 0
   if [ ! -w "$www_dir" ]; then
@@ -16,7 +29,13 @@ www_envsubst() {
   fi
 
   grep --recursive --no-messages --files-with-matches "\${" "$www_dir" | while read -r file; do
-    envsubst < "$file" > "$file.new" && cp --attributes-only --preserve "$file" "$file.new" && mv "$file.new" "$file"
+    if [ -n "$filter" ]; then
+      entrypoint_log "$ME: Running envsubst with filter on $file"
+    else
+      entrypoint_log "$ME: Running envsubst on $file"
+    fi
+
+    envsubst "$defined_envs" < "$file" > "$file.new" && cp --attributes-only --preserve "$file" "$file.new" && mv "$file.new" "$file"
   done
 }
 

files/var/www/index.html

@@ -38,14 +38,20 @@ <h2>Example Dockerfile</h2>
                     <h2>Using environment variables</h2>
                     <p>When this container bootstraps, a script will find and replace all occurrences of
                         &dollar;&lcub;VARIABLE_NAME&rcub; and replace them for their matching values passed
-                        in the environment variables of your container. This is great when trying to
-                        ship a webpack compiled static page in a Docker image on multiple environments.
+                        in the environment variables of your container. This is great for shipping
+                        some bundled static code that only needs a small config change between environments.
                     </p>
                 </header>
-                <p class="content">
-                    As an example: a container is almost certain to receive a hostname when running it. The hostname of
-                    this container is <code>${HOSTNAME}</code>. Try running another instance of this container and notice
-                    how the hostname changes.
+                <p>
+                    As an example: a container recieves a hostname when it starts. The hostname of this container is
+                    <code>${HOSTNAME}</code> the nginx version is <code>${NGINX_VERSION}</code>.
+                    Try running another instance of this container and notice how the hostname changes.
+                </p>
+                <p>
+                    You can also filter the variables the startup script is replacing. This can prevent errors when your
+                    javascript contains es6 template literals. To prevent variables from being replaced you should
+                    set the `NGINX_ENVSUBST_FILTER` environment variable in your container. For example:
+                    `NGINX_ENVSUBST_FILTER=CONFIG_` only replaces variables that start with `CONFIG_`.
                 </p>
             </section>
             <section id="cta" class="main special">