Proxy

Proxy is an HTTP reverse proxy. It was written to be the backend for the Recurse Center custom subdomain service, which lets RC alumni register a recurse.com subdomain for their webapp or website.

Proxy handles requests for subdomains of a single domain. It periodically loads a JSON endpoint continaing mappings from subdomain to URL, and then proxies requests to each subdomain to the appropriate URL.

Proxy can be run almost anywhere, including Heroku.

For simplicity, Proxy handles HTTP requests only. You should deploy it behind a TLS-terminating load balancer on a secure network like a VPC. There is an included certs.sh script that can provision a wildcard certificate from Let's Encrypt and install it on Heroku. See the source of certs.sh for detailed setup instructions.

Dependencies

• Go
• curl, jq, openssl, awk, sed, and bash (for certs.sh)

Setup

Proxy gets its configuration from environmental variables:

Variable	Example	Description	Required	Default
DOMAIN	example.com	The domain to handle requests for.	Yes
ENDPOINT	https://www.example.com/domains.json	The URL of the JSON endpoint containing mappings from subdomain to URL.	Yes
PORT	8080	The port that Proxy should listen on.	No	80
FORCE_TLS	true	If true, Proxy will redirect all HTTP requests to HTTPS.	No	false
READ_TIMEOUT	10	Maximum number of seconds Proxy waits to read a request from a client.	No	5
WRITE_TIMEOUT	15	Maximum number of seconds Proxy will spend writing a response to the client before timing out. This includes time spend proxying the request.	No	10
SHUTDOWN_TIMEOUT	20	Maximum number of seconds Proxy will wait for in-flight requests to complete while shutting down. After this duration has expired, Proxy will kill all requests that are still running.	No	10
REFRESH_INTERVAL	10	Proxy fetches ENDPOINT every REFRESH_INTERVAL seconds.	No	5

Running

Proxy runs in the foreground and logs to STDOUT. All error messages contain the string "error:". When it receives a SIGINT or a SIGTERM, Proxy shuts down.

If present, Proxy will read its configuration out of a .env file. Here's a starting point for development:

DOMAIN=example.com
ENDPOINT=https://www.example.com/domains.json

To start Proxy locally, run:

$ go run .

You can use curl to make a request to a mapped subdomain:

$ curl --header 'Host: foo.example.com' http://localhost

Subdomain mappings endpoint

In order to use Proxy, you need a publicly accessible HTTP endpoint that returns a set of mappings from subdomain to URL. The endpoint must return JSON data in the following format:

[
  ["subdomain1", "https://www.example.com/foo"],
  ["subdomain2", "https://www.example.net"],
  ["subdomain3", "http://www.example.org"]
]

Copyright

Copyright Recurse Center.

License

This project is licensed under the terms of the BSD 2-clause "Simplified" license. See LICENSE.md for full terms.