Horizon.NginxConfig (horizon v0.3.4)

View Source

This module generates an Nginx configuration file using a templating system. Allows for template overrides in the current project. The configuration is based on Horizon.Project and Horizon.Server.

Customizing the Nginx configuration template

To customize your nginx.conf, copy the template from the Horizon package to your project:

$ mkdir -p priv/horizon/templates
$ cp deps/horizon/priv/templates/nginx/nginx.conf.eex priv/horizon/templates/nginx.conf.eex

You can also customize individual blocks of the configuration file:

$ cp deps/horizon/priv/templates/nginx/_upstream.eex priv/horizon/templates/_upstream.eex
$ cp deps/horizon/priv/templates/nginx/_server_http.eex priv/horizon/templates/_server_http.eex
$ cp deps/horizon/priv/templates/nginx/_server_https.eex priv/horizon/templates/_server_https.eex

Nginx Header Options 

* `:client_max_body_size` - Maximum allowed size of the client request body (default: "6M")
* `:sendfile` - Enable or disable sendfile usage (default: true)
* `:keepalive_timeout` - Timeout during which a keep-alive client connection will stay open (default: 65)
* `:gzip` - Enable or disable gzip compression (default: true)
* `:access_log` - Enable or disable access logging (default: true)
* `:access_log_path` - Path to the access log file (default: "/var/log/nginx/access.log")
* `:worker_connections` - Maximum number of simultaneous connections that can be opened by a worker process (default: 1024)

Examples 

iex> project = %Horizon.Project{
...>   name: "example_project",
...>   server_names: ["example.com", "www.example.com"],
...>   letsencrypt_domain: "mydomain.com",
...>   acme_challenge_path: "/apps/challenge/mydomain.com",
...>   http_only: false,
...>   servers: [
...>     %Horizon.Server{internal_ip: "10.0.0.1", port: 4000},
...>     %Horizon.Server{internal_ip: "10.0.0.2", port: 4001}
...>   ]
...> }
iex> Horizon.NginxConfig.generate([project])

With custom options:

iex> Horizon.NginxConfig.generate([project],
...>   client_max_body_size: "20M",
...>   worker_connections: 2048,
...>   gzip: false
...> )
user_host = "username@host-address"
remote_path = "/usr/local/etc/nginx/nginx.conf"

projects = [
  %Horizon.Project{
    name: "project-name",
    server_names: ["my.server.com"],
    http_only: true,
    servers: [
      %Horizon.Server{internal_ip: "127.0.0.1", port: 4000},
      %Horizon.Server{internal_ip: "192.168.100.100", port: 4000}
    ]
  }
]

config_output = Horizon.NginxConfig.send(projects)

Summary

Types

nginx_options()

Functions

cert_key_path(project)

Returns the path for the certificate

cert_path(project)

Returns the path for the certificate

generate(projects, opts \\ [])

Generates an Nginx configuration file as a string based on the provided projects and options.

render_partial(partial_name, assigns)
send(projects, user_host, opts \\ [])

Sends the Nginx configuration to a remote host and reloads the Nginx service.

Types

nginx_options()

@type nginx_options() :: [
  client_max_body_size: String.t(),
  sendfile: boolean(),
  keepalive_timeout: integer(),
  gzip: boolean(),
  access_log: boolean(),
  access_log_path: String.t(),
  worker_connections: integer()
]

Functions

cert_key_path(project)

@spec cert_key_path(Horizon.Project.t()) :: String.t()

Returns the path for the certificate

Examples 

iex> cert_key_path(%Horizon.Project{
...>   certificate: :self,
...>   cert_key_path: "/path/to/cert_key.pem"
...> })
"/path/to/cert_key.pem"

iex> cert_key_path(%Horizon.Project{certificate: :letsencrypt, domain: "example.com"})
"/user/local/etc/letsencrypt/live/example.com/privkey.pem"

cert_path(project)

@spec cert_path(Horizon.Project.t()) :: String.t()

Returns the path for the certificate

Examples 

iex> cert_path(%Horizon.Project{certificate: :self, cert_path: "/path/to/cert.pem"})
"/path/to/cert.pem"

iex> cert_path(%Horizon.Project{certificate: :letsencrypt, domain: "example.com"})
"/user/local/etc/letsencrypt/live/example.com/fullchain.pem"

generate(projects, opts \\ [])

@spec generate([Horizon.Project.t()], nginx_options()) :: String.t()

Generates an Nginx configuration file as a string based on the provided projects and options.

This function takes a list of Horizon.Project.t() structures and optional Nginx configuration options, merges the provided options with defaults, and generates a formatted Nginx configuration string using the appropriate template.

Parameters

  • projects - A list of Horizon.Project.t() structures defining the applications to be configured
  • opts - A keyword list of Nginx configuration options (see "Nginx Header Options" in module documentation)

Returns

  • A formatted Nginx configuration as a string
  • An empty string if the projects list is empty

Examples 

iex> projects = [
...>   %Horizon.Project{
...>     name: "my_app",
...>     server_names: ["example.com"],
...>     servers: [%Horizon.Server{internal_ip: "127.0.0.1", port: 4000}]
...>   }
...> ]
iex> Horizon.NginxConfig.generate(projects)

# With custom options
iex> Horizon.NginxConfig.generate(projects, client_max_body_size: "20M", gzip: false)

render_partial(partial_name, assigns)

@spec render_partial(
  atom(),
  keyword()
) :: String.t()

send(projects, user_host, opts \\ [])

@spec send([Horizon.Project.t()], String.t(), keyword()) ::
  {:ok, any()} | {:error, non_neg_integer(), any()}

Sends the Nginx configuration to a remote host and reloads the Nginx service.

Options

  • :nginxconf_path - Path to nginx.conf on the remote host (default: "/usr/local/etc/nginx/nginx.conf")
  • :action - Action to take on the remote host after updating config (:reload or :restart) (default: :reload)
  • :nginx - Nginx configuration options (see generate/2 for available options)

Examples 

iex> user_host = "me@myhost"
...> projects = [%Horizon.Project{name: "my project", ...}]
...> NginxConfig.send(projects, user_host)

# With custom nginx.conf path and restart action
iex> NginxConfig.send(projects, user_host,
...>   nginxconf_path: "/usr/nginx/nginx.conf",
...>   action: :restart
...> )

# With custom nginx options
iex> NginxConfig.send(projects, user_host,
...>   nginx: [
...>     client_max_body_size: "20M",
...>     worker_connections: 2048
...>   ]
...> )