Skip to content

A simple static HTTP server in Rust, for learning and local doc development

Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation


A simple static HTTP server, for learning and local development.

basic-http-server is designed for two purposes:

  • as a teaching tool. It is a simple and well-commented example of basic tokio, hyper, and asynchronous Rust programming, with async / await.

  • for local development. It serves static HTML content, and with the -x flag, provides convenience features useful for creating developer documentation, including markdown rendering and directory listing.

The entire reference source for setting up a hyper HTTP server is contained in The file contains developer extensions.

Developer extensions

When passed the -x flag, basic-http-server enables additional conveniences useful for developing documentation locally. Those extensions are:

  • Rendering files with the ".md" extension as Markdown.

  • Listing directories when no "index.html" file is found.

  • Serving common source code files as "text/plain" so they are rendered in the browser.

This makes basic-http-server useful for the following scenarios:

  • Previewing markdown content. Draft your changes and view them locally before pushing to GitHub.

  • Navigating to local documentation, including Rust API documentation. Just run basic-http-server -x in your project directory, and use the directory listing to navigate to target/doc, then find the crates to read from there (cargo doc doesn't put an index.html file in target/doc).

Installation and Use

Note that basic-http-server is not production-ready and should not be exposed to the internet. It is a learning and development tool.

Install with cargo install:

$ cargo install basic-http-server
$ basic-http-server

To turn on the developer extensions, pass -x:

$ basic-http-server -x

To increase logging verbosity use RUST_LOG:

RUST_LOG=basic_http_server=trace basic-http-server -x

Command line arguments:

        basic-http-server [FLAGS] [OPTIONS] [ARGS]

    -x               Enable developer extensions
    -h, --help       Prints help information
    -V, --version    Prints version information

    -a, --addr <ADDR>    Sets the IP:PORT combination (default "")

    ROOT    Sets the root directory (default ".")




A simple static HTTP server in Rust, for learning and local doc development