AppSuite:Appserver

API status: New

Appserver

The appserver tool is used to develop and test the OX App Suite UI and its plugins with a remote backend. appserver acts as a reverse HTTP proxy for an existing OX App Suite installation and injects the tested JavaScript code in its replies.

Installation

The core of appserver is a Node.js script, so if your OS does not provide a nodejs package, you will have to install it manually, either as a 3rd party package or directly from nodejs.org.

The installation of the script itself depends on whether you want to make changes to the UI or only develop an external app.

For app developers

If you are developing an app, then you only need the OX App Suite SDK version 7.4 or later. On Linux, it is installed with the package open-xchange-appsuite-dev:

sudo apt-get install open-xchange-appsuite-dev

The binaries are installed to /opt/open-xchange-appsuite-dev/bin/. To have them available in a shell, add this directory to the PATH environment variable:

export PATH=$PATH:/opt/open-xchange-appsuite-dev/bin

For UI developers

If you are a UI developer, or if the SDK is not available for your OS, you will need to clone the UI source and use the tools contained in the ui/bin directory.

git clone --depth 1 -b develop https://code.open-xchange.com/git/wd/frontend/web
export PATH=$PATH:$(pwd)/web/ui/bin

The option -b develop specifies a git branch. Until version 7.4 is released, the full functionality described in this article is only available in the "develop" branch.

The option --depth 1 prevents the download of the entire history, and reduces the download size from hundreds of MB to less than 20MB. It should not be used by OX App Suite developers since it also prevents git push from working properly.

Standalone use

In the simplest case of developing an app or a plugin, all that is needed is an existing OX App Suite installation. Point appserver to the URL of OX App Suite and to the build directory of your app. Assuming you are in the top directory of your app's source code and $builddir is not set:

appserver --server=https://www.ox.io/appsuite/ build

If there are no errors, you can point your browser to http://localhost:8337/appsuite/ to test a version of OX App Suite which includes your app. Do not forget the trailing slash in the URL. Otherwise, the server sends a redirect from /appsuite to /appsuite/ and includes its own absolute URL in the redirect.

You do not need to restart anything after re-building the app, a refresh of the browser page should be enough. If your code doesn’t show up after a refresh, our file cache mighgt not be up-to-date. Until this is fixed in appserver, you can append &debug-js=true to your URL to disable the file cache.

Use with Apache

For more complex cases involving testing your own build of the UI, or apps which include static resources (e. g. images), a local web server is required to serve static resources. The following examples use the Apache HTTP Server, but any web server which can act as a reverse HTTP proxy should work (assuming the configuration and .htaccess files are adapted, of course).

First, make your app visible in Apache. The simplest way is to symlink the $builddir inside the document root. Assuming the app is in /home/user/myapp and the web server's document root is /var/www:

sudo ln -s /home/user/myapp/build /var/www/myapp

In case Apache ignores the symlink, ensure that its configuration directive <Directory /var/www/> contains "Options FollowSymlinks" or something to that effect.

Second, configure Apache to request from appserver anything that it can't find locally. This configuration requires at least mod_rewrite, mod_proxy and mod_proxy_http to be enabled. Add the following inside an eventual <VirtualHost> directive, but outside of any <Directory> directives:

RewriteEngine On
ProxyPreserveHost On

ProxyPassMatch ^/((appsuite|ajax|infostore|publications\
|realtime|servlet|usm-json|webservices)(/.*)?)$ \
http://localhost:8337/$1

RewriteCond %{DOCUMENT_ROOT}/myapp/$2 -f
RewriteRule ^/appsuite/(v=[^,/]+/)?(.*)$ /myapp/$2 [PT]

If you want to test multiple apps, use a different directory for each, and repeat the last two lines for each app, substituting the proper values for "myapp". If you are using aliases instead of symlinks then replace %{DOCUMENT_ROOT} with the actual file system path from the Alias directive.

Now, restart Apache and start appserver.

sudo apachectl restart
appserver --server=https://www.ox.io/appsuite/ /var/www/appsuite

If there are no errors, you can point your browser to http://localhost/appsuite/ to test a version of OX App Suite which includes your app. You do not need to restart anything after re-building the app, a refresh of the browser page should be enough.

