Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
November 24, 2023 10:39
November 6, 2023 12:10
November 6, 2023 12:10
March 10, 2022 12:12
November 10, 2023 19:51
August 10, 2022 20:43


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.


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.


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:


How can I overwrite the default error pages?

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


...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
A:     # Allow any address from
A:       # Allow local loopback connections
D:*               # Deny from other IP connections

You can also allow all requests with some exceptions:

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.


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.


Build the image:

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

Push the image to Docker Hub:

docker push lipanski/docker-static-website:1.2.3
docker push lipanski/docker-static-website:latest

Tag the release:

git tag 1.2.3
git push --tags


A very small Docker image (~154KB) to run any static website






Sponsor this project