ixpantia / faucet

Fast and scalable R application deployment and orchestration
https://ixpantia.github.io/faucet/
MIT License
101 stars 11 forks source link
prodverse

faucet

Crates.io test

Scale, deploy and route Plumber APIs and Shiny applications with ease and efficiency.

Summary

Welcome to faucet, the most feature complete Shiny Application and Plumber API deployment platform. faucet features load balancing, routing, logging, replication, and more all in one place; unifying your workflow for deploying R based applications.

Features

Usage

Get some help

To display the help message, run the following command:

faucet --help

Start a Plumber API

To start a plumber API, you will simply need to specify the directory containing the 'plumber.R' file. faucet will automatically detect the file and start the API.

faucet start --dir /path/to/plumber/api

The server will automatically listen on port 3838 by default. To change the host and port, use the --host flag to specify the socket address to bind to the service.

faucet start --dir /path/to/plumber/api --host 0.0.0.0:3000

By default faucet will start as many workers as there are logical cores on the machine. To specify the number of workers, use the --workers flag.

faucet start --dir /path/to/plumber/api --workers 4

Start a Shiny Application

To start a Shiny Application, you will simply need to specify the directory containing the 'app.R' file. faucet will automatically detect the file and start the application.

faucet start --dir /path/to/shiny/app

The server will automatically listen on port 3838 by default. To change the host and port, use the --host flag to specify the socket address to bind to the service.

faucet start --dir /path/to/shiny/app --host 0.0.0.0:3000

By default faucet will start as many workers as there are logical cores on the machine. To specify the number of workers, use the --workers flag.

faucet start --dir /path/to/shiny/app --workers 4

Note: On Shiny applications, faucet will be forced to use IP Hash load balancing. This is because Shiny applications require a persistent connection between the client and the server. If Round Robin load balancing is used, the client will be redirected to a different instance on each request, causing the connection to be lost.

Pick a Load Balancing Strategy for Plumber APIs

faucet supports two load balancing strategies for Plumber APIs: Round Robin and IP Hash. By default, faucet will use Round Robin load balancing. To change the strategy, use the --strategy flag.

faucet start --dir /path/to/plumber/api --strategy ip-hash

Explicitly Set the Type of Application

By default, faucet will try to detect the type of application based on the files in the specified directory. If you want to explicitly set the type of application, use the --type flag.

For Plumber applications:

faucet start --dir /path/to/plumber/api --type plumber

For Shiny applications:

faucet start --dir /path/to/shiny/app --type shiny

For Quarto applications:

faucet start --qmd /path/to/example.qmd --type quarto-shiny

If you are working with a Quarto document, it must be explicitly specified using the --qmd flag and the --type quarto-shiny option.

With Nginx / Reverse Proxy

If you want to run multiple faucet instances behind a reverse proxy, or you want to enable HTTPS, you may use Nginx or any other reverse proxy. However, to make sure faucet correctly detects the client IP address, you will need to set the X-Forwarded-For header or the X-Real-IP header.

Nginx

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://...;
        proxy_set_header  X-Real-IP $remote_addr;
        proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
        ...
    }
}

Additionally, when running faucet, you will need to set the -i / --ip-from flat to either x-forwarded-for or x-real-ip depending on which header you set in Nginx.

faucet start --dir /path/to/plumber/api --ip-from x-forwarded-for

Installation

Option 1: Binary Download (Linux)

Download the latest release of faucet for Linux from the GitHub Releases page. This should work with most Linux distributions.

FAUCET_VERSION="v1.1.0"

wget https://github.com/ixpantia/faucet/releases/download/$FAUCET_VERSION/faucet-x86_64-unknown-linux-musl -O faucet

# Make the binary executable
chmod +x faucet

# Move the binary to a directory in your PATH (e.g., user local bin)
mv faucet ~/.local/bin

Option 2: Install with Cargo (Linux, macOS, Windows)

Install faucet with Cargo, Rust's package manager.

  1. Install Rust by following the instructions here.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  1. Install faucet with Cargo.
cargo install faucet-server --version ^1.1

Option 3: Build from Source (Linux, macOS, Windows)

  1. Install Rust by following the instructions here.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  1. Clone the faucet repository.
git clone https://github.com/ixpantia/faucet.git
  1. Build faucet with Cargo.
cargo install --path .

HTTP Telemetry

faucet now offers the option of saving HTTP events to a PostgreSQL database. This can be very helpful for tracking latency, total API calls and other important information.

In order to use this feature you will need a PostgreSQL database with a table called faucet_http_events. You can create the table using this table with the following SQL query:

CREATE TABLE faucet_http_events (
    request_uuid UUID,
    namespace TEXT,
    version TEXT,
    target TEXT,
    worker_route TEXT,
    worker_id INT,
    ip_addr INET,
    method TEXT,
    path TEXT,
    query_params TEXT,
    http_version TEXT,
    status SMALLINT,
    user_agent TEXT,
    elapsed BIGINT,
    time TIMESTAMPTZ
);

Connection Strings

In order to connect to the database you will need to pass the FAUCET_TELEMETRY_POSTGRES_STRING environment variable or the --pg-con-string CLI argument.

This should include either a connection string or a URL with the postgres:// protocol.

Example connection strings

FAUCET_TELEMETRY_POSTGRES_STRING="host=localhost user=postgres connect_timeout=10 keepalives=0"
FAUCET_TELEMETRY_POSTGRES_STRING="host=/var/lib/postgresql,localhost port=1234 user=postgres password='password with spaces'"
FAUCET_TELEMETRY_POSTGRES_STRING="postgresql://user@localhost"
FAUCET_TELEMETRY_POSTGRES_STRING="postgresql://user:password@127.0.0.1/mydb?connect_timeout=10"

Telemetry Namespaces

It is likely you want to track different services on the same database. You can control the column namespace using the environment variable FAUCET_TELEMETRY_NAMESPACE or cli argument --telemetry-namespace. By default, this value is "faucet".

Useful links

Contributing

If you want to contribute to faucet please read the CONTRIBUTING.md document.