Options / Config
This section covers all user-configurable options for faucet.
Global Options
These options can be used with both the start
and router
subcommands.
Host
- CLI:
--host
- Environment:
FAUCET_HOST
- Default:
127.0.0.1:3838
The host and port to bind the faucet server to. If running in a container, this should
be set to 0.0.0.0:3838
to allow external access.
IP From (How to determine the client IP)
- CLI:
--ip-from
or-i
- Environment:
FAUCET_IP_FROM
- Default:
client
- Possible values:
client
x-forwarded-for
x-real-ip
How to determine the client IP. This is used to determine the IP for the IP Hash
strategy and for logging of HTTP requests. If you are running faucet directly to end
users, you should use client
. If you are running faucet behind a reverse proxy like
nginx, you should use x-forwarded-for
or x-real-ip
.
Note: If you are running faucet behind a reverse proxy, be sure to set the
X-Forwarded-For
orX-Real-IP
header correctly in your reverse proxy\'s configuration.
Rscript (Define a custom Rscript
binary/executable)
- CLI:
--rscript
or-r
- Environment:
FAUCET_RSCRIPT
- Default:
Rscript
The Rscript
binary/executable to use. This is useful if you need to have
multiple versions of R installed on your system. This should be the full path
to the Rscript
binary/executable or an alias that is available in your
$PATH
. This is also useful in platforms like Windows where the Rscript
binary/executable may not be available in the $PATH
.
Quarto (Define a custom quarto
binary/executable)
- CLI:
--quarto
or-q
- Environment:
FAUCET_QUARTO
- Default:
quarto
The quarto
binary/executable to use. This is useful if you have
multiple versions of Quarto installed or if it\'s not in your $PATH
.
Log File (Redirect logging to a file)
- CLI:
--log-file
or-l
- Environment:
FAUCET_LOG_FILE
- Default:
None
If you set this variable it will disable colors on stderr
and save all output
to the specified path. This will append, not overwrite previously existing files.
Max Log File Size
- CLI:
--max-log-file-size
or-m
- Environment:
FAUCET_MAX_LOG_FILE_SIZE
- Default:
None
The maximum size of the log file before rotation (e.g., 10M, 1GB).
Requires log-file
to be set.
Logging Level
- Environment:
FAUCET_LOG
- Default:
INFO
- Possible values:
ERROR
WARN
INFO
DEBUG
TRACE
The logging level to use. This environment variable sets the global logging verbosity.
Refer to the logging section for more information.
Note: While this environment variable is functional, newer applications might prefer
more granular control via dedicated logger configuration files or library-specific
settings if available. The CLI options --log-file
and --max-log-file-size
provide direct control over file-based logging.
Shutdown
- CLI:
--shutdown
- Environment:
FAUCET_SHUTDOWN
- Default:
immediate
- Possible values:
immediate
graceful
The strategy used for shutting down faucet. immediate
kills every
active connection and shutdown the process. graceful
waits
for all connections to close before shutting down.
Telemetry: PostgreSQL Connection String
- CLI:
--pg-con-string
- Environment:
FAUCET_TELEMETRY_POSTGRES_STRING
- Default:
None
Connection string to a PostgreSQL database for saving HTTP events. If provided, faucet will attempt to log HTTP events to this database.
Telemetry: Namespace
- CLI:
--telemetry-namespace
- Environment:
FAUCET_TELEMETRY_NAMESPACE
- Default:
faucet
Namespace under which HTTP events are saved in PostgreSQL.
Telemetry: Version
- CLI:
--telemetry-version
- Environment:
FAUCET_TELEMETRY_VERSION
- Default:
None
Represents the source code version of the service being run. This is useful for filtering telemetry data.
start
Subcommand Options
These options are specific to the start
subcommand, used for running a standard faucet server.
Workers
- CLI:
--workers
or-w
- Environment:
FAUCET_WORKERS
- Default: The number of CPUs available to the process
The number of worker processes to spawn. On a CPU-bound workload, this should be set to the number of CPUs available to the process. On an IO-bound workload, this could be set to a higher number.
Strategy
- CLI:
--strategy
or-s
- Environment:
FAUCET_STRATEGY
- Default:
round-robin
- Possible values:
round-robin
ip-hash
cookie-hash
The strategy to use for load balancing. Which strategy you choose depends on your workload.
Round Robin
Round robin is a very lightweight and simple load balancing strategy. It simply distributes requests to workers in a round robin fashion. This can be a good strategy for most workloads, it is very simple and has very little overhead.
You should NOT use round robin if the server is stateful, as it will not guarantee that requests from the same client will be routed to the same worker. If you need persistent state, use IP Hash or Cookie Hash.
If a worker dies, the requests that were routed will continue to be the next available worker that is alive.
IP Hash
IP Hash is a more complex strategy that guarantees that requests from the same client
will be routed to the same worker. This is useful for stateful servers, such as Shiny
apps. IP Hash is enforced on Shiny apps if the strategy is set to auto
.
If a worker dies, the requests will be held until the worker is back online. This means that latency may increase if a worker dies.
Cookie Hash
Cookie Hash uses a cookie to identify the worker to send the request to. This is useful for sticky sessions from within the same network, even if clients are behind a NAT or share the same IP address.
Type (Type of server)
- CLI:
--type
or-t
- Environment:
FAUCET_TYPE
- Default:
auto
- Possible values:
auto
plumber
shiny
quarto-shiny
The type of server to run. This is used to determine the correct strategy to use and how to spawn the workers.
Auto
Auto will attempt to determine the type of server based on the contents of the
directory specified by --dir
.
- If the directory contains a plumber.R
or entrypoint.R
file, it will be assumed to be a Plumber server.
- If the directory contains an app.R
, or both server.R
and ui.R
files, it will be assumed to be a Shiny server.
- If a .qmd
file is provided via the --qmd
argument, or if FAUCET_QMD
is set, it will be assumed to be a Quarto Shiny application.
Otherwise, faucet will exit with an error.
Plumber
Runs the server as a Plumber API. The default strategy is round-robin
.
Shiny
Runs the server as a Shiny app. The default strategy is ip-hash
.
Quarto Shiny
Runs the server as a Quarto Shiny app. The default strategy is ip-hash
.
Requires the --qmd
option to specify the Quarto document.
Directory (Working directory)
- CLI:
--dir
or-d
- Environment:
FAUCET_DIR
- Default:
.
The directory to run the server from. This should be the directory that contains the
plumber.R
or Shiny app contents.
App Directory (Shiny appDir
)
- CLI:
--app-dir
or-a
- Environment:
FAUCET_APP_DIR
- Default:
None
Argument passed on to appDir
when running Shiny applications. This allows you
to specify a subdirectory within the --dir
path as the root for the Shiny app.
QMD (Quarto Document)
- CLI:
--qmd
- Environment:
FAUCET_QMD
- Default:
None
Path to the Quarto Shiny .qmd
file. This is required when type
is set to
quarto-shiny
, or when type
is auto
and you intend to run a Quarto Shiny app.
router
Subcommand Options
These options are specific to the router
subcommand, used for running faucet in router mode (experimental).
Config File
- CLI:
--conf
or-c
- Environment:
FAUCET_ROUTER_CONF
- Default:
./frouter.toml
Path to the router configuration TOML file.