npm package: @open-xchange/appserver
Description: A connect based middleware to support local development against a remote backend.
Author: Julian Bäume
Latest version: 0.9.4

# 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.

### Stand-Alone

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.

### As a node module

#### 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.