Defines a Phoenix endpoint.

The endpoint is the boundary where all requests to your web application start. It is also the interface your application provides to the underlying web servers.

Overall, an endpoint has three responsibilities:

• to provide a wrapper for starting and stopping the endpoint as part of a supervision tree

• to define an initial plug pipeline for requests to pass through

• to host web specific configuration for your application

Endpoints

An endpoint is simply a module defined with the help of Phoenix.Endpoint. If you have used the mix phx.new generator, an endpoint was automatically generated as part of your application:

defmodule YourAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :your_app

  # plug ...
  # plug ...

  plug YourApp.Router
end

Endpoints must be explicitly started as part of your application supervision tree. Endpoints are added by default to the supervision tree in generated applications. Endpoints can be added to the supervision tree as follows:

children = [
  YourAppWeb.Endpoint
]

Endpoint configuration

All endpoints are configured in your application environment. For example:

config :your_app, YourAppWeb.Endpoint,
  secret_key_base: "kjoy3o1zeidquwy1398juxzldjlksahdk3"

Endpoint configuration is split into two categories. Compile-time configuration means the configuration is read during compilation and changing it at runtime has no effect. The compile-time configuration is mostly related to error handling.

Runtime configuration, instead, is accessed during or after your application is started and can be read through the config/2 function:

YourAppWeb.Endpoint.config(:port)
YourAppWeb.Endpoint.config(:some_config, :default_value)

Dynamic configuration

For dynamically configuring the endpoint, such as loading data from environment variables or configuration files, Phoenix invokes the c:init/2 callback on the endpoint, passing the atom :supervisor as the first argument and the endpoint configuration as second.

All of Phoenix configuration, except the Compile-time configuration below can be set dynamically from the c:init/2 callback.

Compile-time configuration

• :code_reloader - when true, enables code reloading functionality. For the list of code reloader configuration options see Phoenix.CodeReloader.reload/1. Keep in mind code reloading is based on the file-system, therefore it is not possible to run two instances of the same app at the same time with code reloading in development, as they will race each other and only one will effectively recompile the files. In such cases, tweak your config files so code reloading is enabled in only one of the apps or set the MIX_BUILD environment variable to give them distinct build directories

• :debug_errors - when true, uses Plug.Debugger functionality for debugging failures in the application. Recommended to be set to true only in development as it allows listing of the application source code during debugging. Defaults to false

• :force_ssl - ensures no data is ever sent via HTTP, always redirecting to HTTPS. It expects a list of options which are forwarded to Plug.SSL. By default it sets the "strict-transport-security" header in HTTPS requests, forcing browsers to always use HTTPS. If an unsafe request (HTTP) is sent, it redirects to the HTTPS version using the :host specified in the :url configuration. To dynamically redirect to the host of the current request, set :host in the :force_ssl configuration to nil

Runtime configuration

• :adapter - which webserver adapter to use for serving web requests. See the "Adapter configuration" section below

• :cache_static_manifest - a path to a json manifest file that contains static files and their digested version. This is typically set to "priv/static/cache_manifest.json" which is the file automatically generated by mix phx.digest. It can be either: a string containing a file system path or a tuple containing the application name and the path within that application.

• :cache_static_manifest_latest - a map of the static files pointing to their digest version. This is automatically loaded from cache_static_manifest on boot. However, if you have your own static handling mechanism, you may want to set this value explicitly. This is used by projects such as LiveView to detect if the client is running on the latest version of all assets.

• :cache_manifest_skip_vsn - when true, skips the appended query string "?vsn=d" when generating paths to static assets. This query string is used by Plug.Static to set long expiry dates, therefore, you should set this option to true only if you are not using Plug.Static to serve assets, for example, if you are using a CDN. If you are setting this option, you should also consider passing --no-vsn to mix phx.digest. Defaults to false.

• :check_origin - configure the default :check_origin setting for transports. See socket/3 for options. Defaults to true.

• :secret_key_base - a secret key used as a base to generate secrets for encrypting and signing data. For example, cookies and tokens are signed by default, but they may also be encrypted if desired. Defaults to nil as it must be set per application

• :server - when true, starts the web server when the endpoint supervision tree starts. Defaults to false. The mix phx.server task automatically sets this to true

