AppSuite:Debugging production servers

API status: In Development

Debugging production servers

A how-to for debugging your local UI plugin in combination with production and staging servers, which use redirects, HTTPS, and other things which break with a simple grunt dev command.

Introduction

Not everybody has access to a dedicated test server. Sometimes, a plugin requires a backend system which is hard to access outside of existing infrastructure. And sometimes, a bug appears only on a production server. There are many reasons why a server which is used by grunt dev can not be reconfigured and has to be used as-is.

The most frequent reason, why debugging with a remote server fails, are redirects to an external login page. After the login, the browser is usually redirected to the original domain, and all the cookies used for authentication are also set for that domain, not http://localhost:8337, where Grunt listens.

The solution is to use a proxy server, which redirects all requests to the server's domain to Grunt. Until grunt dev can be used as an HTTP proxy directly, a dedicated proxy is required. This proxy needs to support custom hosts files. Any kind of rewriting or forwarding usually ends up in the wrong domain being used, and therefore still breaking cookies and redirects. The global /etc/hosts can't be used because Grunt still needs to access the original server, and use the original domain name for that to properly set the Host header.

The usual way to use a custom hosts file is to set it in the HOSTALIASES environment variable. Unfortunately, for security reasons, this variable is explicitly cleared when executing setuid processes. And this is exactly what proxy servers tend to do. A proxy server with explicit configuration support for custom hosts files is Squid. So that's what we will use for debugging.

HOWTO

All commands are specified for Debian. Commands which need to be run as root start with #, commands which can be run as a normal user start with $.

The examples use user as user name, and all temporary files are stored in /home/user/proxy. You should use your own directory, and can pick any other directory. For the server domain, we'll use example.com, which should of course be replaced by the real domain of the OX server.

Squid

Install Squid.

# apt-get install squid3

Copy your /etc/hosts file to another location.

$ cp /etc/hosts /home/user/proxy/hosts

Add a line which redirects the target domain to localhost.

$ echo '127.0.0.1 example.com' >> /home/user/proxy/hosts

Now this file can be added to Squid's configuration file.

# echo 'hosts_file /home/user/proxy/hosts' >> /etc/squid3/squid.conf
# service squid3 reload

Grunt

Assuming you already have a working local.conf.json, add the following entries to the "appserver" section:

"protocol": "https",
"port": 443,
"server": "https://example.com/custom-path/",
"rejectUnauthorized": false,
"path": "/custom-path",

The entry "path" is optional, if the default /appsuite is used.

If the main path uses an HTTP redirect for a custom login page, then the initial request can't be intercepted by Grunt. The following entry disables it:

"index": "/",

This has two side-effects:

1. The mail HTML file is always served by the original server, and therefore
2. The timestamps used for cache-busting are not updated by Grunt.

This means clearing the cache will be required more often. If that becomes too much overhead, you can log in, then remove the option and restart Grunt.

Running grunt dev

Since Grunt needs to bind to port 443, it requires additional privileges. There are several options. Running Grunt as root is the quickest, but also least secure way. Better alternatives are authbind and setcap.

Don't forget to stop your local web server (e.g. Apache),

# service apache2 stop

or at least disable SSL.

# a2dismod ssl
# service apache2 restart

authbind

authbind is a program which uses a setuid helper to bind to lower ports. It is usually not installed by default.

# apt-get install authbind

The configuration is performed by creating files in /etc/authbind and giving execute permissions to the appropriate users.

# touch /etc/authbind/443
# chown user /etc/authbind/443
# chmod 544 /etc/authbind

Now, Grunt can be started using the wrapper.

$ authbind --deep grunt dev

setcap

This option can be used if your file system supports capabilities. It is less secure since it grants the permission to bind to all low ports to any Node program. But if supported, it at least does not require additional tools.

# setcap "cap_net_bind_service=+ep" "$(readlink -f "$(which node)")"

On OS X, greadlink needs to be used instead of readlink. If you don't have it, just find out where the actual node binary is installed and use it directly as the second parameter to setcap.

Grunt can then be run as usual.

$ grunt dev

Launching the browser

Now that everything is running, you only need to use the proxy when debugging your code in the browser. Most browsers have their own proxy settings, which override system-wide settings. They also respect environment variables like http_proxy.

$ http_proxy=http://localhost:3128 firefox

Chrome does not have its own settings (it starts the global settings dialog) and it ignores http_proxy. Instead, you have to use a command line parameter:

$ chromium --proxy-server=http://localhost:3128