2018-05-17 13:37:26 +00:00
# miniserve - a CLI tool to serve files and dirs over HTTP
2018-04-26 17:44:30 +00:00
2018-04-26 17:32:25 +00:00
[](https://travis-ci.org/svenstaro/miniserve)
2019-02-19 18:17:31 +00:00
[](https://cloud.docker.com/repository/docker/svenstaro/miniserve/)
2018-04-26 17:32:25 +00:00
[](https://aur.archlinux.org/packages/miniserve/)
[](https://crates.io/crates/miniserve)
[](https://deps.rs/repo/github/svenstaro/miniserve)
[](https://github.com/svenstaro/miniserve/blob/master/LICENSE)
2019-02-15 19:34:16 +00:00
[](https://github.com/svenstaro/miniserve/stargazers)
[](https://github.com/svenstaro/miniserve/releases)
2018-04-26 17:32:25 +00:00
2018-12-25 14:46:59 +00:00
**For when you really just want to serve some files over HTTP right now!**
2018-05-16 13:07:49 +00:00
**miniserve** is a small, self-contained cross-platform CLI tool that allows you to just grab the binary and serve some file(s) via HTTP.
2018-05-16 12:44:25 +00:00
Sometimes this is just a more practical and quick way than doing things properly.
2019-04-10 12:58:29 +00:00
## Screenshot
2019-04-10 12:57:18 +00:00
2018-05-16 11:55:28 +00:00
## How to use
### Serve a directory:
miniserve linux-distro-collection/
### Serve a single file:
miniserve linux-distro.iso
### Require username/password:
miniserve --auth joe:123 unreleased-linux-distros/
2019-02-03 11:03:20 +00:00
### Generate random 6-hexdigit URL:
2019-02-15 20:04:20 +00:00
miniserve -i 192.168.0.1 --random-route /tmp
2019-02-03 11:03:20 +00:00
# Serving path /private/tmp at http://192.168.0.1/c789b6
2018-08-10 05:05:11 +00:00
### Bind to multiple interfaces:
2019-02-16 12:06:22 +00:00
miniserve -i 192.168.0.1 -i 10.13.37.10 -i ::1 /tmp/myshare
2018-08-10 05:05:11 +00:00
2018-05-16 11:55:28 +00:00
## Features
- Easy to use
- Just works: Correct MIME types handling out of the box
2018-05-16 13:08:11 +00:00
- Single binary drop-in with no extra dependencies required
2018-05-16 11:55:28 +00:00
- Authentication support with username and password
- Mega fast and highly parallel (thanks to [Rust ](https://www.rust-lang.org/ ) and [Actix ](https://actix.rs/ ))
2019-03-09 17:03:29 +00:00
- Folder download (compressed in .tar.gz)
2019-04-04 08:56:04 +00:00
- File uploading
2018-05-16 11:55:28 +00:00
2019-03-19 20:00:14 +00:00
## Known limitations
- **For now**, the tar.gz compression is not async-ready, which means that the whole archive needs to be created (in memory) before the download starts. While it should not be a problem for small folders, the download feature can really get resource-heavy for large folders.
2018-05-16 11:55:28 +00:00
## How to install
**On Linux**: Download `miniserve-linux` from [the releases page ](https://github.com/svenstaro/miniserve/releases ) and run
chmod +x miniserve-linux
./miniserve-linux
**On OSX**: Download `miniserve-osx` from [the releases page ](https://github.com/svenstaro/miniserve/releases ) and run
chmod +x miniserve-osx
./miniserve-osx
2018-05-16 12:44:25 +00:00
**On Windows**: Download `miniserve-win.exe` from [the releases page ](https://github.com/svenstaro/miniserve/releases ) and run
miniserve-win.exe
2018-05-16 11:55:28 +00:00
2019-02-23 10:06:19 +00:00
**With Cargo**: You will need the _nightly_ version of Rust to compile the project. Then you can run
2018-05-16 11:55:28 +00:00
cargo install miniserve
miniserve
2019-02-15 15:46:11 +00:00
**With Docker:** If you prefer using Docker for this, run
docker run -v /tmp:/tmp -p 8080:8080 --rm -it svenstaro/miniserve /tmp
2018-08-10 05:05:11 +00:00
## Binding behavior
For convenience reasons, miniserve will try to bind on all interfaces by default (if no `-i` is provided).
It will also do that if explicitly provided with `-i 0.0.0.0` or `-i ::` .
In all of the aforementioned cases, it will bind on both IPv4 and IPv6.
If provided with an explicit non-default interface, it will ONLY bind to that interface.
You can provide `-i` multiple times to bind to multiple interfaces at the same time.
2018-05-16 13:08:38 +00:00
## Why use this over alternatives?
2018-05-16 11:55:28 +00:00
2018-05-16 12:44:25 +00:00
- darkhttpd: Not easily available on Windows and it's not as easy as download and go.
- Python built-in webserver: Need to have Python installed, it's low performance, and also doesn't do correct MIME type handling in some cases.
2018-05-17 13:59:10 +00:00
- netcat: Not as convenient to use and sending directories is [somewhat involved ](https://nakkaya.com/2009/04/15/using-netcat-for-file-transfers/ ).
2018-06-07 21:41:40 +00:00
## Releasing
This is mostly a note for me on how to release this thing:
2019-01-11 02:55:13 +00:00
- Update version in `Cargo.toml` and run `cargo update` .
2018-06-07 21:41:40 +00:00
- `git commit` and `git tag -s` , `git push` .
- `cargo publish`
- Releases will automatically be deployed by Travis.
- Update AUR package.
