AppSuite:Appserver: Difference between revisions
(added categories) |
No edit summary |
||
(37 intermediate revisions by 4 users not shown) | |||
Line 4: | Line 4: | ||
The <code>appserver</code> tool is used to develop and test the OX App Suite UI and its plugins with a remote backend. <code>appserver</code> acts as a reverse HTTP proxy for an existing OX App Suite installation and injects the tested JavaScript code in its replies. | The <code>appserver</code> tool is used to develop and test the OX App Suite UI and its plugins with a remote backend. <code>appserver</code> acts as a reverse HTTP proxy for an existing OX App Suite installation and injects the tested JavaScript code in its replies. | ||
WARNING: These informations are only tested and validated for DEBIAN installations! Please use a DEBIAN virtual machine. Standalone version and using appserver with connect-based middleware should work in most cases, though. | |||
== Installation == | == Installation == | ||
Line 9: | Line 11: | ||
The core of <code>appserver</code> is a Node.js script, so if your OS does not provide a <code>nodejs</code> package, you will have to install it manually, either as a [https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager 3rd party package] or directly from [http://nodejs.org/ nodejs.org]. | The core of <code>appserver</code> is a Node.js script, so if your OS does not provide a <code>nodejs</code> package, you will have to install it manually, either as a [https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager 3rd party package] or directly from [http://nodejs.org/ nodejs.org]. | ||
Read more about how to install the tools for developing for OX App Suite in the [[AppSuite:GettingStarted#Installing | getting started article]]. | |||
== | == Standalone use == | ||
In the simplest case of developing an app or a plugin, all that is needed is the appserver npm package to be installed globally. | |||
# on many Linux systems you need to run this using the sudo command. MacOS and Windows *should* work without | |||
npm install -g appserver | |||
Assuming you are in the top directory of your app's source code and <code>[[AppSuite:UI build system#builddir|$builddir]]</code> is not set: | |||
appserver [[#server|--server]]=<nowiki>https://www.ox.io/appsuite/</nowiki> 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 <code>/appsuite</code> to <code>/appsuite/</code> and includes its own absolute URL in the redirect. | |||
If | 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 <code>&debug-js=true</code> to your URL to disable the file cache. | ||
== Usage with connect-based middleware == | |||
= | You can also integrate the collection of middleware classes shipped by appserver into any [http://www.senchalabs.org/connect/ connect]-based middleware, such as [https://github.com/gruntjs/grunt-contrib-connect grunt-contrib-connect]. An example <code>Gruntfile.js</code> can be found in the [https://github.com/Open-Xchange-Frontend/appserver#example-usage-with-grunt-contrib-connect appserver repo]: | ||
var appserver = require('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; | |||
} | |||
} | |||
} | |||
}); | |||
== 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 <code>.htaccess</code> files are adapted, of course). | |||
First, make your app visible in Apache. The simplest way is to symlink the <code>[[AppSuite:UI build system#builddir|$builddir]]</code> inside the document root. Assuming the app is in <code>/home/user/myapp</code> and the web server's document root is <code>/var/www</code>: | |||
sudo ln -s /home/user/myapp/build /var/www/myapp | |||
In case Apache ignores the symlink, ensure that its configuration directive <code><Directory /var/www/></code> contains "<code>Options FollowSymlinks</code>" or something to that effect. | |||
Second, configure Apache to request from <code>appserver</code> anything that it can't find locally. This configuration requires at least <code>mod_rewrite</code>, <code>mod_proxy</code> and <code>mod_proxy_http</code> to be enabled. Editing a file like <code>/etc/apache2/sites-enabled/000-default</code> containing the proxy configuration, add the following inside an eventual <code><VirtualHost></code> directive, but outside of any <code><Directory></code> directives: | |||
RewriteEngine On | |||
ProxyPreserveHost On | |||
ProxyPassMatch ^/((appsuite|ajax|infostore|publications\ | |||
|realtime|servlet|usm-json|webservices)(/.*)?)$ \ | |||
<nowiki>http://localhost:8337/$1</nowiki> | |||
RewriteCond %{DOCUMENT_ROOT}/myapp/$2 -f | |||
RewriteRule ^/appsuite/(v=[^,/]+/)?(.*)$ /myapp/$2 [PT] | |||
Take care configuring apache configuration, proxy definitions might take place in several files. For example <code>/etc/apache2/conf.d/proxy_http.conf</code> does also often contain http proxy configuration, which may differ from the definitions in the file edited above. | |||
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 "<code>myapp</code>". If you are using aliases instead of symlinks then replace <code>%{DOCUMENT_ROOT}</code> with the actual file system path from the <code>Alias</code> directive. | |||
Now, restart Apache and start <code>appserver</code>. | Now, restart Apache and start <code>appserver</code> adding the path to your simlinked build-path of the app as an parameter. | ||
sudo apachectl restart | sudo apachectl restart | ||
appserver [[#server|--server]]= | appserver [[#server|--server]]=<nowiki>https://www.ox.io/appsuite/</nowiki> /var/www/myapp | ||
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. | 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 <code>/var/www/appsuite</code> as directory, but don't add a <code>RewriteRule</code> for it. Instead, replace "<code>appsuite</code>" with "<code>appsuite/api</code>" in the <code>ProxyPassMatch</code> directive and add a <code><Directory></code> directive like for any other OX App Suite installation: | |||
<Directory /var/www/appsuite/> | |||
Options FollowSymlinks | |||
AllowOverride Indexes FileInfo | |||
</Directory> | |||
== Reference == | == Reference == | ||
Line 72: | Line 120: | ||
-m PATH, --manifests=PATH add manifests from the specified path (default: | -m PATH, --manifests=PATH add manifests from the specified path (default: | ||
the "manifests" subdirectory of every file path) | 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) | -p PORT, --port=PORT listen on PORT (default: 8337) | ||
-s URL, --server=URL use an existing server as fallback | -s URL, --server=URL use an existing server as fallback | ||
-v, | -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 | -z PATH, --zoneinfo=PATH use timezone data from the specified path | ||
(default: /usr/share/zoneinfo/) | (default: /usr/share/zoneinfo/) | ||
Line 86: | Line 137: | ||
If at least one <code>--manifests</code> option is specified, the default file paths are not used for manifests at all. | If at least one <code>--manifests</code> 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 <code>/appsuite/</code>) get mapped to the URL of the <code>[[#server|--server]]</code> parameter, while all other paths get mapped to identical paths on that server to allow services like <code>/publications</code> 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 === | === port === | ||
Line 99: | Line 156: | ||
=== verbose === | === verbose === | ||
Enables verbose output. During normal operation, <code>appserver</code> only | Enables verbose output. During normal operation, <code>appserver</code> 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. | |||
; <nowiki>local:error</nowiki> : 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 <code>-v local -v remote -v proxy</code>. | |||
Output lines belonging to the same client request are grouped together and separated from the next request by an empty line. | |||
=== zoneinfo === | === zoneinfo === |
Latest revision as of 12:08, 14 March 2014
API status: New
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.
WARNING: These informations are only tested and validated for DEBIAN installations! Please use a DEBIAN virtual machine. Standalone version and using appserver with connect-based middleware should work in most cases, though.
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.
Read more about how to install the tools for developing for OX App Suite in the getting started article.
Standalone use
In the simplest case of developing an app or a plugin, all that is needed is the appserver npm package to be installed globally.
# on many Linux systems you need to run this using the sudo command. MacOS and Windows *should* work without npm install -g appserver
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.
Usage with connect-based middleware
You can also integrate the collection of middleware classes shipped by appserver into any connect-based middleware, such as grunt-contrib-connect. An example Gruntfile.js
can be found in the appserver repo:
var appserver = require('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; } } } });
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. Editing a file like /etc/apache2/sites-enabled/000-default
containing the proxy configuration, 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]
Take care configuring apache configuration, proxy definitions might take place in several files. For example /etc/apache2/conf.d/proxy_http.conf
does also often contain http proxy configuration, which may differ from the definitions in the file edited above.
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
adding the path to your simlinked build-path of the app as an parameter.
sudo apachectl restart appserver --server=https://www.ox.io/appsuite/ /var/www/myapp
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 subdirectoriesapps
andmanifests
. Each injected file is looked up in theapps
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 themanifests
subdirectory of each path are combined and added to the manifests from the remote server. Each manifest entry overrides any entries with the samepath
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.
- 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.