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

Overview

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

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

CI Docker Cloud Build Status Crates.io license Stars Downloads Lines of Code

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

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

Packaging status

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

    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

    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

    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

    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)

    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

    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

    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

    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

    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)

    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

    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

    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

    Dependabot compatibility score

    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

    [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

    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

    [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

    [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
Releases(v0.22.0)
Owner
Sven-Hendrik Haase
Freelance consultant, DevOps and automation connoisseur, Arch Linux developer, hobbyist game and graphics programmer. Available for remote contracting.
Sven-Hendrik Haase
Static Web Server - a very small and fast production-ready web server suitable to serve static web files or assets

Static Web Server (or SWS abbreviated) is a very small and fast production-ready web server suitable to serve static web files or assets.

Jose Quintana 496 Jan 2, 2023
handle some lichess.org/tournament load with rust, while learning rust

lila-http Take some of the HTTP load away from lila. WIP! Arena tournaments Clients connected to a tournament page request new data about the tourname

Thibault Duplessis 22 Jan 2, 2023
Host These Things Please - a basic http server for hosting a folder fast and simply

http Host These Things Please - a basic HTTP server for hosting a folder fast and simply Selected features See the manpage for full list. Symlinks fol

thecoshman 367 Dec 23, 2022
Simple http server in Rust (Windows/Mac/Linux)

How it looks like? Screenshot Command Line Arguments Simple HTTP(s) Server 0.6.1 USAGE: simple-http-server [FLAGS] [OPTIONS] [--] [root] FLAGS:

LinFeng Qian 788 Dec 28, 2022
An HTTP library for Rust

hyper A fast and correct HTTP implementation for Rust. HTTP/1 and HTTP/2 Asynchronous design Leading in performance Tested and correct Extensive produ

null 11k Jan 7, 2023
[OUTDATED] A light HTTP framework for Rust

Rustful A light HTTP framework for Rust, with REST-like features. The main purpose of Rustful is to create a simple, modular and non-intrusive foundat

Erik Hedvall 873 Nov 12, 2022
Fully async-await http server framework

Saphir is a fully async-await http server framework for rust The goal is to give low-level control to your web stack (as hyper does) without the time

Richer Archambault 83 Dec 19, 2022
Low level HTTP server library in Rust

tiny-http Documentation Tiny but strong HTTP server in Rust. Its main objectives are to be 100% compliant with the HTTP standard and to provide an eas

null 785 Dec 29, 2022
:zap: fast http framework for rust

zap âš¡ The mission of zap is, to deliver a basic, but fast rust web server library. Documentation About This code is based on tokio's minihttp project,

Daniel Oltmanns 51 Jun 7, 2022
Add Facebook and Google authentication to your HTTP REST API in Actix-web

I created this project while learning Rust. Project shows how to handle Facebook and Google token verification in Rust using Actix-Web. Hope this help

null 37 Dec 31, 2022
Node.js http server framework powered by Hyper native binding.

hnsjs POC project. Install this test package yarn add @hnsjs/core Support matrix node10 node12 node14 node15 Windows x64 ✓ ✓ ✓ ✓ Windows x32 ✓ ✓ ✓ ✓

LongYinan 18 Nov 23, 2022
Akasio is a simple HTTP server that redirects traffic based on a JSON redirect table. This is its Rust implementation.

This page is inaccurate and is pending updates. Akasio (Rust) Description Akasio is a simple HTTP server that redirects traffic based on a JSON redire

K4YT3X 5 May 2, 2022
RUSTENGINE is the high-assurance HTTP server.

RUSTENGINE Table of Contents RUSTENGINE Table of Contents About RUSTENGINE Inspiration with Rust Features Compares with Nginx Build & Run About this R

FUNNY SYSTEMS 10 Aug 27, 2021
OxHTTP is a very simple synchronous HTTP client and server

OxHTTP is a very simple synchronous implementation of HTTP 1.1 in Rust. It provides both a client and a server.

Oxigraph 13 Nov 29, 2022
service_policy_kit is a Rust based toolkit for verifying HTTP services against policies.

Service Policy Kit service_policy_kit is a Rust based toolkit for verifying HTTP services against policies. You can: Build a complete testing framewor

null 19 Dec 5, 2022
A synchronous HTTP server built on hyper.

Astra Astra is a synchronous HTTP server built on top of hyper. use astra::{Body, Response, Server}; fn main() { Server::bind("localhost:3000")

Ibraheem Ahmed 23 Nov 27, 2022
Completely OBSOLETE Rust HTTP library (server and client)

OBSOLETION NOTICE This library is DEAD. It was a useful experiment and is now being replaced under the scope of the Teepee (experimentation grounds at

Chris Morgan 390 Dec 1, 2022
Archibald is my attempt at learning Rust and writing a HTTP 1.1 web server.

Archibald To be a butler, is to be able to maintain an even-temper, at all times. One must have exceptional personal hygiene and look sharp and profes

Daniel Cuthbert 4 Jun 20, 2022
A blazingly fast static web server with routing, templating, and security in a single binary you can set up with zero code. :zap::crab:

binserve âš¡ ?? A blazingly fast static web server with routing, templating, and security in a single binary you can set up with zero code. ?? UPDATE: N

Mufeed VH 722 Dec 27, 2022