hotel README

The project's README from github.com/typicode/hotel. As one markdown file: README.md.

hotel

Start apps from your browser and use local domains/https automatically

Tip: if you don't enable local domains, hotel can still be used as a catalog of local servers.

Hotel works great on any OS (macOS, Linux, Windows) and with all servers :heart:

To all the amazing people who have answered the Hotel survey, thanks so much <3 !

v0.8.0 upgrade

.localhost replaces .dev local domain and is the new default. See https://ma.ttias.be/chrome-force-dev-domains-https-via-preloaded-hsts/ for context.

If you're upgrading, please be sure to:

  1. Remove "tld": "dev" from your ~/.hotel/conf.json file
  2. Run hotel stop && hotel start
  3. Refresh your network settings

Support

If you are benefiting from hotel, you can support its development on Patreon.

You can view the list of Supporters here https://thanks.typicode.com.

Video

Features

Install

npm install -g hotel && hotel start

Hotel requires Node to be installed, if you don't have it, you can simply install it using one of the following method:

You can also visit https://nodejs.org.

Quick start

Local domains (optional)

To use local .localhost domains, you need to configure your network or browser to use hotel's proxy auto-config file or you can skip this step for the moment and go directly to http://localhost:2000

See instructions here.

Add your servers

# Add your server to hotel
~/projects/one$ hotel add 'npm start'
# Or start your server in the terminal as usual and get a temporary local domain
~/projects/two$ hotel run 'npm start'

Visit localhost:2000 or http(s)://hotel.localhost.

Alternatively you can directly go to

http://localhost:2000/one
http://localhost:2000/two

http(s)://one.localhost
http(s)://two.localhost

Using other servers? Here are some examples to get you started :)

hotel add 'ember server'                               # Ember
hotel add 'jekyll serve --port $PORT'                  # Jekyll
hotel add 'rails server -p $PORT -b 127.0.0.1'         # Rails
hotel add 'python -m SimpleHTTPServer $PORT'           # static file server (Python)
hotel add 'php -S 127.0.0.1:$PORT'                     # PHP
hotel add 'docker-compose up'                          # docker-compose
hotel add 'python manage.py runserver 127.0.0.1:$PORT' # Django
# ...

On Windows use "%PORT%" instead of '$PORT'

See a Docker example here..

Proxy requests to remote servers

Add your remote servers

~$ hotel add http://192.168.1.12:1337 --name aliased-address
~$ hotel add http://google.com --name aliased-domain

You can now access them using

http://aliased-address.localhost # will proxy requests to http://192.168.1.12:1337
http://aliased-domain.localhost # will proxy requests to http://google.com

CLI usage and options

hotel add <cmd|url> [opts]
hotel run <cmd> [opts]

# Examples

hotel add 'nodemon app.js' --out dev.log  # Set output file (default: none)
hotel add 'nodemon app.js' --name name    # Set custom name (default: current dir name)
hotel add 'nodemon app.js' --port 3000    # Set a fixed port (default: random port)
hotel add 'nodemon app.js' --env PATH     # Store PATH environment variable in server config
hotel add http://192.168.1.10 --name app  # map local domain to URL

hotel run 'nodemon app.js'                # Run server and get a temporary local domain

# Other commands

hotel ls     # List servers
hotel rm     # Remove server
hotel start  # Start hotel daemon
hotel stop   # Stop hotel daemon

To get help

hotel --help
hotel --help <cmd>

Port

For hotel to work, your servers need to listen on the PORT environment variable. Here are some examples showing how you can do it from your code or the command-line:

var port = process.env.PORT || 3000
server.listen(port)

hotel add 'cmd -p $PORT'  # OS X, Linux
hotel add "cmd -p %PORT%" # Windows

Fallback URL

If you're offline or can't configure your browser to use .localhost domains, you can always access your local servers by going to localhost:2000.

Configurations, logs and self-signed SSL certificate

You can find hotel related files in ~/.hotel :

~/.hotel/conf.json
~/.hotel/daemon.log
~/.hotel/daemon.pid
~/.hotel/key.pem
~/.hotel/cert.pem
~/.hotel/servers/<app-name>.json

