aosasona / chimney

A simple, fast, and easy to use static file server

Warning

This is still in early development, I would not recommend for production use.. yet.

See the issues for things that are on the "roadmap" or missing

This may not fit your usecase, have a look at Nginx and Caddy

A minimal static file server. See this example deployed on Fly.

Goals

• As tiny as possible
• Reasonably fast
• Serve files with the correct mime-types
• Predictable "routing" (the way you will expect it from like Nginx or Apache eg. if /foo is a folder, it should resolve fine to /foo/index.html)
• Rewrites and redirects should just work out of the box
• Little to no "would be nice" features (re goal one)
• Easily usable yet lean as an OCI image (this is more for the project I made it for, may not matter to anyone else)

Installation

With Docker

You can run the Docker image and provide a bind mount like this:

docker pull ghcr.io/aosasona/chimney:latest
docker run -p 80:80 -v ./dist:/var/www/html ghcr.io/aosasona/chimney:latest

Although, a more practical (and recommended) usage is to use it in a multi-stage build Dockerfile, this is a Dockerfile for an Astro website:

FROM node:18-alpine AS build

WORKDIR /app

COPY package.json pnpm-lock.yaml .

# Install pnpm package manager and install dependencies
RUN npm install -g pnpm

RUN pnpm install

# Copy files needed for the build, source directory and public folder
COPY astro.config.mjs tsconfig.json tailwind.config.cjs .

COPY src src

COPY public public

# Build to static HTML
RUN pnpm build

# Use chimney as final run image
FROM ghcr.io/aosasona/chimney:latest

# Copy the result of the previous build process (HTML files and the asssets; JS, CSS, Images, GIFs etc) to the default public directory
COPY --from=build /app/dist /var/www/html

# Replace the default config with our custom config
COPY chimney.toml /etc/chimney/chimney.toml

EXPOSE 80

# Start the proxy
CMD ["run"]

Directories

If you are using the official image, there are a few locations you might want to know about:

Path	Description
/var/www/html	Similar to NGINX, this is where all your publicly available files should be, including any asset. This path was chosen since it is familiar to most people, you can change this by overriding the default config and setting root_dir to anywhere you want in the container
/etc/chimney/chimney.toml	This is where the default config lives, you can change this by copying your own config to wherever you desire and writing CMD as ["run", "-c", "path/to/config"] in your custom Dockerfile
/bin/chimney	This is where the Chimney binary lives in the container, since the ENTRYPOINT has been set to this path, you can easily use the "docker run" command to execute commands in the container directly without specifying /bin/chimney

As a standalone binary

Currently, there is no way to install via Homebrew or Cargo (this may change in the future), but you can download the binary for your platform from the releases page. If you are using Windows, there are no builds available so you could try using the next option.

Build from source

If you are unable to or don't want to use Docker and there are no builds available for your platform, you can use Chimney by building from source:

git clone https://github.com/aosasona/chimney.git
cd chimney
cargo build --release

# and then run it
./target/release/chimney run

Usage

chimney init path/to/project
chimney run -c path/to/project/chimney.toml # the config filename is optional, it looks for `chimney.toml` by default in the target directory

Config reference

Warning

HTTPS functionality has NOT been implemented yet, so using this standalone in production is kind of not feasible... unless you have some sort of central proxy and a bunch of containers running Chimney that you simply proxy requests to (you can probably tell what my usecase is...)

Field	type	Description	Default
host	string	The IP address to bind to	0.0.0.0
port	integer	The (TCP) port to run the HTTP server on	80
domain_names	array	unimplemented The domain names that the server should respond to, this has also not been implemented yet and does nothing yet	[]
enable_logging	boolean	Enable/disable request logging (what gets logged is currently limited and not quite customisable)	true
root_dir	string	This is where your static files and assets are located, for example /var/www/html. This is relative to where the config is located if it is not an absolute path, for example, if your config is located at /Users/name/personal/chimney.toml and the root_dir is set to "public", this will be resolved to /Users/name/personal/public	"public"
fallback_document	string	The file that should be served if the requested path is neither a file that exists nor a valid redirect/rewrite, leaving this blank is also allowed and will just send the status code with no body. A good usecase would be setting this to index.html if you are serving an SPA, or 404.html if you have an Astro site for example	"index.html"
https.enable	boolean	unimplemented	false
https.auto_redirect	boolean	unimplemented	false
https.port	integer	unimplemented	443
https.use_self_signed	boolean	unimplemented	false
https.cert_file	string	unimplemented	nil
https.key_file	string	unimplemented	nil
rewrites	table	A rewrite generally maintains the same URL but serves something different, the file doesn't even need to exist. A rewrite could in fact point to a redirect, the leading slash is required when defining a rewrite. For example, if you have a rewrite defined as "/foo" = "page.html", even though foo is not a real file, when the server receives a request for /foo, it will read and serve the page.html file instead without the user knowing
headers	table	Extra headers you want to append to every response the server sends out	nil
redirects	table	A redirect maps a path to an external URL (including the current site). Unlike rewrites, a redirect does not read or serve a file, it simply takes the user away to the specified URL, and replays the request (useful for POSTs) if configured to. For example, "/foo" = { to = "https://example.com", replay = false } will take the user to example.com anytime they visit yourwebsite.com/foo but will NOT replay the request if it was a POST or similar.	nil

