appserver

A connect based middleware to support local development against a remote backend.

Usage

This module can operate in two different modes. First as a stand-alone application that
is able to serve files from some configured directories. Second mode is via a node module
that can be loaded into some existing node project.

$3

You can install this module globally to make it available as a stand-alone command:

npm install -g @open-xchange/appserver

After that, you can run appserver --help in a terminal to get this help:

``
$ appserver --help :(
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/.
`

Those defaults will only be used for the CLI version. This is because the appserver CLI has
it’s roots within the OX appsuite project.

#### Options

Read more about the CLI options in detail:

##### 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.
- `local:error`: The name of files that have not been found locally are written to standard output (good for debugging missing files).
- `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.

$3

#### Example usage with grunt-contrib-connect

An example of how to use this module with grunt-contrib-connect, see this snippet from our Gruntfile.js:

`
const appserver = require('@open-xchange/appserver');

grunt.config('connect', {
server: {
options: {
port: 8337,
base: ['build/'],
livereload: true,
middleware: function (connect, options, middlewares) {
var config = grunt.config().local.appserver;
if (config.server === '') {
grunt.log.error('Server not specified in grunt/local.conf.json');
grunt.log.writeln('Hint: If this is a new setup you may want to copy the file grunt/local.conf.defaults.json to grunt/local.conf.json and change its values according to your setup.');
grunt.fail.fatal('Please adjust your local.conf.json');
}

config.prefixes = (config.prefixes || []).concat([options.base, options.base + '/apps/']);
config.manifests = (config.manifests || []).concat(options.base + '/manifests/');
config = appserver.tools.unifyOptions(config);

middlewares.push(appserver.middleware.appsload(config));
middlewares.push(appserver.middleware.manifests(config));
middlewares.push(appserver.middleware.localfiles(config));
middlewares.push(appserver.middleware.proxy(config));
return middlewares;
}
}
}
});
``

Development

In order to get started, run:

yarn

This will install the development dependencies needed, to get you started.

Then you can run

yarn dev

to start nodemon watching for file changes and run tests if needed.