Custom UI builds

To test your own build of the core UI, use /var/www/appsuite as directory, but don't add a RewriteRule for it. Instead, replace "appsuite" with "appsuite/api" in the ProxyPassMatch directive and add a <Directory> directive like for any other OX App Suite installation:

<Directory /var/www/appsuite/>
    Options FollowSymlinks
    AllowOverride Indexes FileInfo
</Directory>

Reference

appserver is a reverse HTTP proxy. It accepts HTTP requests and forwards most of them to another HTTP server. There are currently two exceptions:

• api/apps/load is served from a list of local paths. Only files which could not be found are fetched from the remote HTTP server. This allows to inject the code of a tested app without installing it on the remote server. The list of paths is specified as non-option parameters on the command line. Each path should normally have at least the subdirectories apps and manifests. Each injected file is looked up in the apps subdirectory of each path, in the order in which they appear on the command line, and the first found file is used. If a file is not found in any path, and the --server option is specified, the file is downloaded from the server.
• api/apps/manifests?action=config is extended by local manifests. This is necessary to enable the tested app in the UI. If no --manifests options are specified, then all files from the manifests subdirectory of each path are combined and added to the manifests from the remote server. Each manifest entry overrides any entries with the same path attribute. Similar to the priority for files, manifest entries from earlier paths override entries from later paths, and local entries override remote entries.

help

Displays a short summary of available options:

Usage: appserver [OPTION]... [PATH]...

  -h,      --help           print this help message and exit
  -m PATH, --manifests=PATH add manifests from the specified path (default:
                            the "manifests" subdirectory of every file path)
           --path=PATH      absolute path of the UI (default: /appsuite)
  -p PORT, --port=PORT      listen on PORT (default: 8337)
  -s URL,  --server=URL     use an existing server as fallback
  -v TYPE, --verbose=TYPE   print more information depending on TYPE:
                            local: local files, remote: remote files,
                            proxy: forwarded URLs, all: shortcut for all three
  -z PATH, --zoneinfo=PATH  use timezone data from the specified path
                            (default: /usr/share/zoneinfo/)

Files are searched in each PATH in order and requested from the server if not
found. If no paths are specified, the default is /var/www/appsuite/.

manifests

By default, the manifests of an app are collected and put into $builddir/manifests. Therefore, by default, appserver collects manifests from the manifests subdirectoriy of each file path. Since the destination directory for manifests can be changed by setting $manifestDir, the manifest directories can also be changed in appserver by specifying each directory with a separate --manifests option.

If at least one --manifests option is specified, the default file paths are not used for manifests at all.

path

By default, URLs belonging to the OX App Suite (i. e. starting with /appsuite/) get mapped to the URL of the --server parameter, while all other paths get mapped to identical paths on that server to allow services like /publications to work.

This parameter changes the path of the local OX App Suite URL e. g. to allow testing multiple UIs with the same server.

port

Specifies the port to listen on. The default is 8337. This option might be useful to run multiple instances of appserver at once or when port 8337 is already in use.

server

Specifies the URL of an existing OX App Suite installation. The URL must start with http:// or https://. To make forwarding of an HTTPS URL over HTTP possible, appserver removes the Secure attribute from all cookies set by the server.

This option is required for manifest injection to work, since the intercepted request contains more data than just the manifests.

verbose

Enables verbose output. During normal operation, appserver only writes errors to its console. By specifying this option one or more times, additional output can be enabled, depending on the value of each option:

local

The name of every read local file is written to standard output.

remote

The URL of every request for missing local files is written to standard output.

proxy

The URL of every client request which is forwarded as-is is written to standard output.

all

This is just a shortcut for -v local -v remote -v proxy.

Output lines belonging to the same client request are grouped together and separated from the next request by an empty line.

zoneinfo

Specifies the path to the zoneinfo database. On POSIX systems, the default of /usr/share/zoneinfo/ should always work. Even on systems without the database everything should just work if --server is specified, since any missing files will be fetched from the remote server. This option may still be useful when debugging time zone problems caused by different versions of the zoneinfo database.