Candy is a zero-config reverse proxy server.
It makes proxying applications with local top-leveled domains as frictionless as possible.
There is no messing around with /etc/hosts, Dnsmasq, or Nginx.
A few simple conventions eliminate the need for tedious configuration.
Candy runs as your user on unprivileged ports, and includes an HTTP, an HTTPS, and a DNS server.
It also sets up a system hook so that all DNS queries for a local top-level domain (.test) resolve to your local machine.
To route web traffic to an app, just create a file in the ~/.candy directory.
Assuming you are developing an app that runs on http://127.0.0.1:8080, and you would like to access it at http://myapp.test, setting it up is as easy as:
$ echo "8080" > ~/.candy/myapp
The name of the file (myapp) determines the hostname (myapp.test) to access the application that it points to (127.0.0.1:8080).
Both HTTP and HTTPS request is supported out of the box:
$ curl http://myapp.test
$ curl https://myapp.test
brew install owenthereal/candy/candy
After installing the candy binary, you also need to create a DNS resolver config in /etc/resolver/CONFIG.
Creating the /etc/resolver directory and the config file require superuser privileges. You can execute with a one-liner:
sudo candy setup
Alternatively, you can manually execute the followings:
sudo mkdir -p /etc/resolver
cat<<EOF | sudo tee /etc/resolver/candy-test > /dev/null
domain test
nameserver 127.0.0.1
port 25353
search_order 1
timeout 5
EOF
go install github.com/owenthereal/candy/cmd/candy@latest
After installing the candy binary, you also need to create a network name resolution config in /usr/lib/systemd/resolved.conf.d/CONFIG.
Creating the /usr/lib/systemd/resolved.conf.d directory and the config file require superuser privileges. You can execute with a one-liner:
sudo candy setup
Alternatively, you can manually execute the followings:
sudo mkdir -p /usr/lib/systemd/resolved.conf.d
cat<<EOF | sudo tee /usr/lib/systemd/resolved.conf.d/01-candy.conf > /dev/null
[Resolve]
DNS=127.0.0.1:25353
Domains=test
EOF
sudo systemctl restart systemd-resolved # Restart systemd-resolved
To have Launchd start Candy and restart at login:
brew services start candy
To restart Candy, run:
brew services restart candy
To stop Candy, run:
brew services stop candy
Or, if you don't want/need a background service, you can just run:
candy run
TODO
Candy's port/IP proxying feature lets you route all web traffic on a particular hostname to another port or IP address.
To use it, create a file in ~/.candy with the the destination port number or IP address as its contents:
echo "8080" > ~/.candy/app1
curl https://app1.test
echo "1.2.3.4:8080" > ~/.candy/app2
curl https://app2.test
Candy provides good defaults that most people will never need to configure it.
However, if you need to adjust a setting or two, you can create a file to override the defaults in ~/.candyconfig.
See this file for a list of settings that you can change.
For example, you may want to have multiple top-leveled domains besides *.test:
{
"domain": ["test","mydomain"]
}Changing the domain setting requires resetting DNS resolvers in /etc/resolver.
Rerun the setup step and make sure all resolver config files are matching in /etc/resolver.
After changing a setting in ~/.candyconfig, you will also need to restart Candy for the change to take effect: