Skip to content

Latest commit

 

History

History
72 lines (48 loc) · 3.02 KB

README.markdown

File metadata and controls

72 lines (48 loc) · 3.02 KB
Raw

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.