docker-static-site

What is it?

A very small Docker image (~100KB) to run any static website, based on the BusyBox httpd static file server.

Background

This repo is based on the similar one by @lipanski found here: docker-static-website.

However instead of compiling busybox from source, this one is pulling the prebuilt binaries provided by busybox themselves.

Using

The container image can be built and run using similar instructions found in the original README. The contents are quoted below.

To use this container image, use this FROM instruction:

FROM ghcr.io/jason-clark-fg/docker-static-site:main

To build this container, run:

docker build --platform linux/amd64 --tag docker-static-site .

You can use this container directly to serve an html file from the local filesystem by using a volume mount. For instance, if you have your index.html in the current directory, you can use the following:

docker run --platform linux/amd64 -it --init --rm -p 3000:3000 -v ${PWD}/index.html:/home/static/index.html --name docker-static-site docker-static-site

NOTE: The --platform flag may, or may not be required, depending on the platform you are building on and for.

NOTE: The precompiled version of busybox_HTTPD does not support gzipped files as well the compiled one.

---

Original README:

docker-static-website

A very small Docker image (~154KB) to run any static website, based on the BusyBox httpd static file server.

If you're using the previous version (1.x, based on thttpd), I recommend upgrading since the new version (2.x) comes with a much smaller memory footprint.

For more details, check out my article.

Usage

The image is hosted on Docker Hub:

FROM lipanski/docker-static-website:latest

# Copy your static files
COPY . .

Build the image:

docker build -t my-static-website .

Run the image:

docker run -it --rm -p 3000:3000 my-static-website

Browse to http://localhost:3000.

If you need to configure the server in a different way, you can override the CMD line:

FROM lipanski/docker-static-website:latest

# Copy your static files
COPY . .

CMD ["/busybox", "httpd", "-f", "-v", "-p", "3000", "-c", "httpd.conf"]

NOTE: Sending a TERM signal to your TTY running the container won't get propagated due to how busybox is built. Instead you can call docker stop (or docker kill > if can't wait 15 seconds). Alternatively you can run the container with docker run -it --rm --init which will propagate signals to the process correctly.

FAQ

How can I serve gzipped files?

For every file that should be served gzipped, add a matching [FILENAME].gz to your image.

How can I use httpd as a reverse proxy?

Add a httpd.conf file and use the P directive:

P:/some/old/path:[http://]hostname[:port]/some/new/path

How can I overwrite the default error pages?

Add a httpd.conf file and use the E404 directive:

E404:e404.html

...where e404.html is your custom 404 page.

Note that the error page directive is only processed for your main httpd.conf file. It will raise an error if you use it in httpd.conf files added to subdirectories.

How can I implement allow/deny rules?

Add a httpd.conf file and use the A and D directives:

A:172.20.         # Allow address from 172.20.0.0/16
A:10.0.0.0/25     # Allow any address from 10.0.0.0-10.0.0.127
A:127.0.0.1       # Allow local loopback connections
D:*               # Deny from other IP connections

You can also allow all requests with some exceptions:

D:1.2.3.4
D:5.6.7.8
A:* # This line is optional

How can I use basic auth for some of my paths?

Add a httpd.conf file, listing the paths that should be protected and the corresponding credentials:

/admin:my-user:my-password # Require user my-user with password my-password whenever calling /admin

Where can I find the documentation for BusyBox httpd?

Read the source code comments.

Development

Clone the busybox repo and create a blank config:

make allnoconfig

Copy the resulting .config to this project, diff it against the old one and re-enable everything that seems reasonable (mostly the HTTPD features).

Uncomment the COPY . . line in the Dockerfile, add a dummy index.html and build a test image:

docker build -t docker-static-website-test .

Then run it:

docker run -it --rm --init -p 3000:3000 docker-static-website-test

Browse to http://localhost:3000 and check that the contents of the index.html file were rendered correctly.

Release

Build the image:

docker build -t lipanski/docker-static-website:1.2.3 .

Push the image to Docker Hub:

docker push lipanski/docker-static-website:1.2.3

Tag the release:

git tag 1.2.3
git push --tags

Enjoy! 😄