Reverse Proxy

Configure the proxy to intercept inbound requests

Command

stoobly-agent run --proxy-mode reverse:<URL>

Configuring /etc/hosts

To use a reverse proxy with a specific domain name, you need to modify your /etc/hosts file to point the domain to localhost. This allows your system to resolve the domain name to the reverse proxy instead of the actual server.

Manual Configuration

Edit /etc/hosts (requires administrator privileges):

On Linux/macOS:

sudo nano /etc/hosts

Add entries for each domain you want to intercept:

127.0.0.1 example.com
127.0.0.1 api.example.com
::1       example.com
::1       api.example.com

On Windows:

1. Open Notepad as Administrator

2. Open C:\Windows\System32\drivers\etc\hosts

3. Add the same entries as shown above

Example

If you're setting up a reverse proxy for https://api.example.com:

1. Add to /etc/hosts:

   127.0.0.1 api.example.com
   ::1       api.example.com

2. Run Stoobly with reverse proxy mode:

   stoobly-agent run --proxy-mode reverse:https://api.example.com

3. Access the domain - requests will be intercepted:

   curl https://api.example.com/users

Cleanup

Remember to remove entries from /etc/hosts when you're done testing, or comment them out by adding # at the start of each line.

For scaffold workflows, you can use stoobly-agent scaffold hostname install --workflow <WORKFLOW_NAME> to automatically manage /etc/hosts entries for service hostnames.

Enabling HTTPS Traffic

To enable HTTPS traffic to the reverse proxy, add the following options to the run command:

  --certs TEXT                    SSL certificates of the form
                                  "[domain=]path". The domain may include a
                                  wildcard, and is equal to "*" if not
                                  specified. The file at path is a certificate
                                  in PEM format. If a private key is included
                                  in the PEM, it is used, else the default key
                                  in the conf dir is used. The PEM file should
                                  contain the full certificate chain, with the
                                  leaf certificate as the first entry. May be
                                  passed multiple times.

  --cert-passphrase TEXT          Passphrase for decrypting the private key
                                  provided in the --cert option. Note that
                                  passing cert_passphrase on the command line
                                  makes your passphrase visible in your
                                  system's process list. Specify it in
                                  config.yaml to avoid this.