Information [worth reading before you start]
- Wikipedia: Maven What
is Maven? What is Artifactory? What is the
- Maven: install What is an "install"?
- Maven: war What does
- Wikipedia: Tomcat Open source web server
- Wikipedia: Log4j Java-based logging utility - Why not
Installation and adjustment of the required tools
Step 1: Java SDK
Install Java SDK if nonexistent. Please install Java 1.8.
For the encryption of Spring Security we need the Java Cryptography Extensions (more precise: Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files). Download here (scroll to the very bottom) and install. If you are using OpenJDK, JCE should already be installed. You can test whether JCE is correctly installed with
$JAVA_HOME/bin/jrunscript -e 'print (javax.crypto.Cipher.getMaxAllowedKeyLength("RC5") >= 256);'
which should output "true".
Step 2: Eclipse
Download the most recent version of Eclipse JEE Please note: JEE!!! Extract, set up a new workspace and install the following plug-ins
In Eclipse via Help>Install New Software... (just copy the link of the plugin) or via update site:
- Git Plugin
- Use exactly the settings as described here! Do not go on before that!
- Eclipse Tomcat Launcher
Disable the validation of web resources.
Step 3: Git
If nonexistent install Git.
Step 4: Tomcat
A preconfigured tomcat can be found here:
Please download the zip and unpack it.
Step 5: Eclipse-Tomcat Settings
Once you got your Tomcat go to Eclipse and check Settings>Tomcat, set the Tomcat version to 9 and provide the path to the location of your Tomcat directory. Set Context Declaration Mode to Context Files and make sure that Contexts directory is
Click the subitem Tomcat Manager App and change the username to 'manager' and the password to 'password', if you use the preconfigured version of Tomcat.
On first setup of the project Maven will automatically download all dependencies needed.
Connecting to KDE network
If you are connected locally via LAN you have to do nothing. Otherwise (e.g. at home) please connect via VPN.
Hannover & Würzburg
If you are connected locally you have to do nothing. Otherwise please connect to KDE using the VPN of Kassel.
Check out the source code
For main developers with write access to the repository
Note: This includes Hiwis!
In Eclipse select File > Import > Projects from Git.
Use the repository location
firstname.lastname@example.org:bibsonomy/bibsonomy.git. We recommend to use ssh and not HTTPS since ssh should be faster.
(Windows users should use HTTPS, since ssh is cumbersome to install.)
Note: you must use your public key for authorization. If you use ssh please do not change the username (git):
Select the master branch (for now):
Click on "next" and wait some time (the checkout should take some time), afterwards click on "finish". Please import the project as a new general project.
For all other developers
Before you start, you must fork the project and than use your forked project for setup, see above for more details, just replace the repository location.
bibsonomy > misc/eclipse/bibsonomy_settings.epf you can find a Eclipse settings file with predefined Compiler and Code Format settings. Please import the file using
Import > Preferences.
Installing the root POM
Now it's time to run a Maven-install via right-click on the main project
bibsonomy then Run As>Maven build.. with goal
install -N and check the RadioButton
Skip Tests then Run.
This keeps the submodules from being built and only the root POM of the main project will be set up locally.
General steps on how to import a submodule from BibSonomy
To successfully run your version of BibSonomy you must only import the
(Later on you might work with other submodules aswell, however the import steps remain the same)
- In Eclipse File / Import / Maven / Existing Maven Projects
- Choose the corresponding module from your main project
bibsonomyas root directory
- Wait until Eclipse is finished building the workspace
If the project does not look as expected, e.g. the source folder
/src/main/javais missing, update your configuration by Right-click > Maven > Update Project .... Wait until Maven has downloaded all dependencies.
Setting up the webapp submodule
After the module is as error-free as possible, execute a
Run As > Maven build... and type 'install war:inplace' in the 'goals' input field and check the radio button 'Skip Tests'.
Right-click the 'bibsonomy-webapp' module and go to 'Properties > Tomcat'.
- Check 'Is a Tomcat project' / 'Ist ein Tomcat Projekt'
- Set 'Context-name' / 'Anwendungs-URI' to
- Set 'Subdirectory to set as web application root' / 'Unterverzeichnis, das als root der Webapplikation gesetzt werden soll' to
Click 'Apply' and then 'OK'.
Please check that the path in the
.xml (location: config directory of the tomcat) contains the correct path ending with
bibsonomy.properties file in your home dir. Add the following two lines to the file:
database.main.password = **PASSWORD** database.recommender.tag.password = **PASSWORD**
Those define the connections to the required BibLicious databases. They run on shredder and are only available in the KDE network. If you have VPN access, connect before working on BibSonomy. If you use an SSH tunnel change every occurence of 'biblicious.org:8088' to 'localhost:6033' or change 'biblicious.org' to 'localhost' in Hosts file. Use 'localhost' instead of 'biblicious.org' for your own databases. You can always find the schemes for the databases in the 'src/resources/database' folder of the respective module (clicklogger => logger).
passwords please ask your supervisor.
- You can start / terminate / restart Tomcat via the three buttons in the toolbar
Finally! - Now your BibLicious aka BibSonomy should be available via http://localhost:8080/. If you have to change different modules, please follow these instructions for every submodule.
Tips und Tricks
- Other error messages (and ways how to fixed them) are described '''on this wiki page.'''
- Tests may also be skipped. See Maven RunConfig dialog or execute
mvn install -Dmaven.test.skip
- If you change a module you have to execute a
mvn installand a
mvn war:inplacein the webapp module afterwards. Otherwise changes in the webapp will not be visible. The alternative is to use the SysDeo Dev Loader (see below).
Some submodules require a running MySQL database. It is sufficient to install a new plain mysql server, add an empty database called 'bibsonomy_unit_test' and a user who has access (including DROP and CREATE rights). The TEstcases will automatically drop and re-create the database tables. Ask your supervisor if you do not want to install your own MySQL server. To configure the connection (host, username, password) we use Maven profiles. You should add a new profile to your Maven settings.xml (
<settings> [...] <profiles> [...] <profile> <id>bibsonomy-test-settings</id> <properties> <database.main.url>jdbc:mysql://localhost/bibsonomy_unit_test?useUnicode=true&characterEncoding=utf-8&mysqlEncoding=utf8</database.main.url> <database.main.username>YOUR_USER_NAME</database.main.username><!-- change! --> <database.main.password>YOUR_PASSWORD</database.main.password><!-- change! --> </properties> </profile> </profiles> <activeProfiles> [...] <activeProfile>bibsonomy-test-settings</activeProfile> </activeProfiles> [...] </settings>
Currently the following modules require database configuration (with their required property keys):
Good to know
- We use a Jenkins-service at https://jenkins.cs.uni-kassel.de which rebuilds the BibSonomy-project on commits and runs all the tests. If a problem occurs an email will be sent to the developer address. If everything passes, the new version will be published on gromit)
Version Control System
We use a distributed version control system which is slightly more complex to use than CVS or SVN. Therefore, please read How to use the version control system carefully!
There are two plug-ins which simplify the interaction between Eclipse and Tomcat
Sysdeo Tomcat Launcher
- Has to be installed individually
- Is quite old and only loosely coupled with Eclipse
- Startet nicht bei jeder kleinen Änderung an der Webapp den Tomcat
neu und triggert daher unser Memory Leak nicht so
schnell. Erst nach einem
mvn install war:inplacegibt es ein Redeploy. Does not restart the Tomcat server on every small change and thus will take longer to trigger the MemoryLeak
- The last version is from 2007 and still works. The plug-in is thus pretty simple.
Works with the following versions of Tomcat:
Does not work with the following versions of Tomcat:
- Comes with WTP which has to be installed anyway.
- Provides excellent Eclipse integration.
Instruction: Install the adequate Server Runtime in Eclipse:
- Window > Preferences > Server > Installed Runtimes > Add...
- Select Apache Tomcat 7 and provide its installation directory
Read Eclipse Tips and Tricks.
This setup guide only covered the basic setup of the development environment, for more advanced setup see this page.