🌟 For when you really just want to serve some files over HTTP right now!

Last update: Dec 31, 2022

Overview

miniserve - a CLI tool to serve files and dirs over HTTP

For when you really just want to serve some files over HTTP right now!

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. Sometimes this is just a more practical and quick way than doing things properly.

Screenshot

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/

Require username/password as hash:

pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
miniserve --auth joe:sha256:$pw unreleased-linux-distros/

Generate random 6-hexdigit URL:

miniserve -i 192.168.0.1 --random-route /tmp
# Serving path /private/tmp at http://192.168.0.1/c789b6

Bind to multiple interfaces:

miniserve -i 192.168.0.1 -i 10.13.37.10 -i ::1 /tmp/myshare

Features

Easy to use
Just works: Correct MIME types handling out of the box
Single binary drop-in with no extra dependencies required
Authentication support with username and password (and hashed password)
Mega fast and highly parallel (thanks to Rust and Actix)
Folder download (compressed on the fly as .tar.gz or .zip)
File uploading
Pretty themes
Scan QR code for quick access

Usage

miniserve 0.11.0
Sven-Hendrik Haase <[email protected]>, Boastful Squirrel <[email protected]>
For when you really just want to serve some files over HTTP right now!

USAGE:
    miniserve [FLAGS] [OPTIONS] [--] [PATH]

FLAGS:
    -D, --dirs-first
            List directories first

    -r, --enable-tar
            Enable tar archive generation

    -z, --enable-zip
            Enable zip archive generation

            WARNING: Zipping large directories can result in out-of-memory exception because zip generation is done in
            memory and cannot be sent on the fly
    -u, --upload-files
            Enable file uploading

    -h, --help
            Prints help information

    -P, --no-symlinks
            Do not follow symbolic links

    -o, --overwrite-files
            Enable overriding existing files during file upload

    -q, --qrcode
            Enable QR code display

        --random-route
            Generate a random 6-hexdigit route

    -V, --version
            Prints version information

    -v, --verbose
            Be verbose, includes emitting access logs


OPTIONS:
    -a, --auth <auth>...
            Set authentication. Currently supported formats: username:password, username:sha256:hash,
            username:sha512:hash (e.g. joe:123,
            joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3)
    -c, --color-scheme <color-scheme>
            Default color scheme [default: squirrel]  [possible values: squirrel, archlinux,
            zenburn, monokai]
    -d, --color-scheme-dark <color-scheme-dark>
            Default color scheme [default: archlinux]  [possible values: squirrel, archlinux,
            zenburn, monokai]
        --header <header>...
            Set custom header for responses
        --index <index_file>
            The name of a directory index file to serve, like "index.html"

            Normally, when miniserve serves a directory, it creates a listing for that directory. However, if a
            directory contains this file, miniserve will serve that file instead.
    -i, --interfaces <interfaces>...
            Interface to listen on

    -p, --port <port>
            Port to use [default: 8080]

    -t, --title <title>
            Shown instead of host in page title and heading


ARGS:
    <PATH>
            Which path to serve

How to install

On Linux: Download miniserve-linux from the releases page and run

chmod +x miniserve-linux
./miniserve-linux

Alternatively, if you are on Arch Linux, you can do

pacman -S miniserve

On OSX: Download miniserve-osx from the releases page and run

chmod +x miniserve-osx
./miniserve-osx

Alternatively install with Homebrew.

brew install miniserve
miniserve

On Windows: Download miniserve-win.exe from the releases page and run

miniserve-win.exe

With Cargo: Make sure you have a recent version of Rust. Then you can run

cargo install miniserve
miniserve

With Docker: If you prefer using Docker for this, run

docker run -v /tmp:/tmp -p 8080:8080 --rm -it svenstaro/miniserve /tmp

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.

Why use this over alternatives?

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.
netcat: Not as convenient to use and sending directories is somewhat involved.

Releasing

This is mostly a note for me on how to release this thing:

Make sure CHANGELOG.md is up to date.
cargo release --dry-run <version>
cargo release <version>
Releases will automatically be deployed by Github Actions.
Docker images will automatically be built by Docker Hub.
Update Arch package.

Comments

Interfaces

1. Report if any address fails to bind

::actix_web::HttpServer::bind() fails if and only if ALL the requested addresses fail to bind! an the docs require multiple calls for multiple addresses.

2. Fix: faulty bahvior when setting -i 0.0.0.0

Currrently, 0.0.0.0 address is converted into 127.0.0.1!

