mallox/go-static-env repository overview

⁠goStaticEnv

This project is a fork of mmguero-dev/goStatic⁠, with additional features and improvements. The name has been updated to goStaticEnv to reflect its enhanced capabilities.

A really small, multi-arch, static web server for Docker

⁠The goal

My goal is to create to smallest docker container for my web static files. The advantage of Go is that you can generate a fully static binary, so that you don't need anything else.

⁠Wait, I've been using old versions of GoStatic and things have changed!

⁠The goal

My goal is to create to smallest docker container for my web static files. The advantage of Go is that you can generate a fully static binary, so that you don't need anything else.

⁠Wait, I've been using old versions of GoStatic and things have changed!

Yeah, decided to drop support of unsecured HTTPS. Two-years ago, when I started GoStatic, there was no automatic HTTPS available. Nowadays, thanks to Let's Encrypt, it's really easy to do so. If you need HTTPS, I recommend caddy⁠.

⁠About this fork

goStaticEnv extends the original goStatic with support for environment variable substitution in served files. This allows you to inject environment-specific values directly into your static content at runtime, making it ideal for containerized and cloud-native deployments.

⁠Environment Variable Substitution

Feature:

You can use environment variables in your static files using the syntax ${VARNAME} or ${VARNAME:=default}. When a file is served, goStaticEnv will replace these placeholders with the value of the corresponding environment variable, or with the provided default if the variable is not set.

Usage Example:

Suppose your HTML file contains:

<script>
  window.API_URL = "${API_URL:=https://api.example.com}";
</script>

If you run the server with API_URL set in the environment, it will be replaced. If not, the default will be used.

How it works:

• ${VARNAME}: Replaced with the value of VARNAME if set, otherwise left as-is.
• ${VARNAME:=default}: Replaced with the value of VARNAME if set, otherwise replaced with default.

Validation: At startup, goStaticEnv will scan your static files and report an error if any required environment variables (without a default) are missing. You can use the --allow-missing-env flag to start the server with warnings instead of exiting when environment variables are missing.

Directory and File Filtering: You can control which directories and files are scanned for environment variables using the include/exclude flags:

• --env-include: Only scan the specified directories and files (comma-separated, relative to base path)
• --env-exclude: Skip the specified directories and files when scanning (comma-separated, relative to base path)

Pattern Matching: Both directory and file patterns support simple names and glob-style wildcards:

