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
- Disable content caching
- Write cross-origin resource sharing headers to the response
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.
Running with Docker
docker run -d -p 8080:8080 -v /public:/web m3ng9i/ran
Directory volume mounted to
/web will be served by default.
Below is another example, the options
-l -404 /404page.html are passed to the
docker run --name ran -d -p 8080:8080 -v /public:/web:ro m3ng9i/ran -l -404 /404page.html
You can also download the Ran binary without building it yourself.
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:
|Root directory||the current working directory|
|Index file||index.html, index.htm|
|List files of directories||false|
|Serve all path||false|
|Write cross-origin headers||false|
Open http://127.0.0.1:8080 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. -b, -bind-ip=<ip> Bind one or more IP addresses to the ran web server. Multiple IP addresses should be separated by comma. If not provide this Option, ran will use 0.0.0.0. -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. Default is false. -g, -gzip=<bool> Turn on or off gzip compression. Default value is true (means turn on). -nc, -no-cache=<bool> If true, ran will remove Last-Modified header and write some no-cache headers to the response: Cache-Control: no-cache, no-store, must-revalidate Pragma: no-cache Expires 0 Default is false. -cors=<bool> If true, ran will write some cross-origin resource sharing headers to the response: Access-Control-Allow-Origin: * Access-Control-Allow-Credentials: true Access-Control-Allow-Methods: * Access-Control-Allow-Headers: * If the request header has a Origin field, then it's value is used in Access-Control-Allow-Origin. Default is false. -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.
-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
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 https://127.0.0.1:9999.
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.
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
Example 8: Custom IP binding
Tips and tricks
Before running Ran binary or build.py, make sure they have execute permission. If don't, use
chmod u+x <filename> to set.
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 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.6: Fix security issue under Windows
-b, -bind-ipfor custom IP binding
- URL for 404 page now return status 404
-no-cacheoption to disable content caching
-corsoption to write cross-origin resource sharing headers to the response
- Record the X-Real-Ip field in the request header to the log
- Fix bug of file not being closed after opening
- Use HTML template for directory listing (thanks to @toby)
- 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
What's the meaning of Ran
It's a Chinese PinYin and pronounce 燃, means flame burning.
If you like this project, please give me a star.