a simple static web server written in Go
Go Python
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Ran: a simple static web server written in Go


Ran is a simple web server for serving static files.


  • Directory listing
  • Automatic gzip compression
  • Digest authentication
  • Access logging
  • Custom 401 and 404 error file
  • TLS encryption

What is Ran for?

  • File sharing in LAN or home network
  • Web application testing
  • Personal web site hosting or demonstrating



Use the command below to install the dependencies mentioned above, and build the binary into $GOPATH/bin.

go get -u github.com/m3ng9i/ran

For convenience, you can move the ran binary to a directory in the PATH environment variable.

You can also call ./build.py command under the Ran source directory to write version information into the binary, so that ran -v will give a significant result. Run ./build.py -h for help.

Download binary

You can also download the Ran binary without building it yourself.

Download Ran binary from the release page.

Run Ran

You can start a web server without any options by typing ran and pressing return in terminal window. This will use the following default configuration:

Configuration Default value
Root directory the current working directory
Port 8080
Index file index.html, index.htm
List files of directories false
Gzip true
Digest auth false
TLS encryption off

Open in browser to see your website.

You can use the command line options to override the default configuration.


    -r,  -root=<path>        Root path of the site. Default is current working directory.
    -p,  -port=<port>        HTTP port. Default is 8080.
         -404=<path>         Path of a custom 404 file, relative to Root. Example: /404.html.
    -i,  -index=<path>       File name of index, priority depends on the order of values.
                             Separate by colon. Example: -i "index.html:index.htm"
                             If not provide, default is index.html and index.htm.
    -l,  -listdir=<bool>     When request a directory and no index file found,
                             if listdir is true, show file list of the directory,
                             if listdir is false, return 404 not found error.
                             Default is false.
    -sa, -serve-all=<bool>   Serve all paths even if the path is start with dot.
    -g,  -gzip=<bool>        Turn on or off gzip compression. Default value is true (means turn on).

    -am, -auth-method=<auth> Set authentication method, valid values are basic and digest. Default is basic.
    -a,  -auth=<user:pass>   Turn on authentication and set username and password (separate by colon).
                             After turn on authentication, all the page require authentication.
         -401=<path>         Path of a custom 401 file, relative to Root. Example: /401.html.
                             If authentication fails and 401 file is set,
                             the file content will be sent to the client.

         -tls-port=<port>    HTTPS port. Default is 443.
         -tls-policy=<pol>   This option indicates how to handle HTTP and HTTPS traffic.
                             There are three option values: redirect, both and only.
                             redirect: redirect HTTP to HTTPS
                             both:     both HTTP and HTTPS are enabled
                             only:     only HTTPS is enabled, HTTP is disabled
                             The default value is: only.
         -cert=<path>        Load a file as a certificate.
                             If use with -make-cert, will generate a certificate to the path.
         -key=<path>         Load a file as a private key.
                             If use with -make-cert, will generate a private key to the path.

Other options:

         -make-cert          Generate a self-signed certificate and a private key used in TLS encryption.
                             You should use -cert and -key to set the output paths.
         -showconf           Show config info in the log.
         -debug              Turn on debug mode.
    -v,  -version            Show version information.
    -h,  -help               Show help message.

If you want to shutdown Ran, type ctrl+c in the terminal, or kill it in the task manager.


Example 1: Start a server in the current directory and set port to 8888

ran -p=8888

Example 2: Set root to /tmp, list files of directories and set a custom 404 page

ran -r=/tmp -l=true -404=/404.html

-l=true can be shorted to -l for convenience.

Example 3: Turn off gzip compression, set access username and password and set a custom 401 page

ran -g=false -a=user:pass -401=/401.html

Example 4: Set custom index file

ran -i default.html:index.html

Example 5: Turn on TLS encryption

If you want to turn on TLS encryption (https), you should use -cert to load a certificate and -key to load a private key.

The default TLS port is 443, you can use -tls-port to set it to another port.

The following command load a certificate and a private key, and set TLS port to 9999. It can be browsed at

ran -cert=/path/to/cert.pem -key=/path/to/key.pem -tls-port=9999

Example 6: Control HTTP and HTTPS traffic

When you turn on TLS, you can choose to disable HTTP, redirect HTTP to HTTPS or let them work together.

You can use -tls-policy to control HTTP and HTTPS traffic:

  • If set to "redirect", all HTTP traffic will be redirect to HTTPS.
  • If set to "both", both HTTP and HTTPS are enabled.
  • If set to "only", only HTTPS is enabled, HTTP is disabled.

If not provide -tls-policy, the default value "only" will be used.

An example:

ran -cert=cert.pem -key=key.pem -tls-policy=redirect

Example 7: Create a self-signed certificate and a private key

For testing purposes or internal usage, you can use -make-cert to create a self-signed certificate and a private key.

ran -make-cert -cert=/path/to/cert.pem -key=/path/to/key.pem

Tips and tricks

Execute permission

Before running Ran binary or build.py, make sure they have execute permission. If don't, use chmod u+x <filename> to set.

download parameter

If you add download as a query string parameter in the url, the browser will download the file instead of displaying it in the browser window. Example:

gzip parameter

Gzip compression is enabled by default. Ran will gzip file automaticly according to the file extension. Example: a .txt file will be compressed and a .jpg file will not.

If you add gzip=true in the url, Ran will force compress the file even if the file should not be compressed. Example:

If you add gzip=false in the url, Ran will not compress it even if it should be compressed. Example:

Read the source code of CanBeCompressed() to learn more about automatic gzip compression.


  • v0.1.3:

    • Add trailing slash if the request path is a directory and the directory contains a index file.
    • Add basic auth; add -am, -auth-method option.
    • Add -sa, -serve-all option to set if skip paths that start with dot.
    • Print the listening URLs after the server starts.
  • v0.1.2: Add TLS encryption; add custom 401 file.

  • v0.1.1: Fix bugs and typos.

  • v0.1: Initial release.


The following functionalities will be added in the future:

  • Load config from file
  • IP filter
  • Custom log format
  • etc

What's the meaning of Ran

It's a Chinese PinYin and pronounce 燃, means flame burning.


mengqi https://github.com/m3ng9i

If you like this project, please give me a star.