-Building GSS requires the following software installed:\r
+Short version\r
+-------------\r
+\r
+# ant install run\r
+\r
+\r
+\r
+Long version\r
+------------\r
+\r
+\r
+Prerequisites\r
+-------------\r
+\r
+Building GSS requires the following software to be installed on your system:\r
\r
- Java Development Kit version 1.6.\r
- Apache Ant version 1.7.\r
-- Google Web Toolkit version 2.0.\r
-- JBoss Application Server version 5.1.0 built with JDK 1.6.\r
-- JUnit version 3.\r
-- HornetQ version 2.0.0.\r
\r
+Running GSS requires a running PostgreSQL server for storing the system's data. Setting up PostgreSQL for gss entails configuring the database to accept connections from the application server and creating the appropriate database and user:\r
\r
-Building from the command line\r
-------------------------------\r
-\r
-Create a build.properties file with the following variables, set to the appropriate values for your system. The value of gwt.workers should match the virtual cores in your system for faster builds. For instance in a dual-core system the best value would be 2. You can experiment with increasing the value until you start to get worse build times, if you are not sure about your system's specifications.\r
+# create user gss with password 'gss';\r
+# create database gssdb owner gss encoding 'UTF8';\r
\r
-build.properties:\r
+Then, when the gss server is first launched, the database will be populated with the required schema.\r
+ \r
\r
-jboss.version=5.1.0\r
-jboss.home=/path/to/development/deployment/jboss-5.1.0.GA\r
-jboss.prod.home=/path/to/production/deployment/jboss-5.1.0.GA\r
-gwt.path=/path/to/gwt-2.0.0\r
-gwt.workers=1\r
-junit.path=/path/to/junit\r
-hornetq.path=/path/to/hornetq\r
+Installing and configuring dependencies\r
+---------------------------------------\r
\r
-Run "ant".\r
+Run "ant install" from the gss directory to download the various software dependencies (JBoss, GWT, etc.) and install the configuration files. The install task is something that will need to be executed again only if the configuration files or dependencies change. This requirement will be explicitly mentioned in the ChangeLog after a new release.\r
\r
-Alternatively, you can set them in the command line, or specify them as environment variables:\r
\r
-ant -Djboss.version=5.1.0 -Djboss.home=/path/to/jboss-5.1.0.GA -Dgwt.path=/path/to/gwt-2.0.0 -Dgwt.workers=2 -Djunit.path=/path/to/junit -Dhornetq.path=/path/to/hornetq\r
+Building and running the server\r
+-------------------------------\r
\r
-The final build artifact is the file "gss.ear" in the directory "bin", which has already been deployed to the server.\r
+Run "ant run" from the gss directory to build and deploy gss and start JBoss. Use Ctrl/Cmd-C to stop the server. If you want to rebuild and redeploy the service after having made changes to the source code, run "ant deploy" or "ant" without a task name, which does the same thing.\r
\r
+On first launch the database will be empty. If you have successfully setup Shibboleth authentication (see the "Authentication" section below) you may use existing user credentials to log into the service. If the Shibboleth IdP is itself empty, visit the following URL:\r
\r
-Running the server\r
-------------------\r
+http://127.0.0.1:8080/pithos/register\r
\r
-Before running the server for the first time, some configuration files must be installed. This can be accomplished by running "ant install" (with the already mentioned variables set, as above). Then just start JBoss with the default configuration.\r
+There you will be able to both register a new account with the service and create a new account in the configured IdP/LDAP server. See the gss.properties configuration file for more information on configuring the gss-ldap connection.\r
\r
\r
-Building from Eclipse\r
----------------------\r
+Customizing the build script\r
+----------------------------\r
\r
-In Eclipse the following User Libraries must be defined:\r
+If you want to customize the behavior of the ant script, you may want to create a build.properties file in the gss directory with the following variables, set to the appropriate values for your system.\r
\r
-GWT Dev Library (pointing to gwt-dev.jar)\r
-GWT User Library (pointing to gwt-user.jar)\r
-GWT Servlet Library (pointing to gwt-servlet.jar)\r
-JBoss 5 lib (pointing to all the jars in ${jboss.home}/lib\r
-JBoss 5 common lib (pointing to to all the jars in ${jboss.home}/common/lib)\r
+build.properties:\r
\r
-Furthermore the ant variables mentioned above must be set as well.\r
+jboss.home=/opt/jboss-5.1.0.GA\r
+jboss.args=-b 0.0.0.0 -Djboss.server.log.threshold=DEBUG\r
+gwt.workers=4\r
\r
+The value of jboss.home should be the path where jboss will be installed and run from. The value of jboss.args will get passed to the JBoss startup script when starting the service with "ant run". The value of gwt.workers should match the virtual cores in your system for faster builds. For instance in a dual-core system the best value would be 2. You can experiment with increasing the value until you start to get worse build times, if you are not sure about your system's specifications.\r
+ \r
+Alternatively, you can override the above properties using command line arguments:\r
\r
-Deploying to production\r
------------------------\r
+ant -Djboss.home=/usr/local/jboss-5.1.0.GA -Dgwt.workers=2\r
\r
-First of all, make sure the database is ready for gss. This entails configuring the database to accept connections from the application server and create the appropriate database and user:\r
\r
-# create user gss with password 'gss';\r
-# create database gssdb owner gss encoding 'UTF8';\r
+Production deployment\r
+---------------------\r
\r
-Then make sure the path to the production server is specified in build.properties (jboss.prod.home). Also make sure that the permissions in the jboss directory and subdirectories are properly set for the system user that the service will run as.\r
-Run "ant install-production" to install the JBoss configuration files for the deployment server.\r
-Run "ant deploy-production" to copy the build artifact (gss.ear) to the deployment server.\r
+First of all, modify the configuration files to suit your installation. Most importantly go through the gss.properties file and remove the testUsername value, since you probably won't need a loophole in your authentication system. Then make sure that the permissions in the jboss directory and subdirectories are properly set for the system user that the service will run as.\r
Copy the jboss init script to the proper place for the host operating system. Modify the various variables defined in the start of the run script as necessary.\r
\r
For Debian:\r
\r
You need to have Shibboleth authentication set up in order to authenticate. The first step in the Shibboleth authentication process is a redirection to a WAYF (Where Are You From) server, for selecting the Identity Provider that has your credentials. You can read more about Shibboleth here: \r
\r
-http://en.wikipedia.org/wiki/Shibboleth\r
+http://en.wikipedia.org/wiki/Shibboleth_(Internet2)\r
\r
Then point a browser to http://127.0.0.1:8080/pithos/ in order to connect to the service.\r
\r
-Alternatively, for development purposes, you can use a shortcut in the server to authenticate without Shibboleth. You have to manually initialize a user entry in the database first (using SQL insert) and then set its username in the testUsername property of the jboss\conf\gss.properties configuration file. You can find it deployed in JBOSS_HOME\server\default\conf\gss.properties. The proper URL for using in this scenario is the following, which can be also found in the GWT hosted mode launch configuration:\r
+Alternatively, for development purposes, you can use a shortcut in the server to authenticate without Shibboleth. You have to register a new account (see "Building and running the server" section above) or manually initialize a user entry in the database first (using SQL insert) and then set its username in the testUsername property of the jboss\conf\gss.properties configuration file. You can find it deployed in JBOSS_HOME\server\default\conf\gss.properties. The proper URL for using in this scenario is the following, which can be also found in the GWT hosted mode launch configuration:\r
\r
http://127.0.0.1:8080/pithos/login?next=http://127.0.0.1:8080/pithos/\r
projects / pithos / blobdiff