miniserve

miniserve is a small, self-contained cross-platform CLI tool that allows you to serve files and directories over HTTP.

Installation

Usage

To serve a directory

$ miniserve /srv/http

Refer to miniserve --help or miniserve(1) for additional options, such as custom index files, authentication, interface binding, TLS, compressed folder download, and file upload capability.

Configuration

Temporary

miniserve does not use a configuration file. Instead, all options are passed via the CLI or set through environment variables. For example:

$ MINISERVE_VERBOSE=true MINISERVE_PORT=8081 miniserve --enable-webdav /srv/http

This enables verbose logging, changes the port from the default 8080 to 8081, and starts miniserve with read-only WebDAV support.

Permanent

A hardened systemd template unit file miniserve@.service is included with the package and can be customized via a drop-in file.

At first the path you wish to serve (e.g. /srv/http) must be escaped for a valid systemd unit name. Use systemd-escape(1) to format it correctly :

$ systemd-escape /srv/http

-srv-http

-srv-http is your desired path, translated into a valid instance name for the systemd unit.

Use the escaped path as the instance name to configure miniserve with your desired settings:

/etc/systemd/system/miniserve@-srv-http.d/environment.conf

[Service]
Environment=MINISERVE_VERBOSE=true
Environment=MINISERVE_PORT=8087

You might additionally have to override IPAddressAllow and IPAddressDeny if you plan on making miniserve directly available on a public interface.

Start and enable the unit with full instance name and inspect the journal.

Testing

Upon startup, miniserve reports the bound interface and a list of available IP addresses:

Bound to [::]:8080, 0.0.0.0:8080
Serving path /srv/http
Available at (non-exhaustive list):
   http://127.0.0.1:8080
   http://192.168.0.50:8080
   http://[::1]:8080

A health check is implemented and should return "OK":

$ curl http://127.0.0.1:8080/__miniserve_internal/healthcheck