• Simple patterns: docs matches docs, docs/api, src/docs, etc. (intuitive prefix matching)
• File patterns: config.txt matches only files named config.txt anywhere in the tree
• Glob patterns: Use *, ?, and [] for flexible matching (powered by Go's filepath.Match)
  • * matches any sequence of characters (except /)
  • ? matches any single character
  • [abc] matches any character in the set

File Extension and Path Patterns:

• File extensions: *.js matches all JavaScript files, *.html matches all HTML files
• Path-based file patterns: src/*.js matches JavaScript files only in the src directory
• Mixed patterns: You can combine directory and file patterns in the same command

Verified Examples:

# Directory patterns (verified working)
./goStaticEnv --env-include-dirs "src,public"           # Include only src/ and public/ directories
./goStaticEnv --env-exclude-dirs "node_modules,vendor"  # Exclude node_modules and vendor anywhere

# File extension patterns (verified working)
./goStaticEnv --env-include-dirs "*.html"               # Include only HTML files
./goStaticEnv --env-include-dirs "*.js,*.css"           # Include only JavaScript and CSS files
./goStaticEnv --env-exclude-dirs "*.log,*.tmp"          # Exclude log and temporary files

# Specific file patterns (verified working)
./goStaticEnv --env-include-dirs "config.txt"           # Include only config.txt files
./goStaticEnv --env-exclude-dirs "package-lock.json"    # Exclude package-lock.json files

# Path-based file patterns (verified working)
./goStaticEnv --env-include-dirs "src/*.js"             # Include JavaScript files only in src directory
./goStaticEnv --env-include-dirs "docs/*.md"            # Include Markdown files only in docs directory

# Glob patterns with wildcards (all verified working)
./goStaticEnv --env-exclude-dirs "test-*"               # Exclude test-unit, test-integration, etc.
./goStaticEnv --env-exclude-dirs "*-backup"             # Exclude old-backup, data-backup, etc.
./goStaticEnv --env-include-dirs "*.tmp"                # Include config.tmp, cache.tmp, etc.
./goStaticEnv --env-include-dirs "cache-?"              # Include cache-1, cache-2, etc.

# Complex path patterns (verified working)
./goStaticEnv --env-include-dirs "docs/v*"              # Include docs/v1, docs/v2, docs/v1-draft, etc.

# Mixed include/exclude patterns (verified working)
./goStaticEnv --env-include-dirs "src,docs/v*" --env-exclude-dirs "docs/v1-*"  # Include src and docs/v* but exclude docs/v1-*
./goStaticEnv --env-include-dirs "*.js,*.css" --env-exclude-dirs "node_modules" # Include JS/CSS files but exclude node_modules

# Common use cases (all verified working)
./goStaticEnv --env-exclude-dirs "node_modules,vendor,.git,test-*,*-backup"    # Exclude common build/temp directories
./goStaticEnv --env-include-dirs "src,public,docs"                            # Only scan specific source directories
./goStaticEnv --env-include-dirs "*.html,*.js,*.css"                          # Only scan web asset files

⁠Features

• A fully static web server embedded in a SCRATCH image
• No framework
• Web server built for Docker
• Light container
• More secure than official images (see below)
• Log enabled
• Specify custom response headers per path and filetype (info)⁠
• NEW: Environment variable substitution in static files

⁠Why?

Because the official Golang image is wayyyy too big (around 1/2Gb as you can see below) and could be insecure.

For me, the whole point of containers is to have a light container... Many links should provide you with additional info to see my point of view:

• Over 30% of Official Images in Docker Hub Contain High Priority Security Vulnerabilities⁠
• Create The Smallest Possible Docker Container⁠
• Building Docker Images for Static Go Binaries⁠
• Small Docker Images For Go Apps⁠

⁠How to use

docker run -d -p 80:8043 -v path/to/website:/srv/http -e API_URL=https://api.example.com --name goStatic ghcr.io/mmguero-dev/gostatic

⁠Usage

./goStaticEnv --help
Usage of ./goStaticEnv:
  -allow-missing-env
        Allow server to start with warnings when environment variables are missing, instead of exiting with fatal error
  -append-header HeaderName:Value
        HTTP response header, specified as HeaderName:Value that should be added to all responses.
  -context string
        The 'context' path on which files are served, e.g. 'doc' will serve the files at 'http://localhost:<port>/doc/'
  -default-user-basic-auth string
        Define the user (default "gopher")
  -enable-basic-auth
        Enable basic auth. By default, password are randomly generated. Use --set-basic-auth to set it.
  -enable-health
        Enable health check endpoint. You can call /health to get a 200 response. Useful for Kubernetes, OpenFaas, etc.
  -enable-logging
        Enable log request
  -env-exclude string
        Comma-separated list of directories to exclude when scanning for environment variables (relative to base path)
  -env-include string
        Comma-separated list of directories to include when scanning for environment variables (relative to base path)
  -fallback string
        Default fallback file. Either absolute for a specific asset (/index.html), or relative to recursively resolve (index.html)
  -header-config-path string
        Path to the config file for custom response headers (default "/config/headerConfig.json")
  -https-promote
        All HTTP requests should be redirected to HTTPS
  -password-length int
        Size of the randomized password (default 16)
  -path string
        The path for the static files (default "/srv/http")
  -port int
        The listening port (default 8043)
  -set-basic-auth string
        Define the basic auth user string. Form must be user:password
  -basic-auth-user
        Define the basic auth username
  -basic-auth-pass
        Define the basic auth password

⁠Fallback

The fallback option is principally useful for single-page applications (SPAs) where the browser may request a file, but where part of the path is in fact an internal route in the application, not a file on disk. goStatic supports two possible usages of this option:

1. Using an absolute path so that all not found requests resolve to the same file
2. Using a relative file, which searches up the tree for the specified file

The second case is useful if you have multiple SPAs within the one filesystem. e.g., / and /admin.

⁠Build

⁠Docker images

docker buildx create --use --name=cross
docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v5,linux/arm/v6,linux/arm/v7,darwin/amd64,darwin/arm64,windows/amd64 .

⁠Versions

⁠v1.0.0

Initial release of goStaticEnv with environment variable substitution feature.

⁠v1.1.0

Added support for directory filtering using include/exclude flags. Enhanced environment variable substitution with validation and pattern matching.

⁠v1.1.1

Added support for file filtering in addition to directory filtering. Improved pattern matching for both directories and files, allowing for more flexible inclusion/exclusion rules.