Getting started

This page describes how you get started with the development of SHOGun2.

It is assumed that you know the basic concepts of this projects design and you are using a Linux-based operating system with a command line interface (CLI). Furthermore, we illustrate the usage of Eclipse with an integrated Tomcat servlet container.

Checking out the sources

At first, you have to check out the sources of SHOGun2:

Go to your (Eclipse-)workspace directory...

$ cd /your/workspace/directory

... and checkout the sources from github:

$ git clone https://github.com/terrestris/shogun2.git

A new folder shogun2 should have been created. Enter the src-folder (which contains the root-pom.xml) in that directory:

$ cd shogun2/src

Building with maven

Execute

$ mvn clean install

to install all SHOGun2-artifacts to your local maven repository.

Using SHOGun2 with Eclipse

For this and next step you can alternatively use in Eclipse integrated plug-in m2e as described here.

Execute

$ mvn eclipse:clean eclipse:eclipse

to create Eclipse-.project files (and more).

If you open Eclipse now, you can go to File -> Import -> Existing Projects into Workspace and select the shogun2 root-directory (the one you've just checked out from github above).

You now should see some projects that you can import by clicking on Finish import.

In case of a successful import, dependent projects/modules should reference each other, which is very nice, because changes in Module X will immediately be available in any module that depends on Module X. For example, you could check, if the DAO-Project references the Model-project by right-clicking on the DAO-project -> Properties -> Java Build Path. In the Projects-Tab you should see an entry for the shogun2-model-project.

Generate a SHOGun2-based web application

Note: Skip this block, if you've used m2e Eclipse plug-in in the previous step.

If you have installed the maven artifacts to your local repository, you can create a SHOGun2-based webapp-project by executing the following command (ideally in your Eclipse workspace directory):

$ mvn archetype:generate \
    -DarchetypeCatalog=local \
    -DarchetypeGroupId=de.terrestris \
    -DarchetypeArtifactId=shogun2-webapp-archetype

You will be asked for some values:

• groupId: Identifies the (web-)project you are about to create. You should use a domain name you control. More info here.
• artifactId: Name of your artifact without version.
• version: The version of your artifact.
• package: The (base) package of your Java classes. You should use a domain name you control.
• webapp-name: A Name for the webapp you create (Whitespace allowed)

Confirm the creation of the SHOGun2-based webapp by entering Y.

You will now have new folder with the name of the previously entered artifactId.

Run a SHOGun2-based web application on a Tomcat (in Eclipse)

Enter the directory from the previous step and again, execute:

$ mvn eclipse:clean eclipse:eclipse

In Eclipse, you can import the generated webapp the same way as above:

File -> Import -> Existing Projects into Workspace

In case you have a tomcat integrated in your Eclipse, you can run the (imported) webapp by right-clicking the project and selecting

Run as -> Run on server

After a few seconds, a simple login form should appear. You can login to your SHOGun2-based web application with user admin and password shogun2.

Using SHOGun2 with Eclipse m2e plug-in

Alternatively to executing of mvn commands from command line you can use the in Eclipse integrated plug-in m2e to create the project in Eclipse. Please do the following steps to achieve this:

• Make right-click somewhere in Package Explorer in Eclipse and choose New... -> Other... -> Maven Project
• Adjust default workspace location and/or working set if needed (this step can be skipped)
• Select an archetype
  • Ensure that Include snapshot archetypes property is checked - so shogun2-webapp-archetype will be also shown in the list and can be chosen
• Provide GroupId (e.g. de.terrestris) and ArtifactId (e.g. momo) according to your project setup
• (If properties avaliable from archetype grid doesn't include shogun2-parent-package, restart Eclipse and do all the previous steps once again)
• Provide webapp-name for your future application (this name will be used for WAR-file lately)
• After finish the new maven project with specified webapp-name will be created in your workspace.