By default, hotel uses the following configuration values:

{
  "port": 2000,
  "host": '127.0.0.1',
  
  // Timeout when proxying requests to local domains
  "timeout": 5000,
  
  // Change this if you want to use another tld than .localhost
  "tld": 'localhost', 
  
  // If you're behind a corporate proxy, replace this with your network proxy IP (example: "1.2.3.4:5000")
  "proxy": false
}

To override a value, simply add it to ~/.hotel/conf.json and run hotel stop && hotel start

Third-party tools

FAQ

Setting a fixed port

hotel add --port 3000 'server-cmd $PORT'

Adding X-Forwarded-* headers to requests

hotel add --xfwd 'server-cmd'

Setting HTTP_PROXY env

Use --http-proxy-env flag when adding your server or edit your server configuration in ~/.hotel/servers

hotel add --http-proxy-env 'server-cmd'

Proxying requests to a remote https server

hotel add --change-origin 'https://jsonplaceholder.typicode.com'

When proxying to a https server, you may get an error because your .localhost domain doesn't match the host defined in the server certificate. With this flag, host header is changed to match the target URL.

ENOSPC and EACCES errors

If you're seeing one of these errors in ~/.hotel/daemon.log, this usually means that there's some permissions issues. hotel daemon should be started without sudo and ~/.hotel should belong to $USER.

# to fix permissions
sudo chown -R $USER: $HOME/.hotel

See also, https://docs.npmjs.com/getting-started/fixing-npm-permissions

Configuring a network proxy IP

If you're behind a corporate proxy, replace "proxy" with your network proxy IP in ~/.hotel/conf.json. For example:

{
  "proxy": "1.2.3.4:5000"
}

License

MIT

Patreon - Supporters ✨

hotel (typicode/hotel)

Searching Database…

10K ·GitHub
Hotel
What is this?Hotel is a simple process manager for developers: you start your apps from the browser and reach them through local .localhost domains with HTTPS set up automatically.
Why use this instead of just running apps on localhost ports?You get clean .localhost domains with wildcard subdomains, automatic HTTPS via a self-signed certificate, lazy starts and fixed or random ports — no port 80, /etc/hosts or sudo hassles.
How do I get it running?Install Node first (nvm install stable or brew install node), then install hotel globally with npm. You manage everything from the web dashboard at localhost:2000 or hotel.localhost.
Does my app need to be set up in a special way to work with it?Yes: servers must listen on the PORT environment variable. To use .localhost domains your network or browser must point at hotel's proxy auto-config file; otherwise fall back to the localhost:2000 catalog.
Which operating systems does it run on?macOS, Linux and Windows are all supported, and it is built to coexist with servers like Apache and Nginx already running on the machine.
Which stacks can it run — only Node apps?Any server that can listen on a PORT env var. The README lists Node (Express, Webpack), PHP (Laravel, Symfony), Ruby (Rails, Sinatra, Jekyll), Python (Django), Docker, Go, Apache and Nginx as examples.
Can a local domain point to a remote server instead of a local one?Yes, hotel doubles as a proxy: you can map local domains to remote servers, with options for adding X-Forwarded headers and proxying to https targets whose certificates don't match.
What happened to .dev domains?From v0.8.0 the default local domain is .localhost. When upgrading you remove the 'tld': 'dev' entry from ~/.hotel/conf.json, run hotel stop && hotel start and refresh your network settings.
Is there a menu bar or tray app for it?The community built several: Hotelier for Mac and Windows tray, Hotel Clerk and HotelX for the macOS menu bar, the alfred-hotel workflow and a Hotel Manager Gnome Shell extension.
What are similar projects?http-server, portless, localtunnel, webpack-dashboard, bower, volta, knip, mkcert
Which topics is it in?localhost, process-manager, local, https, front-end, devtools, proxy, command-line-tool, free, npm, frontend, tool
Creator
typicode
Size
3.1 MB
Stars
10K
Updated
CommitOct 23Releasev1.0.0Oct 23
Age
11y
Commits · 90 Days