Proxy Box

A CLI to create and manage containerized proxy servers. Useful for woking around HTTPS and CORS hurdles in local development environments.

Getting started

Dependencies

In order for proxy-box to do its thing, you'll need the following installed:

• Node (>=8) & NPM (>= 5)
• Docker

Setup

First, install the proxy-box package globally:

npm install -g proxy-box

Next, if you're going to be using the HTTPS listener, you'll want to download this localhost SSL certificate and install it in your list of locally trusted roots. How you do that is dependent on your OS/browser, so you're gonna have to Google it if you're unfamiliar.

Finally, you'll want to initialize the proxy-box Docker image:

pxbx init

And you should be ready to start making boxes!

Usage

pxbx init

This command initializes proxy-box by downloading the Docker image it relies on to create instances. You can use the --skip-pull flag to force the image to build locally instead of attempting to pull from Docker Hub.

Flag	Description
--skip-pull	Skip attempting to pull image from Docker Hub
--debug	Enable debug logging for this command
--help	View help docs for this command

pxbx create

This command creates proxy-box instances. You can pass it a config file with the --file or -f flags, or provide full configuration via flags. If you do both, the flags you provide in the command will override config file properties.

Flag	Description
--file, -f	Path to a config file
--target	The proxy target URL
--http	The port to listen on for HTTP
--https	The port to listen on for HTTPS
--cors	Enable CORS handling
--debug	Enable debug logging for this command
--help	View help docs for this command

A config file might look something like this:

{
  "http": 4000,
  "https": 4443,
  "target": "https://localhost:3000",
  "cors": true
}

Of the configuration options, target and at least one of http or https is required to create an instance.

Some example commands:

# Create from a config file 
pxbx create mybox -f config.json
 
# Create a simple HTTP proxy to localhost 
pxbx create mybox --http 5000 --target http://localhost:3000
 
# Use a config file but override some properties 
pxbx create mybox -f config.json --https 8443 --cors

pxbx start

This command starts your proxy-box instances. It takes a name as its third argument, and that's basically it.

Flag	Description
--debug	Enable debug logging for this command
--help	View help docs for this command

An example command:

# Start an instance named "mybox" 
pxbx start mybox

pxbx stop

This command stops your proxy-box instances. It also takes a name as its third argument, and that's basically it.

Flag	Description
--debug	Enable debug logging for this command
--help	View help docs for this command

An example command:

# Stop an instance named "mybox" 
pxbx stop mybox

pxbx restart

This command restarts your proxy-box instances. It also takes a name as its third argument, and that's basically it.

Flag	Description
--debug	Enable debug logging for this command
--help	View help docs for this command

An example command:

# Restart an instance named "mybox" 
pxbx restart mybox

pxbx rm

This command removes your proxy-box instances. It takes a name as its third argument, and you can pass it --force or -f to force remove running instances.

Flag	Description
--force, -f	Force remove a running instance
--debug	Enable debug logging for this command
--help	View help docs for this command

Some example commands:

# Remove a stopped instance named "mybox" 
pxbx rm mybox
 
# Remove a running instance named "alsomybox" 
pxbx rm -f alsomybox

pxbx logs

This command retrieves logs from your proxy-box instances. It takes a name as its third argument, and you can pass it --follow or -f to tail the logs for running instances.

Flag	Description
--follow, -f	Tail logs for a running instance
--debug	Enable debug logging for this command
--help	View help docs for this command

Some example commands:

# View logs for an instance named "mybox" 
pxbx logs mybox
 
# Tail logs for a running instance named "mybox" 
pxbx logs -f mybox

pxbx ls

This command lists your proxy-box instances. It'll tell you the name, status, and configuration of each.

An example command:

# List those instances 
pxbx ls

Development

To work on pxbx locally, you can use npm link to make the command available.

To work on the proxy server image itself, you can use npm run dev inside the server directory to start up a dev server. For example:

npm run dev -- --target http://localhost:3000 --http 5000 --https 6000