Closes #470

3. Fix: On Windows, miniserve binds only to localhost(127.0.0.1) by default

This is in part because of the issue mentioned above, and also because binding to :: binds only to IPv6 by default on Windows!

Closes #405 Also reported by @KaneGreen in #470.

4. cross-platform default binding addresses

Currently, miniserve by default binds to both 0.0.0.0 and :: ant the same time. This behaviour has a problem:

On some platforms (e.g. majority of linux distros and OSX?) , the :: address also accepts ipv4 connections. This makes these two addresses incompatible! See https://stackoverflow.com/questions/1618240/how-to-support-both-ipv4-and-ipv6-connections

~I currently have no idea how this should be fixed!~

5. implement #422

Closes #422

opened by aliemjay 24
Themed errors

Error pages should now follow the query parameters the user had before. So, this respects the theme, but also the potential sorting parameters the user had (this is useful when using the go back to file listing link). Also, I implemented Copy for some of our enums, as it greatly reduce the boilerplate and makes the code more readable, I think.

opened by ghost 22
File upload
This is my WIP for file uploading #6

I would like to clean up my error handling and discus some ideas.

if we can upload files, maybe I should add option to delete files too

Is it ok to override existing files?

I think the ability to upload file should be behind CLI flag and not by default

I've tested my code only under linux, but it seems ok.
opened by vojta7 22
Add support for readme rendering
Fixes https://github.com/svenstaro/miniserve/issues/859

Suggestions are welcome, I'm only implemented the basic render for now.

Other things that might be needed:

user flag to turn on/off readme rendering

render html bits inside markdown (might to be fixed from markdown crate)

other formats besides .md (.txt and , maybe .org)
opened by Atreyagaurav 20
Add support for media streaming (video files)

Hi there!

I've been using Miniserve for a quite a bit now, and I'm really enjoying this tool. But I find it misses a feature I'd personally would love to see: video streaming.

If I go the URI of a picture for instance it will be displayed by the browser correctly. But if it's an ~~video~~ audio file (e.g. MP~~4~~3) it will be downloaded instead of being played.

Would it be possible to implement support for these formats? I have no idea if it would be complicated, just thought I'd throw the idea here :)
good first issue

opened by ClementNerma 17
Implement raw view to allow recursive downloading via wget
Currently it's not easily possible to use wget to download a folder served with miniserve because the rendered directory listing contains links for the different .tar options, themes and whatnot.

This implements a raw view which can get accessed via http://.../somedir/foo/?raw and is a stripped down html version

Besides this it also implements a new ui element which contains a generated wget command to download this folder via wget

This is probably a hackish attempt, but works quite well. If there's a chance of this feature getting merged, i would overhaul it, add integration tests and whatnot.
opened by Jikstra 17
Split integration test into multiple files

Fix https://github.com/svenstaro/miniserve/issues/85

An additional issue arises: cargo test warns me of unused items in helper module. This happens because the items are only used by test functions in test-only context. I don't know how to fix this other than #[allow(dead_code)].

opened by KSXGitHub 17
Resolve symlinks on directory listing

This has the benefit of showing the size and modification date of the pointed-to file. Symlink to directories now respects '--dirs-first' option and broken symlinks don't show up in directory listing.

The only downside AFAIK is more syscalls when listing directories.

@svenstaro Any input on this? should it be configurable? can we abandon the symlink symbol?

opened by aliemjay 16
Download folders in .tar.gz format

This is my WIP for solving #2 (only .tar.gz at the moment).

The code isn't quite clean, the error handling needs some more work, and I have a bug on Mac OS X because user folders are wierd symlinks, and it causes the current code to fail. I'm investigating this issue.

Otherwise, it works pretty well :)

