UNPKG

5.49 kBMarkdownView Raw
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
17This 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
25Using `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
98To implement a catch-all redirect, use the index page itself as the proxy with:
99
100```
101http-server --proxy http://localhost:8080?
102```
103
104Note the `?` at the end of the proxy URL. Thanks to [@houston3](https://github.com/houston3) for this clever hack!
105
106## TLS/SSL
107
108First, 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
111openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
112```
113
114You 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
116This generates a cert-key pair and it will be valid for 3650 days (about 10 years).
117
118Then you need to run the server with `-S` for enabling SSL and `-C` for your certificate file.
119
120``` sh
121http-server -S -C cert.pem
122```
123
124This is what should be output if successful:
125
126``` sh
127Starting up http-server, serving ./ through https
128Available on:
129 https:127.0.0.1:8080
130 https:192.168.1.101:8080
131 https:192.168.1.104:8080
132Hit CTRL-C to stop the server
133```
134
135# Development
136
137Checkout 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
146You should see the turtle image in the screenshot above hosted at that URL. See
147the `./public` folder for demo content.