Proxrox can be started with a config from the file system. This file can be shared in a team, e.g. placed in a repository, to ensure that every team member is using the same configuration. Proxrox supports two config file formats:
- JSON (recommended file name is
.proxrox.json) - YAML (recommended file name is
.proxrox.yaml)
All configuration options in this config file will take precedence over proxrox's defaults and the CLI arguments. If you need to adapt options to developers' machines, then you shouldn't put these options into the config file as these values would otherwise take precedence.
A configuration file in the YAML format (in .proxrox.yaml) would look like
this. The following sections explain the supported options.
# you can use YAML comments
root: './web'
ssi: true
proxy:
- type: 'http'
from: '/'
to: 'http://127.0.0.1:8080'
This option is used to populate nginx's server_name directive. Most users
will not make use of this option and can use the default value.
- Type:
string - Default:
'example' - Nginx docs:
The port to bind to.
- Type:
number - Default:
4000 - Nginx docs:
Defines the path to the directory which should be served via HTTP. You can use absolute paths or relative paths that are resolved against the location of the config file.
Use false to deactivate serving of static assets. This is only useful if you
are using proxrox to combine multiple services via proxies and don't care
about serving static assets from the file system.
- Type:
stringorboolean(onlyfalseis supported) - Default: The current working directory
- Nginx docs:
Defines the path to the temporary directory used to store the generated nginx
configuration, TLS certificates and more. By default, proxrox will delete and
re-create this directory on every execution. Explicitly configure a tmpDir
to run multiple proxrox instances at the same time.
- Type:
string - Default:
/tmp/proxrox
Defines the path to the nginx logs.
- Type:
string - Default:
'logs/'(relative totmpDir)
Whether or not to generated a directory listing for requests to directories.
- Type:
boolean - Default:
true - Nginx docs:
Whether or not to use gzip compression for responses (if possible).
- Type:
boolean - Default:
true - Nginx docs:
Proxy requests to services via nginx. This is very useful to combine services under a single origin. Proxies can be used in two ways with proxrox.
- When serving static assets, a proxy defined for url
/will act as a fall back for all incoming requests. This is done via a named location which is referenced in nginx'stry_filesdirective. - When not serving static assets, all proxies are turned into nginx location blocks, i.e. for a specific location an nginx proxy is used.
Examples:
The following config is used to serve static assets and to provide a fallback for incoming requests.
root: '/var/www'
proxy:
- type: 'http'
from: '/'
to: 'http://api.example.com'
Multiple proxies can be used which will be turned into additional nginx location blocks:
root: '/var/www'
proxy:
- type: 'http'
from: '/'
to: 'http://api.example.com'
- type: 'websocket'
from: '/data'
to: 'http://data.example.com'
For more example and resulting nginx configurations take a look at the tests.
- Type:
Array<{type: 'http' | 'websocket' | 'eventsource', from: string, to: string, additionalDirectives?: string}> - Default:
[] - Nginx docs:
When set, reading a response from the proxied server will timeout at this.
- Type:
string - Default: 60s
- Nginx docs:
When set, proxrox will generate a self-signed SSL certificate. Once started,
nginx will only accept https connections under the configured port.
- Type:
boolean - Default:
false - Nginx docs:
The absolute path of an SSL certificate file to use when running with tls:true.
When set, proxrox will never generate the SSL certificate,
otherwise regenerate the SSL certificate every time.
If this flag is set, tlsCertificateKeyFile must also be set.
- Type:
string
The absolute path of an SSL certificate file to use when running with tls:true.
When set, proxrox will never generate the SSL certificate,
otherwise regenerate the SSL certificate every time.
If this flag is set, tlsCertificateFile must also be set.
- Type:
string
Proxrox can enable HTTP 2 protocol support. Activating HTTP 2 does not mean that tls is implied. Nginx can support HTTP 2 without TLS. This is only available when used with at least nginx 1.9.5.
- Type:
boolean - Default:
false - Nginx docs:
Server-side includes are very useful and can be activated with the ssi flag.
- Type:
boolean - Default:
false - Nginx docs:
Make basic Nginx status information available under the URI /nginx_status
- Type:
boolean - Default:
false - Nginx docs:
Whether to render out the standard server section configured via the remaining prorox configuration options. Useful when only desiring to render out an nginx config with what is defined in extraSite.
- Type:
boolean - Default:
true
Absolute path to an nginx configuration file that should be included within the generated nginx configuration file. Useful to render out an additional server/site section within the nginx configuration.
- Type:
string - Nginx docs: