MasterProxy (master_proxy v0.1.4)

Route requests to other Phoenix Endpoints or Plugs with WebSocket support.

This library is useful for Gigalixir, Render, Heroku or other deployments where only one web port is exposed.

Installation

Add MasterProxy to your list of dependencies in mix.exs.

Note: if you are running an umbrella project, adding MasterProxy as a dependency at the root mix.exs won't work. Instead, either add it to one of your child apps or create a new child app solely for the proxy.

def deps do
  [
    {:master_proxy, "~> 0.1"},
  ]
end

Configure rules for routing requests by adding something like this in your configuration (i.e. config/config.exs).

config :master_proxy, 
  # any Cowboy options are allowed
  http: [:inet6, port: 4080],
  https: [:inet6, port: 4443],
  backends: [
    %{
      domain: "my-cool-app.com",
      phoenix_endpoint: MyCoolAppWeb.Endpoint
    },
    %{
      domain: "members.my-cool-app.com",
      phoenix_endpoint: MyAppMembersWeb.Endpoint
    },
    %{
      verb: ~r/get/i,
      path: ~r{^/master-proxy-plug-test$},
      plug: MasterProxy.Plug.Test,
      opts: [1, 2, 3]
    }
  ]

See Configuration Examples for more.

To avoid the platform routing requests directly to your Web apps' Endpoints, and thus bypassing the Endpoint on which MasterProxy is running, you can configure your other Web apps' Endpoints to not start a server in your production config.

# An Endpoint on which MasterProxy is not running
config :my_app_web, MyAppWeb.Endpoint,
  # ...
  server: false

Available Options

  • :http - the configuration for the HTTP server. It accepts all options as defined by Plug.Cowboy.
  • :https - the configuration for the HTTPS server. It accepts all options as defined by Plug.Cowboy.
  • :server - true by default. If you are running application with mix phx.server, this option is ignored, and the server will always be started.
  • :backends - the rule for routing requests. See Configuration Examples for more.
    • :verb
    • :host
    • :path
    • :phoenix_endpoint / :plug
    • :opts - only for :plug
  • :log_requests - true by default. Log the requests or not.

Configuration Examples

Route requests to apps based on hostname

config :master_proxy,
  http: [port: 80],
  backends: [
    %{
      host: ~r{^app-name\.gigalixirapp\.com$},
      phoenix_endpoint: MyAppWeb.Endpoint
    },
    %{
      host: ~r{^www\.example\.com$},
      phoenix_endpoint: MyAppWeb.Endpoint
    },
    %{
      host: ~r{^api\.example\.com$},
      phoenix_endpoint: MyAppApiWeb.Endpoint
    },
    %{
      host: ~r{^members\.example\.com$},
      phoenix_endpoint: MyAppMembersWeb.Endpoint
    }
  ]