Skip to content

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 or X-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.

Max Message Size

  • CLI: --max-message-size
  • Environment: FAUCEC_MAX_MESSAGE_SIZE
  • Default: None

Maximum size of a WebSocket message. This is useful for DDOS prevention. If not set, there is no size limit.

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.

Telemetry: PostgreSQL SSL Certificate

  • CLI: --pg-sslcert
  • Environment: FAUCET_TELEMETRY_POSTGRES_SSLCERT
  • Default: None

Path to a CA certificate file for verifying the PostgreSQL server when using SSL/TLS. Required if --pg-sslmode is set to verify-ca or verify-full. The certificate should be in PEM or DER format.

Telemetry: PostgreSQL SSL Mode

  • CLI: --pg-sslmode
  • Environment: FAUCET_TELEMETRY_POSTGRES_SSLMODE
  • Default: prefer
  • Possible values:
  • disable
  • prefer
  • require
  • verify-ca
  • verify-full

Controls the SSL/TLS behavior for the PostgreSQL connection. If set to verify-ca or verify-full, a CA certificate must be provided via --pg-sslcert or FAUCET_TELEMETRY_POSTGRES_SSLCERT.

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 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.