stack-wrapper-static-content

A container wrapper scheme for the stack tool that serves static HTML content with nginx.

A repository containing only static content (an index.html and friends) can be built into a servable container image with no containerization knowledge required:

$ stack fetch repo bozemanpass/stack-wrapper-static-content
$ stack webapp build --wrapper static-content --source-repo ~/my-static-site

Authentication

The content is served to anyone by default. Setting a username and password in the environment puts it behind HTTP basic authentication instead:

$ docker run -p 3000:80 -e STACK_AUTH_USER=alice -e STACK_AUTH_PASSWORD=secret <image>

or, for a deployment made with the stack tool:

$ stack init --stack my-site --output spec.yml \
    --config STACK_AUTH_USER=alice --config STACK_AUTH_PASSWORD=secret

Variable	Meaning
STACK_AUTH_USER, STACK_AUTH_PASSWORD	One credential. The password is hashed when the container starts; the two must be set together or the container refuses to start.
STACK_AUTH_HTPASSWD	The content of an htpasswd file, already hashed — several users, without a plaintext password in the environment. Additive with the pair above.
STACK_AUTH_REALM	The name the browser's prompt shows. Defaults to Restricted.
STACK_AUTH_EXCLUDE	Space-separated path prefixes served without credentials.

Two things worth knowing:

• This is configurable after deployment. The variables are read at container start, not baked into the image, so a site that was deployed without authentication is gated by adding them to the deployment's config.env and running stack manage --dir <dir> update, which applies environment changes on every target. Removing them again ungates it. The image is the same either way.
• A composefile healthcheck needs STACK_AUTH_EXCLUDE. On Kubernetes a healthcheck becomes the container's liveness probe, and a probe answered with a 401 restarts the pod for as long as authentication is configured. Point the healthcheck at a path named in STACK_AUTH_EXCLUDE.

Basic authentication sends the password with every request, protected by nothing but base64, so it is only worth having over HTTPS. See the stack tool's docs/ingress.md for serving a deployment over TLS.

Contents

• wrapper.yml — the wrapper manifest (see the stack tool's docs/wrappers.md)
• Containerfile — build for the bozemanpass/static-content-base base image
• Containerfile.app — wraps the app source into a servable image (build context is the app repository)
• build.sh — build script invoked by the stack tool
• nginx/default.conf — the served site's nginx configuration
• scripts/40-stack-auth.sh — run by nginx's entrypoint, configures authentication from the environment