|
|
| (6 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | {{Stability-experimental}}
| + | The content on this page has moved to https://documentation.open-xchange.com/latest/ui/miscellaneous/debugging-prodserver.html |
| − | <div class="title">Debugging production servers</div>
| |
| | | | |
| − | 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 <tt>grunt dev</tt> command.
| + | Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition. |
| − | | |
| − | == 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 <tt>grunt dev</tt> 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 <tt>grunt dev</tt> 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 <tt>/etc/hosts</tt> 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 <tt>Host</tt> header.
| |
| − | | |
| − | The usual way to use a custom hosts file is to set it in the <tt>HOSTALIASES</tt> 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 <tt>#</tt>, commands which can be run as a normal user start with <tt>$</tt>.
| |
| − | | |
| − | The examples use <tt>''user''</tt> as user name, and all temporary files are stored in <tt>/home/''user''/proxy</tt>. You should use your own directory, and can pick any other directory. For the server domain, we'll use <tt>''example.com''</tt>, which should of course be replaced by the real domain of the OX server.
| |
| − | | |
| − | === Squid ===
| |
| − | | |
| − | Install Squid.
| |
| − | | |
| − | # apt-get install squid3
| |
| − | | |
| − | Copy your <tt>/etc/hosts</tt> 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''<nowiki/>' >> /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 <tt>local.conf.json</tt>, add the following entries to the <tt>"appserver"</tt> section:
| |
| − | | |
| − | "protocol": "https",
| |
| − | "port": 443,
| |
| − | "server": "https://''example.com''/''custom-path''/",
| |
| − | "rejectUnauthorized": false,
| |
| − | "path": "/''custom-path''",
| |
| − | | |
| − | The entry <tt>"path"</tt> is optional, if the default <tt>/appsuite</tt> 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:
| |
| − | # The mail HTML file is always served by the original server, and therefore
| |
| − | # 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 <tt>grunt dev</tt>===
| |
| − | | |
| − | 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 <tt>authbind</tt> and <tt>setcap</tt>.
| |
| − | | |
| − | 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
| |
| − | | |
| − | ==== <tt>authbind</tt> ====
| |
| − | | |
| − | <tt>authbind</tt> 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 <tt>/etc/authbind</tt> 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
| |
| − | | |
| − | ==== <tt>setcap</tt> ====
| |
| − | | |
| − | 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, <tt>greadlink</tt> needs to be used instead of <tt>readlink</tt>. If you don't have it, just find out where the actual <tt>node</tt> binary is installed and use it directly as the second parameter to <tt>setcap</tt>.
| |
| − | | |
| − | 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 <tt>http_proxy</tt>.
| |
| − | | |
| − | $ 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
| |