bripkens / proxrox

Proxy services, combine origins, use SSI and more during development

proxrox  

Avoid SOP problems, combine origins, proxy services, use SSL, HTTP2, SSI and more… during development!

Installation | Usage | Configuration | Example projects | Support | Changelog

---

Proxrox is a command line utility which starts a local Nginx instance to serve up static files, proxy one or many services under a single origin, use SSL locally and, generally, to get a development environment that is similar to a production environment.

Proxrox achieves this using Nginx. When proxrox is asked to start a server, it will create an Nginx config file in a temporary location and start an Nginx instance using this config file. This means that proxrox can theoretically support all of Nginx's features.

You can also use Proxrox to debug web apps, as shown in the following presentation.

Installation

TL;DR; npm install -g proxrox. Nginx needs to be on the $PATH and executable without super-user privileges.

Detailed installation instructions can be found in INSTALLATION.md.

Usage

Start proxrox using a local configuration file. Format and supported options are explained in the CONFIGURATION.md file.

proxrox start .proxrox.yaml

Stop the running Nginx instances (stops all):

proxrox stop

Experience has shown that the definition of options via configuration files, e.g. .proxrox.yaml, is the most commonly used option. Working example projects with the recommended project setup can be seen in the examples directory.

Why proxrox exists

Production and development environment parity

Development environments should resemble production environments. This means that server-side includes, transport layer security, compression and more should exist during development. Not only is this important for page speed optimizations, but it also allows you to find security issues early, e.g. a secure page which references insecure content.

Serving multiple services under a single origin

Whether the app is service-oriented, micro service based, resource-oriented client architecture like or a single page app, the same-origin policy is often an issue for local development. People circumvent this issue in various ways. While most teams have good practices in place for production environments, development environments often lack this. Solutions I have seen range from cross-origin resource sharing for local development activated via feature flags to completely disabling web security in browsers.

Extending the space of possible solutions

Many people don't know or use server-side includes. There are probably various reasons for this. One thing that I noticed myself is that it just takes time to setup a proper development environment with proxy servers.

Support

Something not working as expected? Feel free to contact me on Twitter via @BenRipkens!

proxrox's Issues

Optionally use a standard certificate instead of regenerating a new one all the time

This way the user wouldn't be required to accept the newly generated certificate all the time.

Proxy multiple services

It should be possible to proxy multiple services. We are currently doing this via try_files for a single named location, but might need to switch to multiple locations with paths to implement this.

Add authbind instructions to run proxrox on linux?

Hi, thanks for making this great utility, its an absolutely awesome thing.

I have been using proxrox on MacOS for quite sometime now, but today I had to setup an environment on Linux (Linux Mint to be specific) and for some reason the default installation instructions did not work for me.

What worked though was using authbind to setup proxrox. I would be happy to contribute by opening a PR to suggest this as an alternative approach if that works for you?

Don't immediately read pid. Wait until nginx has started

Also see

proxrox/lib/control.js

Line 51 in bea43b8

var pid = parseInt(fs.readFileSync(pidFile, {encoding: 'utf8'}).trim());

Issue with directory permissions results in 404 on POST

I noticed that a POST request that works fine without being proxied through proxrox results in a 404 when proxied through proxrox. Here's what the logs say:

error log:

2015/08/08 16:24:48 [crit] 6549#0: *6 open() "/var/lib/nginx/body/0000000001" failed (13: Permission denied), client: 127.0.0.1, server: example, request: "POST /upload HTTP/1.1", host: "localhost:4000", referrer: "http://localhost:4000/"
2015/08/08 16:24:48 [error] 6549#0: *6 open() "/tmp/proxrox/c5f08868-85d1-4599-9e47-1af1bf9b88bb/html/50x.html" failed (2: No such file or directory), client: 127.0.0.1, server: example, request: "POST /upload HTTP/1.1", host: "localhost:4000", referrer: "http://localhost:4000/"

access.log

127.0.0.1 - - [08/Aug/2015:16:24:48 +0200] "POST /upload HTTP/1.1" 404 420 "http://localhost:4000/" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Ubuntu Chromium/43.0.2357.130 Chrome/43.0.2357.130 Safari/537.36" "2.94"

The main issue seems to be open() "/var/lib/nginx/body/0000000001" failed (13: Permission denied). The directory /var/lib/nginx/body used to temporary store the request body and on my system, everything under /var/lib/nginx is owned by nobody:root. When running proxrox/nginx without sudo (I assume proxrox is intended to be run without sudo, right?) then nginx can not create new files there.

I verified this by temporarily chmodding /var/lib/nginx/body to 777, then the POST request works as expected.

A possible solution might be to set the client_body_temp_path directive in the nginx.conf. However, I could guess there might be more, similar cases where nginx needs a tmp dir for something and does not have the correct permissions. (For example, at least proxy_temp_path looks suspicious)

Use SPDY for development

proxrox stop gets stuck

proxrox stop hangs on my Linux Mint box, reproducible. The nginx processes get killed though, but proxrox stop never returns control to the shell. I'm pretty sure it's shelljs' fault, as this one liner also hangs:

require('shelljs').exec('pkill -f foobar');

It's probably related to shelljs/shelljs#51

On a slightly related note, it feels a little bit brute-force-y to just kill all nginx master processes. It might be quite unlikely, but there could be another, completely unrelated, nginx process around, right?

What about spawning the nginx process via node core's child_process.spawn on proxrox start, remembering the pid (in the tmp folder), and killing only the process with that pid on proxrox stop?