opened by ghost 16
add a default index serving option (#156)

Start addressing #156

~~Do you know where I should consume this option and how to configure active-web to serve the file? I started modifying fn configure_app( but couldn't figure out how to make it serve an index.html from within a configured directory root.~~

opened by ghost 15
Color schemes

So, here is my WIP to solve #51, and in a more general way, have different colour schemes. At the moment, I implemented 3 dark themes since I'm more comfortable designing them, but I'll eventually come up with a light theme (or multiple ones, if needed), I just have to find a nice way to make the colours fit together...

I also did several improvements to the CSS in general (padding, back to top button bigger, and only visible on small screen (I can set it back if needed), etc). Also, I prepared the moment when we'll have several compression methods available. Download buttons should fit nicely next to each-other.

I am open to any changes when it comes to the colours, or the design in general. Let's use this PR to fix everything that you don't like design-wise :)

opened by ghost 15
Bump grass from 0.12.0 to 0.12.1
Bumps grass from 0.12.0 to 0.12.1.

Changelog

Sourced from grass's changelog.

0.12.1

add grass::include! macro to make it easier to include CSS at compile time

various optimizations improving the bootstrap benchmark by ~30% and the bulma benchmark by ~15%

improve error message for complex units in calculations

more accurate formatting of named arguments in arglists when passed to inspect(..)

more accurate formatting of nested lists with different separators when passed to inspect(..)

support $whiteness and $blackness as arguments to scale-color(..)

more accurate list separator from join(..)

resolve unicode edge cases in str-index(..)

more robust support for @forward prefixes

allow strings as the first argument to call(..)

bug fix: add back support for the $css argument to get-function(..). regressed in 0.12.0

Commits

See full diff in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

@dependabot rebase will rebase this PR

@dependabot recreate will recreate this PR, overwriting any edits that have been made to it

@dependabot merge will merge this PR after your CI passes on it

@dependabot squash and merge will squash and merge this PR after your CI passes on it

@dependabot cancel merge will cancel a previously requested merge and block automerging

@dependabot reopen will reopen this PR if it is closed

@dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually

@dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)

@dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)

@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

dependencies
opened by dependabot[bot] 0
[Feature Request] Block crawler bots by default with robots.txt

Hi all, I have a public-facing instance of Miniserve running at home and I've noticed that I often get flooded with requests for random files in my directories by Googlebot. (including requests for zipped download of entire directory)

I would love it if miniserve either by default, or through a switch, served a static robots.txt that disallows crawling by bots.

Google Developers has an example of how to formulate a robots.txt that disallows crawling here.

If there's some interest I don't mind trying to implement it myself but it would have to be in a few days.

Open to suggestions!

opened by hashFactory 1

Error running Docker Container on ARM64

I am attempting to run miniserve as a Docker container on Apple Silicone (M1 Pro). Works fine on an x64 Mac but not on Apple Silicone.

When I run, it crashes with www exited with code 139 whether I use Docker Compose or from CLI.

services:
  www:
    container_name: www
    image: svenstaro/miniserve
    #tty: true
    #restart: always
    volumes:
      - /www:/www
    ports:
      - "8080:8080"
    command: "--dirs-first --enable-tar --title www /www"

docker run -v /www:/www -p 8080:8080  -it docker.io/svenstaro/miniserve /www

opened by jmcombs 3

$Unable to upload a/o create folder on any other disk than C:\ on Win10$

Unable to upload a/o create folder on any other disk than C:\ on Win10

Hi, I'm using miniserve on a Windows 10 laptop

When miniserve's path to serve is on C:\ disk, upload of file a/o directory creation works fine, and is possible, at least as soon as appropriate access rights are granted on local NTFS disk.

But if the path to serve is on another local disk (eg "miniserve D:\Temp\ -u -U" ), upload of files a/o directory creation systematically fail with the error message "Insufficient permissions to create file in \?\D:\Temp", and this even if full control has been granted to everyone at OS level in this target folder. On the other hand, it works "sometimes" even on disk D: For example, if I create a new folder D:\Test (at Win10 level), then launch "miniserve D:\Test -u -U", I'm able to upload files a/o create directories... while access rights are exactly the same at OS level for D:\Test and D:\Temp....

Moreover, in case access rights are NOT granted to users in target dir, upload and directory creation are (hopefully...) not possible, but the error message is not at all the same, but rather "Failed to create mysubdir / caused by: Accès refusé. (os error 5)", or "Failed to create \?\D:\Test\P1080514.JPG / caused by: Accès refusé. (os error 5)"

opened by LaurentGrenet 0
[fix] Sorting breaks subdir downloading

Adds a small check in render.rs make_link_with_trailing_slash to do nothing if link is empty, instead of adding a slash where its not needed.

It looks like nothing calls make_link_with_trailing_slash with an empty string aside from downloading when sorting, so this should not break anything else.

You can test the fix out here if needed: https://archive.vamist.dev/

Another alternative fix is to just not include sorting options when downloading, so if you would rather this, let me know.

Fixes #967

opened by Vam-Jam 0
[feature request] online file "viewer"

allow users to view various file in miniserve , images like png/jpg , media files like mp3/mp4/avi , and text files like yml/py/markdown what do you think ?

opened by changchichung 0