1 | [![build status](https://img.shields.io/travis/http-party/http-server.svg?style=flat-square)](https://travis-ci.org/http-party/http-server)
|
2 | [![npm](https://img.shields.io/npm/v/http-server.svg?style=flat-square)](https://www.npmjs.com/package/http-server) [![homebrew](https://img.shields.io/homebrew/v/http-server?style=flat-square)](https://formulae.brew.sh/formula/http-server) [![npm downloads](https://img.shields.io/npm/dm/http-server?color=blue&label=npm%20downloads&style=flat-square)](https://www.npmjs.com/package/http-server)
|
3 | [![license](https://img.shields.io/github/license/http-party/http-server.svg?style=flat-square)](https://github.com/http-party/http-server)
|
4 |
|
5 | # http-server: a command-line http server
|
6 |
|
7 | `http-server` is a simple, zero-configuration command-line http server. It is powerful enough for production usage, but it's simple and hackable enough to be used for testing, local development, and learning.
|
8 |
|
9 | ![Example of running http-server](https://github.com/http-party/http-server/raw/master/screenshots/public.png)
|
10 |
|
11 | ## Installation:
|
12 |
|
13 | #### Globally via `npm`
|
14 |
|
15 | npm install --global http-server
|
16 |
|
17 | This will install `http-server` globally so that it may be run from the command line anywhere.
|
18 |
|
19 | #### Globally via Homebrew
|
20 |
|
21 | brew install http-server
|
22 |
|
23 | #### Running on-demand:
|
24 |
|
25 | Using `npx` you can run the script without installing it first:
|
26 |
|
27 | npx http-server [path] [options]
|
28 |
|
29 | #### As a dependency in your `npm` package:
|
30 |
|
31 | npm install http-server
|
32 |
|
33 | ## Usage:
|
34 |
|
35 | http-server [path] [options]
|
36 |
|
37 | `[path]` defaults to `./public` if the folder exists, and `./` otherwise.
|
38 |
|
39 | *Now you can visit http://localhost:8080 to view your server*
|
40 |
|
41 | **Note:** Caching is on by default. Add `-c-1` as an option to disable caching.
|
42 |
|
43 | ## Available Options:
|
44 |
|
45 | `-p` or `--port` Port to use (defaults to 8080)
|
46 |
|
47 | `-a` Address to use (defaults to 0.0.0.0)
|
48 |
|
49 | `-d` Show directory listings (defaults to `true`)
|
50 |
|
51 | `-i` Display autoIndex (defaults to `true`)
|
52 |
|
53 | `-g` or `--gzip` When enabled (defaults to `false`) it will serve `./public/some-file.js.gz` in place of `./public/some-file.js` when a gzipped version of the file exists and the request accepts gzip encoding. If brotli is also enabled, it will try to serve brotli first.
|
54 |
|
55 | `-b` or `--brotli` When enabled (defaults to `false`) it will serve `./public/some-file.js.br` in place of `./public/some-file.js` when a brotli compressed version of the file exists and the request accepts `br` encoding. If gzip is also enabled, it will try to serve brotli first.
|
56 |
|
57 | `-e` or `--ext` Default file extension if none supplied (defaults to `html`)
|
58 |
|
59 | `-s` or `--silent` Suppress log messages from output
|
60 |
|
61 | `--cors` Enable CORS via the `Access-Control-Allow-Origin` header
|
62 |
|
63 | `-o [path]` Open browser window after starting the server. Optionally provide a URL path to open. e.g.: -o /other/dir/
|
64 |
|
65 | `-c` Set cache time (in seconds) for cache-control max-age header, e.g. `-c10` for 10 seconds (defaults to `3600`). To disable caching, use `-c-1`.
|
66 |
|
67 | `-U` or `--utc` Use UTC time format in log messages.
|
68 |
|
69 | `--log-ip` Enable logging of the client's IP address (default: `false`).
|
70 |
|
71 | `-P` or `--proxy` Proxies all requests which can't be resolved locally to the given url. e.g.: -P http://someurl.com
|
72 |
|
73 | `--username` Username for basic authentication [none]
|
74 |
|
75 | `--password` Password for basic authentication [none]
|
76 |
|
77 | `-S` or `--ssl` Enable https.
|
78 |
|
79 | `-C` or `--cert` Path to ssl cert file (default: `cert.pem`).
|
80 |
|
81 | `-K` or `--key` Path to ssl key file (default: `key.pem`).
|
82 |
|
83 | `-r` or `--robots` Provide a /robots.txt (whose content defaults to `User-agent: *\nDisallow: /`)
|
84 |
|
85 | `--no-dotfiles` Do not show dotfiles
|
86 |
|
87 | `-h` or `--help` Print this list and exit.
|
88 |
|
89 | `-v` or `--version` Print the version and exit.
|
90 |
|
91 | ## Magic Files
|
92 |
|
93 | - `index.html` will be served as the default file to any directory requests.
|
94 | - `404.html` will be served if a file is not found. This can be used for Single-Page App (SPA) hosting to serve the entry page.
|
95 |
|
96 | ## Catch-all redirect
|
97 |
|
98 | To implement a catch-all redirect, use the index page itself as the proxy with:
|
99 |
|
100 | ```
|
101 | http-server --proxy http://localhost:8080?
|
102 | ```
|
103 |
|
104 | Note the `?` at the end of the proxy URL. Thanks to [@houston3](https://github.com/houston3) for this clever hack!
|
105 |
|
106 | ## TLS/SSL
|
107 |
|
108 | First, you need to make sure that [openssl](https://github.com/openssl/openssl) is installed correctly, and you have `key.pem` and `cert.pem` files. You can generate them using this command:
|
109 |
|
110 | ``` sh
|
111 | openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
|
112 | ```
|
113 |
|
114 | You will be prompted with a few questions after entering the command. Use `127.0.0.1` as value for `Common name` if you want to be able to install the certificate in your OS's root certificate store or browser so that it is trusted.
|
115 |
|
116 | This generates a cert-key pair and it will be valid for 3650 days (about 10 years).
|
117 |
|
118 | Then you need to run the server with `-S` for enabling SSL and `-C` for your certificate file.
|
119 |
|
120 | ``` sh
|
121 | http-server -S -C cert.pem
|
122 | ```
|
123 |
|
124 | This is what should be output if successful:
|
125 |
|
126 | ``` sh
|
127 | Starting up http-server, serving ./ through https
|
128 | Available on:
|
129 | https:127.0.0.1:8080
|
130 | https:192.168.1.101:8080
|
131 | https:192.168.1.104:8080
|
132 | Hit CTRL-C to stop the server
|
133 | ```
|
134 |
|
135 | # Development
|
136 |
|
137 | Checkout this repository locally, then:
|
138 |
|
139 | ```sh
|
140 | $ npm i
|
141 | $ node bin/http-server
|
142 | ```
|
143 |
|
144 | *Now you can visit http://localhost:8080 to view your server*
|
145 |
|
146 | You should see the turtle image in the screenshot above hosted at that URL. See
|
147 | the `./public` folder for demo content.
|