Skip to content

Latest commit

 

History

History
280 lines (194 loc) · 7.74 KB

README.md

File metadata and controls

280 lines (194 loc) · 7.74 KB
Raw

chalet

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

Note: This is a maintained fork of hotel, which seems to have grown stale.

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

Chalet 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
  • ...

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 ~/.chalet/conf.json file
  2. Run chalet stop && chalet start
  3. Refresh your network settings

Features

  • Local domains - http://project.test
  • HTTPS via local self-signed SSL certificate - https://project.test
  • Wildcard subdomains - http://*.project.test
  • 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 chalet && chalet start

Chalet 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 .test domains, you need to configure your network or browser to use chalet'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 chalet
~/projects/one$ chalet add 'npm start'
# Or start your server in the terminal as usual and get a temporary local domain
~/projects/two$ chalet run 'npm start'

Visit localhost:2000 or http(s)://chalet.test.

Alternatively you can directly go to

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

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

Popular servers examples

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

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

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

See a Docker example here..

Proxy requests to remote servers

Add your remote servers

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

You can now access them using

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

CLI usage and options

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

# Examples

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

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

# Other commands

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

To get help

chalet --help
chalet --help <cmd>

Port

For chalet 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);
chalet add 'cmd -p $PORT'  # OS X, Linux
chalet add "cmd -p %PORT%" # Windows

Fallback URL

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

Configurations, logs and self-signed SSL certificate

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

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

By default, chalet 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 .test
  "tld": 'test',

  // 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 ~/.chalet/conf.json and run chalet stop && chalet start

Third-party tools

FAQ

Problem with self signed certificates

You will want to delete your existing certificates and restart chalet:

chalet stop
rm ~/.chalet/cert.pem ~/.chalet/key.pem
chalet start

Setting a fixed port

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

Adding X-Forwarded-* headers to requests

chalet add --xfwd 'server-cmd'

Setting HTTP_PROXY env

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

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

Proxying requests to a remote https server

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

When proxying to a https server, you may get an error because your .test 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 ~/.chalet/daemon.log, this usually means that there's some permissions issues. chalet daemon should be started without sudo and ~/.chalet should belong to $USER.

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

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 ~/.chalet/conf.json. For example:

{
  "proxy": "1.2.3.4:5000"
}

License

MIT