hostel

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

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

hostel works great on any OS (macOS, Linux, Windows) and with all servers ❤️

Node (Express, Webpack)
PHP (Laravel, Symfony)
Ruby (Rails, Sinatra, Jekyll)
Python (Django)
Docker
Go
Apache, Nginx
...

To all the amazing people who have answered the hostel 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:

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

Support

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

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

Video

Starting apps with hostel - Spacedojo Code Kata by Josh Owens

Features

Local domains - http://project.localhost
HTTPS via local self-signed SSL certificate - https://project.localhost
Wildcard subdomains - http://*.project.localhost
Works everywhere - macOS, Linux and Windows
Works with any server - Node, Ruby, PHP, ...
Proxy - Map local domains to remote servers
System-friendly - No messing with port 80, /etc/hosts, sudo or additional software
Fallback URL - http://localhost:2000/project
Servers are only started when you access them
Plays nice with other servers (Apache, Nginx, ...)
Random or fixed ports

Install

npm install -g hostel && hostel start

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

https://github.com/creationix/nvm nvm install stable
https://brew.sh brew install node

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 hostel'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 hostel
~/projects/one$ hostel add 'npm start'
# Or start your server in the terminal as usual and get a temporary local domain
~/projects/two$ hostel run 'npm start'

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

Alternatively you can directly go to

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

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

Popular servers examples

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

hostel add 'ember server'                               # Ember
hostel add 'jekyll serve --port $PORT'                  # Jekyll
hostel add 'rails server -p $PORT -b 127.0.0.1'         # Rails
hostel add 'python -m SimpleHTTPServer $PORT'           # static file server (Python)
hostel add 'php -S 127.0.0.1:$PORT'                     # PHP
hostel add 'docker-compose up'                          # docker-compose
hostel 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

~$ hostel add http://192.168.1.12:1337 --name aliased-address
~$ hostel 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

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

# Examples

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

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

# Other commands

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

To get help

hostel --help
hostel --help <cmd>

Port

For hostel 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)

hostel add 'cmd -p $PORT'  # OS X, Linux
hostel 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 hostel related files in ~/.hostel :

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

By default, hostel 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,

  // Change to false to prevent hostel from starting itself up automatically on login
  "autostart": true
}

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

Third-party tools

Hotelier Hotelier (Mac & Windows Tray App)
hostel Clerk OS X menubar
HotelX Another OS X menubar (only 1.6MB)
alfred-hostel Alfred 3 workflow
hostel Manager Gnome Shell extension

FAQ

Setting a fixed port

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

Adding `X-Forwarded-*` headers to requests

hostel add --xfwd 'server-cmd'

Setting `HTTP_PROXY` env

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

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

Proxying requests to a remote `https` server

hostel 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 ~/.hostel/daemon.log, this usually means that there's some permissions issues. hostel daemon should be started without sudo and ~/.hostel should belong to $USER.

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

Configuring a network proxy IP

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

{
  "proxy": "1.2.3.4:5000"
}

License

MIT

Patreon - Supporters ✨

hwknsj/hostel