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 tiny 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, like this:

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 ["serve"]

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 serve

Usage

chimney init -p path/to/config
chimney serve -c path/to/config/chimney.toml

HTTPS Configuration

Chimney supports HTTPS with both manual certificates and automatic certificate issuance via ACME (Let's Encrypt).

Automatic Certificate Issuance (ACME)

Chimney can automatically obtain and renew TLS certificates from Let's Encrypt using the ACME protocol. Enable HTTPS globally in your main chimney.toml:

# chimney.toml (main config)
[https]
enabled = true
acme_email = "admin@example.com"
# acme_directory_url = "https://acme-v02.api.letsencrypt.org/directory"  # Default (production)

When global HTTPS is enabled, all sites automatically use ACME for certificate issuance. No per-site configuration is required for ACME mode.

Important Notes:

• Uses TLS-ALPN-01 validation (challenges are served on port 443)
• Certificates are cached in .chimney/certs/ directory
• Automatic renewal happens in the background
• For testing, use Let's Encrypt staging: acme_directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"
• Port 443 must be accessible from the internet for ACME validation

Manual Certificates

To use manual certificates for a specific site instead of ACME, provide cert_file and key_file in the site's chimney.toml:

# sites/example/chimney.toml
root = "."
domain_names = ["example.com", "www.example.com"]

[https_config]
cert_file = "/path/to/cert.pem"
key_file = "/path/to/key.pem"
# ca_file = "/path/to/ca.pem"   # Optional CA certificate
# auto_redirect = true          # Default: redirect HTTP to HTTPS

Generating Self-Signed Certificates (for testing)

openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout key.pem -out cert.pem -days 365 \
  -subj "/CN=example.com"

Dual Listener Architecture

When HTTPS is enabled:

• HTTP listener runs on the configured port (default: 80)
• HTTPS listener runs on port 443
• Requests are automatically redirected from HTTP to HTTPS when auto_redirect = true

SNI Support

Chimney supports Server Name Indication (SNI), allowing multiple sites with different certificates on the same server. Each site can have its own certificate configuration.

Mixed Configurations

You can mix ACME and manual certificates across different sites:

• Some sites can use ACME for automatic certificate management
• Other sites can use manual certificates
• All sites benefit from SNI-based certificate selection

Why not [this other proxy/server]?

Because I wanted to make one, and I did. That's the simple answer.

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.

Note

HTTPS is fully supported with both manual certificates and automatic certificate issuance via ACME (Let's Encrypt). See the HTTPS Configuration section above for details.