You can find sample config files here and here.

Why not [this other proxy/server]?

I made this for my very narrow use-case as both a learning exercise and because I:

• wanted something with a small surface area and extensible to suit my own needs for frontend deployment-related reasons later in the future (like #23)
• was interested in making something relatively small (both as a standalone binary and as a Docker image) - you can see most of the points are sort of related
• already had a well-defined scope, I only needed a static file server, these other proxies just also happen to be function as file servers, and they work fine but I did not want the 90% of features just to use the 10%
• wanted a bit more control, not just being able to extend as I go (also very possible with Caddy and Nginx) but things like choosing TOML over YAML (or a DSL) and in turn making defining things like redirects and rewrites pretty easy and familiar (I agree too, not much of a good reason)
• wanted to use and learn Rust "properly" (I still haven't read the book or taken a course :/), obviously, this was a great fit for it!

This is most definitely not what you want, and if it is, give it a go and let me know how you're using it, bugs you find and general feedback would be appreciated.

Contributing & feedback

I would love to hear from people who are actively using this mainly for bug fixes and feature suggestions, I may or may not add your desired feature if it doesn't fit any of the goals.

chimney's Issues

feat: properly set mimetype for other files

For files like the ones that will live in the .well-known directory, robots.txt, even *.json files and other such files, their mimetype should be properly inferred before falling back to text/html

docs: add documentation in readme

• explain the basic CLI usage
• show a docker example (deploy 1063 with it)
• add a table to explain the different config options

fix: include `chimney.toml` in examples folder

Big oof in the .gitignore

feat: respond to domain names

feat: support redirects

It already supports rewrites but there are cases where the user actually wants to redirect, add a new config option for that.

feat: generate best-match config from project

Could add a new --infer flag to the init command which will have a look at the project itself and use some pre-defined providers to try to generate a working config for the current project based on the type (SPA, MPA) and framework.

feat: support multiple projects/websites

Chimney is designed to work as a single website in a container together with the chimney binary, but what if we could serve multiple instead.

This will indeed be a breaking change if I go about it the wrong way, but we could add a new tenant-mode (or just mode although it may be more confusing) option that can be set to single or multi and that will be used to decide if the server wants to go with the root_dir or a new sites array of tables.

fix: account for nested-folders

e.g. /something should resolve fine to /something/index.html if it exists

feat: add config option to show and serve directory map

It might be nice to be able to just serve the directory structure with a nice UI sort of the way some other static file servers do

perf: optimise server methods to use less cloning where possible

feat: cache path resolutions

Chimney can resolve paths really fast right now but it'll be even faster if we can reuse the result of previous resolutions in new, similar requests.

cleanup: remove unused deps

feat: gzip and/or brotli compression (?)

feat: local SSL cert generation

Generate local SSL certs suitable for local development

feat: implement cache rules

The user should be able to control the default caching duration for specific file formats and paths even. Still unsure what that will look like but this is my current thought:

[cache_rules]
"*.png|*.jpg" = { duration = 30, exclude_dir = ["something"] } # where duration is `time to live`  (better term instead of duration) and 30 is in seconds
"/path/*" = 30 # matches /path/foo, /path/bar etc
"/exact-path" = 100 # strictly matches /exact-path

In code, extension-based cache rules and path-based cache rules will be handled separately.

update dockerfile

Update the PATH variable with ENV, fix comments and organise labels

docs: remove size comparison

Caddy's size is incorrectly stated for proper builds, and honestly, it's not comparable to be fair. It would be better to make it clear that I wanted this to be more specialised.

react to filesystem changes

If the config changes or if new sites are added with config in them, chimney should automatically pick them up

fix: don't set default fallback_document

Make it an option, and if it is not set, don't use the SPA behaviour of defaulting to index.html, just return not found

feat: allow users pass in config options via CLI in init instead of static template

Currently there is a static config template but we need to move away from that and make it a bit more dynamic

perf: stop cloning self in loop (server.rs; L99)

bug: investigate possible regression with fallback path

Latest deployment of my website does not seem to be falling back to 404.html as expected

update: add mimetype for `WASM`

feat: support external SSL/TLS certs

• Users should be able to use something like certbot and then point the server to where those certificates are
• Maybe support automatic cert generation via Let's Encrypt or ZeroSSL