local proxrox proxy config?

This is a great idea. Currently I am using nginx to proxy two micro services into one website during development. If proxrox read a local proxrox.json file or something like that, and could set up proxies on the fly based on that file, it'd be incredibly useful. Something like

{
  "/foo": "http://127.0.0.1:8000",
  "/bar": "http://127.0.0.1:9000"
}

obviously that's super simplified, but the general idea.

Allow custom domains

Thinking of starting the server and being able to type https://my-project.local into the browser.

Support ngx_pagespeed for Linux platforms

Unfortunately pagespeed does not yet support OS X (apache/incubator-pagespeed-ngx#149), but this feature may be very useful for Linux users.

Document nginx installation instructions for linux

Provide proxrox install support for the most common linux distributions and document proxrox's expections, i.e. that nginx is on the $PATH and that a server must be runnable without sudo.

Installation looks like this for Ubuntu 14.04 when we want to support pagespeed. If not, then aptitude would suffice.

set -eo pipefail

NPS_VERSION=1.9.32.3
NGINX_VERSION=1.6.2

INSTALL_PATH=/tmp/nginx/install
RUN_PATH=/tmp/nginx/run

rm -rf $INSTALL_PATH $RUN_PATH
mkdir -p $INSTALL_PATH
mkdir -p $RUN_PATH


# sudo apt-get update
sudo apt-get install openssl libpcre3 libpcre3-dev libssl-dev zlib1g-dev build-essential unzip

cd $INSTALL_PATH
wget https://github.com/pagespeed/ngx_pagespeed/archive/release-${NPS_VERSION}-beta.zip
unzip release-${NPS_VERSION}-beta.zip
cd ngx_pagespeed-release-${NPS_VERSION}-beta/
wget https://dl.google.com/dl/page-speed/psol/${NPS_VERSION}.tar.gz
tar -xzvf ${NPS_VERSION}.tar.gz  # extracts to psol/

cd ..
# check http://nginx.org/en/download.html for the latest version
wget http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz
tar -xvzf nginx-${NGINX_VERSION}.tar.gz
cd nginx-${NGINX_VERSION}/
./configure --add-module=../ngx_pagespeed-release-${NPS_VERSION}-beta \
            --with-http_ssl_module \
            --with-http_gzip_static_module \
            --with-http_spdy_module \
            --sbin-path=$RUN_PATH/nginx \
            --conf-path=$RUN_PATH/nginx.conf \
            --pid-path=$RUN_PATH/nginx.pid \
            --lock-path=$RUN_PATH/nginx.lock \
            --http-client-body-temp-path=$RUN_PATH/client_body_temp \
            --http-proxy-temp-path=$RUN_PATH/proxy_temp \
            --http-fastcgi-temp-path=$RUN_PATH/fastcgi_temp \
            --http-uwsgi-temp-path=$RUN_PATH/uwsgi_temp \
            --http-scgi-temp-path=$RUN_PATH/scgi_temp \
            --http-log-path=$RUN_PATH/access.log \
            --error-log-path=$RUN_PATH/error.log
make
sudo make install

Automatically start a browser upon server start

Add HTTP2 config support

nginx now has HTTP2 protocol support. This can be supported by proxrox!

Provide programatic API to start proxrox

This way the following use case would become easier:

https://github.com/bripkens/proxrox/blob/master/examples/inquirerDevModeWithWebpack/build/dev.js#L52-L69

Document nginx installation instructions for Ubuntu systems when executing `proxrox install`

proxrox stop might kill unrelated instances of nginx

As discussed in #14

@basti1302:

On a slightly related note, it feels a little bit brute-force-y to just kill all nginx master processes. It might be quite unlikely, but there could be another, completely unrelated, nginx process around, right?

What about spawning the nginx process via node core's child_process.spawn on proxrox start, remembering the pid (in the tmp folder), and killing only the process with that pid on proxrox stop?

@bripkens:

I very much like the idea! But then proxrox stop could only stop the last started nginx process. Can we come up with a strategy to stop the nginx process which is currently running for a given .proxrox.yaml file?

I investigated a bit yesterday. The pid returned by child_process.spawnSync is not the pid of the nginx master process. Apparently nginx -c ... -p ... (the command used to start nginx) starts a short lived process which in turn spawns the master process. However, the nginx pid is already available in /tmp/proxrox/uuid/log/nginx.pid because this is configured in the nginx config template.

So we could have a look at all existing files that match the pattern /tmp/proxrox/uuid/log/nginx.pid, read the pids from those files and kill only those processes. That still would kill all nginx processes created by proxrox but it is a bit better than killing all nginx intances, even those not created by proxrox.

The alternative would be to put a file (only the pid or the whole tmp structure) into the current directory but that creates some new problems.

I think there is no third alternative, as proxrox has no persistent storage between proxrox start and proxrox stop.

Export the proxrox API for other tool developers

use application/javascript mime type for js files

Proxrox for Windows

Is it possible to run this on Windows?

npm ERR! code EBADPLATFORM npm ERR! notsup Unsupported platform for [email protected]: wanted {"os":"darwin,linux"} (current: {"os":"win32","arch":"x64"})

Not redirecting

my proxrox config

proxy:

• type: 'https'
  from: '/'
  to: 'https://app.*.ai:3000'

use case : redirect all requests from app..ai to app..ai:3000

please help

gzip javascript files

Use transport-layer security for development