Web Application Server


The Web application server is a threaded server which provides services to the Web UI, as well as supporting the tagger broker. By default, the application server also starts up a command loop which allows the user to start up and shut down various portions of the application. The application server supports CGI access for some services, and XML-RPC for others. The service API is intended to be internal; it will be documented at a later point.

Note: the Web application server inventories the tagger models it makes available in file mode at startup time. If you build a model after you start the Web server, the Web server won't know about that model until you restart it. (This condition does not apply to workspaces.)

The command loop

When you start up the Web server, and it's running a command loop, you see something like this:

Web server started on port 7801.

Web server command loop. Commands are:

exit - exit the command loop and stop the Web server
loopexit - exit the command loop, but leave the Web server running
taggerexit - shut down the tagger service, if it's running
restart - restart the Web server
ws_key - show the workspace key
help, ? - this message

Workspace key is w65gABlWFKYSdZwXCHaspyhW0DySP7ZW

These commands should be self-explanatory. The command that you're most likely to use is "ws_key", which prints out the workspace key that the Web server knows. The workspace security documentation explains the importance of this key.




Windows native:

> %MAT_PKG_HOME%\bin\MATWeb.cmd

Usage: MATWeb [options]


--port <num>
Port to listen on (default is 7801).
Don't report Web errors and access to stdout.
--access_log <file>
Absolute pathname of intended access log file. If absent, the Web access information will be written to standard output, unless --noscreen is specified.
--error_log <file> Absolute pathname of intended error log file. If absent, the Web error information will be written to standard output, unless --noscreen is specified.
--tagger_log <file> Absolute pathname of intended tagger log file. If absent, tagger service status output will be routed to standard output.
Clear the logs before startup.
Don't start up an interactive command loop.
Don't start up the tagger service.
Accept connections only from localhost or
--log_rotation_count <n>
Rotate logs on restart, and keep only n logs
Restart automatically at midnight (useful for rolling over logs)
--workspace_key <k>
Use the specified key as a workspace key. This flag is used mostly when the server automatically restarts after an error, so the user doesn't need to change the workspace key in the UI. However, it can also be used explicitly, e.g., to associate a previously-agreed-upon "password" for the workspaces.

WARNING: the key will be visible in process listings. If you want something more secure, use --workspace_key_file.
--workspace_key_file <f>
Like --workspace_key, but more secure. The key file should be readable only by the user starting up MATWeb, and should be a UTF-8 file containing the workspace key.
If --workspace_key_file is provided, remove the key file immediately after startup.
By default, workspaces only permit access from local clients. If this flag is specified, the server allows workspaces to be accessed by clients on remote hosts.
--workspace_container_directory <dir>
By default, when the user opens a workspace from the UI, she must provide a full pathname. If you provide this option, which is repeatable, and the user provides a partial pathname, the server will search in each of the candidate container directories for a workspace at the location indicated by the partial pathname. If this option is provided, the user will no longer be able to specify a full pathname, in order to circumscribe remote access when MATWeb is being run as a persistent service.
If specified, terminate any MATWeb server running on the requested port on this machine, if the current user has permission to do so.
--output_log <log>
Redirect all stray output from stdout and stderr to this log. This file should be readable only by the user starting up MATWeb, since the workspace key may be written to this log.
--as_service <dir>
Start up MATWeb as a service. This creates the specified log directory and starts up as if you specified
--log_rotation_count 7 --midnight_restart --allow_remote_workspace_access \
--supersede_existing_server --noscreen --no_cmdloop \
--access_log <dir>/access.log --error_log <dir>/error.log \
--tagger_log <dir>/tagger.log --output_log <dir>/output.log
This option is interpreted before all other command line options, so you can also specify options like --log_rotation_count or --access_log if you like. Options like --workspace_container_directory, --localhost_only, --workspace_key, --no_tagger_service are also respected.

For more details about --output_log, --workspace_key, --workspace_key_file, and --workspace_container_directory, see the section on workspace security.


Example 1

To start up the Web server listening on the default port, with a command loop and all status messages printed to standard output:



Windows native:

> %MAT_PKG_HOME%\bin\MATWeb.cmd

Example 2

To start up the Web server on port 7806, but only allow connections from the local host:


% $MAT_PKG_HOME/bin/MATWeb --port 7806 --localhost_only

Windows native:

> %MAT_PKG_HOME%\bin\MATWeb.cmd --port 7806 --localhost_only

Example 3

To start up the Web server on the default port, but write the status messages to different files:


% $MAT_PKG_HOME/bin/MATWeb --access_log ./web_access.log --error_log ./web_error.log \
--tagger_log ./web_tagger.log --noscreen

Windows native:

> %MAT_PKG_HOME%\bin\MATWeb.cmd --access_log %CD%\web_access.log --error_log %CD%\web_error.log \
--tagger_log %CD%\web_tagger.log --noscreen

Without the --noscreen flag, the Web server messages will be printed both to the files and to standard output.

Example 4

On Unix, to start up the Web server as a Unix cron job, saving logs for the previous 7 days in /etc/MAT/logs, and restarting each midnight, enter this command line in your crontab, if MAT_PKG_HOME is /usr/MAT:

/usr/MAT/bin/MATWeb --access_log /etc/MAT/logs/web_access.log \
--error_log /etc/MAT/logs/web_error.log \

--tagger_log /etc/MAT/logs/web_tagger.log --noscreen \
--no_cmdloop --midnight_restart --log_rotation_count 7

Caution: this mode is very, very lightly tested.

Example 5

Let's say you want to distribute access to some MAT workspaces to a range of annotators on a variety of machines, but you don't want to force them to remember a complex workspace key or pathname. You can specify the workspace key and the container directory for the workspaces on the command line when you start up MATWeb. (Be sure to distribute the workspace key to your annotators in a secure manner, since it's our only means of security at the moment.)


% $MAT_PKG_HOME/bin/MATWeb --workspace_key my_annotator_key \

Windows native:

> %MAT_PKG_HOME%\bin\MATWeb.cmd --workspace_key my_annotator_key \

Example 6

Let's say you want to start up the Web server as a cron job, but you don't want all the verbosity in example 4, and you also want to specify the workspace key and the workspace container directory, and you prefer a log rotation of 5:

/usr/MAT/bin/MATWeb --as_service /etc/MAT/logs \
--workspace_key my_annotator_key \
/path/to/dir/containing/workspaces \
--log_rotation_count 5

This is the same as if you had specified

/usr/MAT/bin/MATWeb --midnight_restart --allow_remote_workspace_access \
--supersede_existing_server --noscreen --no_cmdloop \
--access_log /etc/MAT/logs/access.log --error_log /etc/MAT/logs/error.log \
--tagger_log /etc/MAT/logs/tagger.log --output_log /etc/MAT/logs/output.log \
--workspace_key my_annotator_key \
--workspace_container_directory /path/to/dir/containing/workspaces \

--log_rotation_count 5