Installation
Guide for Corga Version 2.0
[$Id: InstallationGuide.html,v 1.11 2006/07/21 12:12:08 jacomac Exp $]
Contents
Prerequisites
It is assumed that you have already installed some
things on your server:
A servlet container where the web
application can run in. Corga has been tested in Tomcat 5.0.28 (JDK
1.4/1.5), both on SUSE Linux 9.3 and Windows XP SP2
You should have access permission to an SMTP
server that takes care of sending out emails.
Quick Start
The distribution WAR file is nearly ready to use. You
only need to dump it into your webapps directory of the servlet
container, configure a user for the admin pages and do some
adjustments for the init parameters of the initServlet in the
web.xml. Once you have your corga instance running, it is recommended
to also take some measures to protect your data from abuse.
Put the war file in your webapps folder
and let the container extract this compressed archive. For the
following we consider that you have installed the web app at
${webapproot}.
Register the preconfigured database shipped with Corga as
a service (on Windows) or hook in with run level editor (on Unix)
and start the database.
All stuff related to the preconfigured Hypersonic SQL database
(hsqldb.org) can be found in
the folder ${webapproot}\WEB-INF\built-in-db.
On a Windows machine (XP/ME/2000), you can just
double-click on the service install script hsql_service_install.bat
to register the database server as Windows service and start it. On
Unix, use the runServer.sh script, embed it in a
start/stop script in the /etc/init.d directory and
activate it in the desired run levels.
Edit the parameters in
${webapproot}\WEB-INF\web.xml:
You need to set the following parameters of the IniServlet in
order for the web application to work properly:
closing_date1: The date when until
when the paper submissions need to be submitted via corga.
dbURL: The JDBC URL for the
database server, including the database name (default: corgadb (the
alias for CorgaDB_2)). For HSQL, the
deaulft database, this corresponds to:
jdbc:hsqldb:hsql://localhost:9006/corgadb
(“localhost” should be replaced with
the server's real domain name to allow the use of the programme
generator from another machine).
mailAddressAdministrator: The email
address of the person in charge of the conference organisation.
name_of_conference: The name of the
workshop / conference.
place_of_conference: The place
/venue where the workshop / conference takes place.
time_of_conference: The date of the
workshop / conference.
name_of_organizing_institution: The
name of the institution organizing the workshop and which is
responsible for data protection of the conference participant's
data.
notification_of_acceptance: The
date by when the organisers promise to let paper submitters know
about the acceptance or rejection of their working paper.
paymentMethods: The payment methods
that you intend to accept for the registration, each entry separated
by a comma. Hereby "Invoice" is a key word and when being
used and being chosen at a registration, the participant
automatically receives a PDF invoice along with his confirmation
email. If you leave this blank, it is assumed that there is no
registration fee.
registrationFee: If you have
specified paymentMethods, you should provide the information, how
much the normal registration fee is, including the currency.
registrationOptions: An enumeration
of extra questions you would like to ask at registration time, again
separated by commata. There can be up to 5 questions. The answers
cannot be changed: it is either yes, undecided or no. if you leave
this blank, it is assumed there are no registration options.
smtpServer: the name of the mail
server you intend to use for sending out the generated emails.
deploymentUrl: The Url this web
application itsself is deployed at. This information is currently
needed for the programme publisher utility only.
In order for the changes to take effect, you may need to reload
the init servlet by invoking http://${your_server}/corga/init.
Now or later, but before being able to assign
reviewers to papers, you will need to set up the reviewers. The
system administrator as well as the not-so-technical conference
organiser can do that via the administrative web interface at
/admin/: click the link "see available reviewers"
and then push the button "create reviewers" at the bottom
of the page (importing CSV data (several entries divided by a
carriage return, syntax per line: hisFirstName; hisLastName;
hismail@somedomain.org).
Congratulations, now you have set up a fully
functional instance of corga for your conference! Still, we
recommend that you enhance security by following the advice in the
following section.
Securing your Instance of Conference Organizer
Change the user for the admin pages
If you have used a new tomcat
installation, you will have a default user “tomcat” with
password “tomcat” that can access the admin pages. This
world known user should be changed to rpotect your data. There are
several ways for doing that. The easiest standard way is to edit the
tomcat-users.xml file in the <%CATALINA_HOME%>/conf directory.
The central configuration in corga (web.xml) offers per default the
role "corga-admin". Activate this role by replacing * with
“corga-admin” in the <auth-constraint>
directive of the web.xml. If you don’t know
how to create a user for that role, I recommend the following how-to
pages by Apache:
http://tomcat.apache.org/tomcat-5.0-doc/realm-howto.html#MemoryRealm
Change the passwords for the database users
corga_user and sa
For this, go to the hsql db directory
${webapproot}\WEB-INF\built-in-db and
start the manageDB utility. This will start a graphical user
interface for administering the hsql db corga uses. In the SQL
window state „ALTER USER corga_user SET PASSWORD
myNewPassword“. Do the same for sa and don't forget to adopt
the changes in the web.xml and the manageDB script you are currently
using.
Activate SSL, at least for the
admin pages
The use of SSL for encryption of the communication channel of the
web app is encouraged for improved confidentiality. When using Tomcat
5.0, see here
for more details on SSL activation in Tomcat. Once SSL is
activated for the servlet container, it is recommended to set the
<transport-guarantee> value to CONFIDENTIAL in order to force
the use of SSL.
Important: the /admin/ subdirectory is
foreseen to be password protected. Although this fact is configured
already in the web.xml as a security constraint, you will have to
setup your user/password combination in the server’s
environment, depending on your set up (see above if you are using a
Tomcat Server).
Optional: Setting up another database
From Corga version 2.0 onwards, you can use the
preconfigured database that corga has been shipped with. The rest of
this section is only needed, if you want ot use another SQL database.
Before running the setup SQL script, there are 3
things an administrator of the database server has to do:
Create a new database, e.g. "CorgaDB"
Create a new SQL Server login called
"corga_user". If you choose to use another name, you will
have to search and replace the string "corga_user"
throughout the SQL script mentioned below with whatever login you
decide to use.
Add the freshly created user to the newly
established database and give him read and write permissions in
there.
In the subfolder "database-setup" within the
distribution package you will see all the SQL setup scripts:
For MS SQL, use the file corgaDBmssql_complete.sql,
which you can just paste into the Query Analyzer.
For MySQL, use the file corgaDBmysql_complete.sql
and import it either from the command line or paste it into your
client tool (e.g. in phpMyAdmin) as a regular SQL query.
To renew the already ready-to-use HSQL databse, you could use
the script corgaDBhypersonic_complete.sql, together
with the manageDB utility in the WEB-INF/built-in-db
subfolder (as said, normally not needed).
Run it and the corga database structure will be set up in your database.
Now the database is ready to use.
All settings in web.xml
Here is a complete listing of the parameters that are
set in the web.xml and a short explanation for each:
dataAbstractionLayerClass: Currently
there are two choices regarding which Class to use. For HSQL and MySQL:
corga.workshop.db.CorgaDBstandardSql and for MS SQL:
corga.workshop.db.CorgaDBmssql. HSQL version is the
default. Although only lightly tested
corga.workshop.db.CorgaDBstandardSql should be fairly easy to adapt to support other DBs,
as proprietary, special functions have been avoided where possible.
The factory is then instantiating exactly this class, using the
driver specified with the jdbcDriver parameter.
dbLogin: default is corga_user, but
you may of course change that here. But then you will have to change
the sql set up script accordingly as well (or do it manually which
is quite a bit of work).
dbPassword: The password you have
set for the corga_user
dbURL: The jdbc URL for the
database server, including the database name (default: CorgaDB). For
HSQL (default) this corresponds to:
jdbc:hsqldb:hsql://localhost:9006/corgadb (or
for in-process mode:jdbc:hsqldb:${webappRoot}/WEB-INF/db/CorgaDB_2jdbc:jtds:sqlserver://localhost:1433/CorgaDBjdbc:mysql://localhost/corgadbdbURLjdbcDriverdataAbstractionLayerClass${webappRoot}webappRoot
deploymentUrl: The Url this web
application itsself is deployed at. This information is currently
needed for the programme publisher utility only.
fileuploadDestinationFolder: The
default here is "submitted_papers", which is a subfolder
that already exists. If you change the value make sure that the
folder actually exists. In any case, double check whether the
servlet container has write permissions for the file upload folder.
fileuploadTemporaryFolder: The
physical path to a directory, where the uploaded files can be stored
temporarily before they are moved to their final destination. Again,
on windows you should make sure that you escape the backslashes
(i.e.\\). A frequently used place is "/tmp/" on Unix and
"C:\\tmp\\" on Windows.
jdbcDriver: Put here the Java Class
that implements the JDBC driver interface fpor the given interface.
For HSQL that is (default): org.hsqldb.jdbcDriver, for
MS SQL: net.sourceforge.jtds.jdbc.Driver, for MySQL:
com.mysql.jdbc.Driver
mailAddressAdministrator: The email
address of the person in charge of the conference organisation.
name_of_conference: The name of the
workshop / conference.
name_of_organizing_institution: The
name of the institution organizing the workshop and which is
responsible for data protection of the conference participant's
data.
notification_of_acceptance: The
date by when the organisers promise to let paper submitters know
about the acceptance or rejection of their working paper.
paymentMethods: The payment methods
that you intend to accept for the registration, each entry separated
by a comma. Hereby "Invoice" is a key word and when being
used and being chosen at a registration, the participant
automatically receives a PDF invoice along with his confirmation
email. In future versions "Credit Card" will probably also
be made a keyword with a special process connected to it. If you
leave this blank, it is assumed that there is no registration fee.
place_of_conference: The place
/venue where the workshop / conference takes place.
registrationFee: If you have
specified paymentMethods, you should provide the information, how
much the normal registration fee is, including the currency.
registrationOptions: An enumeration
of extra questions you would like to ask at registration time, again
separated by commata. There can be up to 5 questions. The answers
cannot be changed: it is either yes, undecided or no. if you leave
this blank, it is assumed there are no registration options.
showAllParameters: This is a
Boolean flag (true/false) for debugging purposes only. When set to
true you will be able to monitor the values of the context, session
and request parameters. They will be displayed on each, web page
then.
webappRoot: The physical, 'real'
path to your webapps directory. Can usually be left blank. Could
need to be set when working inside an integrated development
environment. When specifying, make sure on Windows that you escape
the backslashes (i.e.\\) and that the path ends also with a path
separator (win: \\ unix: /).
The WAR file also includes the Javadocs in the
subdirectory /doc/, the JUnit test cases in /test/ and the rest of
the java source code in /src/. It is recommended to remove these
directories when having the web app in production use.
Some things about the Programme Generator functionality
The Graphical User interface, available as Java Web Start
Application, is currently only fully usable with the default
distribution and with MS SQL Server (exchanging hsqldb-1.8.jar with
jtds-1.2.jar in the JNLP file template in the templates folder), but
then you will need to make sure that your desktop can directly access
the DB Server, which in some cases may be blocked by a firewall
(default port 9006 in HSQL, can be altered in server.properties).
If you do not want to use the programme generator and do not want
to expose the db directly to the outside at all, you can switch to
in-process mode, specifying
jdbc:hsqldb:${webappRoot}WEB-INF/built-in-db/CorgaDB_2 as
dbUrl (see the hsqldb
documentation for more details).
Customization
The Web Layout
In the root directory of the web app
there are three files: header.jsp, footer.jsp
and a CSS stylesheet referenced in the header file. They control most
of the layout, so that the layout can be centrally changed for all
web pages in Corga. There are a few styles that should be defined:
"TD.even" and "TD.uneven": these two styles let
you better distinguish the rows in a table. ".Footnote":
this style class is for all remarks, comments, hints etc.
The
templates for mails, invoices and badges
In the subfolder /templates/ you will
find all the templates that are being used for the generation of
emails, invoices and badges for the participants. The email templates
are plain ASCII text, while the rest is xsl-fo syntax. For
information on the XSL-FO syntax, see
http://xml.apache.org/fop/fo.html.
All templates have in common that they contain placeholders for the
dynamically altered data. These placeholders start and end with two
double crosses (##). Please make sure that you don’t accidently
erase them.
Interface for Prefilling Registration Form
with External Data
There is an interface for
prefilling the registration form with external data, which is useful
when you have the needed user data already in some other application.
This funcionality is provided by the class
corga.workshop.registration.ExternallyPrefilledRegistrationFormAction
and is reachable by posting to the URL
/registration/externally_prefilled_registration. This
Servlet listens to HTTP POSTS and prefills the registration form
accordingly. The following variables are accepted:
"Email", "LastName", "FirstName",
"Salutation", "Title",
"Institution_Company",
"Institute_Department", "Street_PostBox",
"PostCode", "City",
"Country", "Phone", "Fax".
An example HTML is provided at
${webapproot}registration/prefilled_registration_form_example.html
(usually you would provide them as hidden params though).
