ECT Webstart (v2) User Guide
Chris Greenhalgh, 2005-04-21
Getting ECT
The webstart/Installation support for ECT has now been substantially
revised. I really really want people to start using it :-)
Either:
- check ECT out of CVS, build it, and click "ect.jnlp" in "install"
directory or "runWebstart.bat" in the "webstart" directory; or
- download a zipped version of the webstart directory from someone
else and click on the "runWebstart.bat" (or edit "ect.jnlp" and change
the codebase and download URLs to point to the location of your
unzipped directory, and click "ect.jnlp"); or
- use a webstart version directly from the web, e.g. http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/docs/ect/webstart3/ect.jnlp
Building from CVS
- Currently still hosted at the MRL, configure your CVS client with
CVSROOT ":pserver:anonymous@dumas.mrl.nott.ac.uk:/mrl/src/cvsroot" and
check out the "module" "Equator/equip4j/infrastructure"
- Open a command shell, and set your environment to run ANT and
JAVA SDK (you'll need both), e.g. on windows:
- set
ANT_HOME=c:\ant\apache-ant-1.6.1 (for example)
- set
JAVA_HOME=c:\j2sdk1.4.2_07 (for example)
- set
PATH=%ANT_HOM%\bin;%JAVA_HOME%\bin;%PATH%
- Build it with ant:
- ant
This will create a "webstart" directory with "runWebstart.bat" and
"ect.jnlp" in it, and an "install" directory with (effectively) a
simple installation with various batch files to run individual
sub-applications.
The Boot Manager
New Installation/first use
If you start ECT using webstart (rather than the "runWebstart.bat"
script) then webstart will load and check the core libraries; to do
this it will ask if you are prepared to accept the (currently anonymous
self-signed) certificate that was used to sign these files. If you say
"no" then it won't run ECT :-)
The Boot Manager will now appear. It has three tabbed panes, showing:
installations that this maching has previously been part of;
installations that are running at the moment on the local network; and
the option to create a new installation (or join an installation
running on a remote network). Go to this third "New" pane:
Normally you will start by making a new master installation, rather
than joining a remote installation, so:
- Enter a short name for your installation in the upper text field.
- (optionally) change the installation secret to something more
memorable (you need to know this secret in order to access the
installation, e.g. to add another machine or to edit it from another
machine).
- Click "Create New Installation..."
- (optionally - probably not this time!) change the installation's
download URL - this is the URL from which the installation will
download components and other resources each time it is started. If you
have started from the web then this will be an HTTP URL of the site
that you are running it from; if you are running a CVS build locally
then this will be a local fiile URL of the "webstart/download"
directory.
- Hit "OK"
The boot manager now starts the installation master, which begins by
checking that there isn't already a master for that installation on the
local network:
This takes about 30 seconds; if you are sure that there is no other
local installation of the same name then you can close the window to
abort the discovery process. Note that the disocery process for a slave
(i.e. a host joining an existing installation) is (a) faster, taking a
couple of seconds and (b) essential - if you cancel the discovery
dialog for a slave then you will just be returned to the boot manager.
The Installation Manager should now appear - see below.
Previous installation
If the machine has previous been part of an installation the boot
manager will automatically restart this installation when it is first
started or after the installation manager is terminated. It presents
this dialog giving you a chance to prevent this autostart ("cancel" or
close window) or expedite it ("OK"):
If you cancel then you will see the list of installation previously
known by this boot manager:
Select a previously joined master or slave installation and click
"Restart Installation". Note that you won't be allowed to restart a
slave of a local installation
if the corresponding master is not currently running.
Joining an existing local installation
Select the "Discovered" pane of the Boot Manager; you will see a list
of master installations which are known on the local network with an
indication of whether they are currently running:
Select a running one which you wish to join; you will be prompted to
enter that installations shared secret. If it is incorrect then
installation secret dialog will remain visible (close it to return to
the boot manager if you change your mind about joining that
installation). If you enter the correct shared secret then the
installation manager will be started, but as a slave to that master
(see below).
Joining an existing remote installation
Discovery only works on a local network, so if you want to have an
installation with master and/or slaves on different networks then you
will need to use the "Join Remote Installation..." option of the Boot
Manager's "New" pane. You need to know:
- The name of the remote network - enter it as the name of the
installation to "create"
- The shared secret - enter it as the Installation secret
- The webserver URL of the remote installation master - after you
click "Join Remote Installation..." you a
small dialog will prompt you to enter this. You can obtain this from
the master installation manager's "Export Webserver URL" option (see
below), but note that the presence of firewalls may complicate this
(see below).
- The dataspace URL of the remote installation master. Similarly,
you can obtain this from the master installation manager's "Export
Dataspace URL" option (see below), but note that the presence of
firewalls may complicate this (see below).
When joining a remote installation the discovery step is omitted and
you will go directly to the installation manager screen. This will only
start to download components and files and start any containers when it
successfully connects to the installation master. You will also be
unable to start any tools (editor, configuration manager) until you
have successfully download from that master at least once. If in doubt,
check the console output for hints...
Firewall issues
If there are one of more firewalls between the master and a client then:
- the firewall will have to allow the clients to contact the
master's dataspace, normally on port 9123, TCP, originated by the
client.
- In addition, if the master is
behind a NAT firewall then the master dataspace URL given to the remote
clients should normally have the IP address of the NAT router itself
and possibly a different external port, rather than the server machine
(check with the firewall administrator).
- the firewall will have to allow the client to contact the
master's webserver, normally (at present) on port 8088 TCP.
- Similarly, if the master is behind a NAT firewall then then enter
the external version of the
master's webserver URL in the "Create remote slave" dialog.
The Installation Manager
Once discovery has completed (or been cancelled, in the case of an
installation master) then the Installation Manager window will appear:
(Note: initially the container will not be running, and the status
at the bottom will be different and changing)
The Installation Manager will start by trying to download components
and other resource files. As it downloads files it will show a progress
bar for each one that is actually downloaded. It will only download a
new copy of a file that it already has if the size has changed or the
remote file has a newer modification time than the last copy downloaded.
Once files are downloaded the installation will more any old log
files to a history folder, and in the case of a slave installation
upload them to the history folder on the installation master.
Once logs are uploaded the installation will (normally) start a java
component container. This can take a few seconds to start up, and
eventually displays the container GUI (see below).
The Installation is now ready to host components.
The Installation Manager allows you to:
- start a graphical editor on this machine ("Graph Editor" button)
- this allows you to create components, configure them and connect them
together to create applications - see below.
- start a configuration manager on this machine ("Configuration
Manager" button) - this allows you to clear out an application, save an
application (a "configuration" of components), and re-load a previously
saved application
- terminate the installation, returning to the boot manager
("Terminate Installation" button)
- stop any containers on this machine ("Stop all" button)
- stop and re-start any containers on this machine ("(Re)start all"
button) - can be useful if a component has crashed and/or crashed a
container (e.g. not responding at all)
- check the installation's shared secret ("Export shared secret"
button) - useful when you want to add another machine to the
installation
- check the installation's download URL ("Configuration" menu,
"Export Download URL...") - useful if you want to check where
components are being downloaded from (note that a slave machine always downloads its components from
the installation master, irrespective of where the master downloads
from) (may work only on master)
- check the installation's dataspace URL ("Configuration" menu,
"Export Download URL...") - useful if you want to add another machine
to the installation which is on a different (not local) network (may
work only on master)
- check the installation's webserver URL ("Configuration" menu,
"Export Webserver URL...") - useful if you want to debug the
installation, of make another installation obtain its components from
this one (only on master)
- view the installation's console ("Debug" menu, "Show console...")
- ask slaves of this installation to send their latest log files to
the master ("Debug" menu, "Request slave file upload") (only on master)
- note that this could take a few seconds, or more if there is a lot of
information
Java Component Container
The Java Component Container is started by the Installation Manager.
When first started it determines which component types are available
locally. This can take tens of seconds, during which a small start-up
dialog is displayed. Once it has completed this, possibly
re-instantiating components that it had previously been hosting, the
main window appears:
This allows you to view the console log ("Help" menu, "View console
log") or terminate the container (close window). Most problems with
components can be diagnosed (to some extent) by checking the console
log. Note that the console log is also written to disk, and uploaded to
the installation master's history archive by the installation manager
each time it restarts, or on request.
Graph Editor
Capability Browser
...
Component Editing Canvas
...
Configuration Manager
...
Known Problems
- Shahram's Dynamo components do not work with webstart at present
(unknown)
- Only works on windows at present (boot manager unable to start
installation manager due to windows-only workaround of java exec
problems)
Other Operational Considerations
Disk usage
By default console and dataspace logs will be kept on the master, moved
to the history hierarchy each time an installation manager restarts.
These can get quite large. If you don't need them then delete them
periodically. If you do need them, e.g. for analysis, then move them
away periodically e.g. to CD. Note: it may be best to stop the
installation while you do this.