• :url - configuration for generating URLs throughout the app. Accepts the :host, :scheme, :path and :port options. All keys except :path can be changed at runtime. Defaults to:

  [host: "localhost", path: "/"]

  The :port option requires either an integer or string. The :host option requires a string.

  The :scheme option accepts "http" and "https" values. Default value is inferred from top level :http or :https option. It is useful when hosting Phoenix behind a load balancer or reverse proxy and terminating SSL there.

  The :path option can be used to override root path. Useful when hosting Phoenix behind a reverse proxy with URL rewrite rules

• :static_url - configuration for generating URLs for static files. It will fallback to url if no option is provided. Accepts the same options as url

• :watchers - a set of watchers to run alongside your server. It expects a list of tuples containing the executable and its arguments. Watchers are guaranteed to run in the application directory, but only when the server is enabled (unless :force_watchers configuration is set to true). For example, the watcher below will run the "watch" mode of the webpack build tool when the server starts. You can configure it to whatever build tool or command you want:

  [
    node: [
      "node_modules/webpack/bin/webpack.js",
      "--mode",
      "development",
      "--watch",
      "--watch-options-stdin"
    ]
  ]

  The :cd and :env options can be given at the end of the list to customize the watcher:

  [node: [..., cd: "assets", env: [{"TAILWIND_MODE", "watch"}]]]

  A watcher can also be a module-function-args tuple that will be invoked accordingly:

  [another: {Mod, :fun, [arg1, arg2]}]

• :force_watchers - when true, forces your watchers to start even when the :server option is set to false.

• :live_reload - configuration for the live reload option. Configuration requires a :patterns option which should be a list of file patterns to watch. When these files change, it will trigger a reload.

  live_reload: [
    url: "ws://localhost:4000",
    patterns: [
      ~r"priv/static/(?!uploads/).*(js|css|png|jpeg|jpg|gif|svg)$",
      ~r"lib/app_web/(live|views)/.*(ex)$",
      ~r"lib/app_web/templates/.*(eex)$"
    ]
  ]

• :pubsub_server - the name of the pubsub server to use in channels and via the Endpoint broadcast functions. The PubSub server is typically started in your supervision tree.

• :render_errors - responsible for rendering templates whenever there is a failure in the application. For example, if the application crashes with a 500 error during a HTML request, render("500.html", assigns) will be called in the view given to :render_errors. A :formats list can be provided to specify a module per format to handle error rendering. Example:

  [formats: [html: MyApp.ErrorHTML], layout: false, log: :debug]

• :log_access_url - log the access url once the server boots

Note that you can also store your own configurations in the Phoenix.Endpoint. For example, Phoenix LiveView expects its own configuration under the :live_view key. In such cases, you should consult the documentation of the respective projects.

Adapter configuration

Phoenix allows you to choose which webserver adapter to use. Newly generated applications created via the phx.new Mix task use the Bandit webserver via the Bandit.PhoenixAdapter adapter. If not otherwise specified via the adapter option Phoenix will fall back to the Phoenix.Endpoint.Cowboy2Adapter for backwards compatibility with applications generated prior to Phoenix 1.7.8.

Both adapters can be configured in a similar manner using the following two top-level options:

• :http - the configuration for the HTTP server. It accepts all options as defined by either Bandit or Plug.Cowboy depending on your choice of adapter. Defaults to false

• :https - the configuration for the HTTPS server. It accepts all options as defined by either Bandit or Plug.Cowboy depending on your choice of adapter. Defaults to false

In addition, the connection draining can be configured for the Cowboy webserver via the following top-level option (this is not required for Bandit as it has connection draining built-in):

• :drainer - a drainer process waits for any on-going request to finish during application shutdown. It accepts the :shutdown and :check_interval options as defined by Plug.Cowboy.Drainer. Note the draining does not terminate any existing connection, it simply waits for them to finish. Socket connections run their own drainer before this one is invoked. That's because sockets are stateful and can be gracefully notified, which allows us to stagger them over a longer period of time. See the documentation for socket/3 for more information

Endpoint API

In the previous section, we have used the config/2 function that is automatically generated in your endpoint. Here's a list of all the functions that are automatically defined in your endpoint:

• for handling paths and URLs: struct_url/0, url/0, path/1, static_url/0,static_path/1, and static_integrity/1

• for gathering runtime information about the address and port the endpoint is running on: server_info/1

• for broadcasting to channels: broadcast/3, broadcast!/3, broadcast_from/4, broadcast_from!/4, local_broadcast/3, and local_broadcast_from/4

• for configuration: start_link/1, config/2, and config_change/2

• as required by the Plug behaviour: Plug.init/1 and Plug.call/2