Installation

Configure the Git repository

  1. Fork the ESPD Git repository by clicking on the Fork button on the top-right corner of the repository page. Forking a repository allows you to freely experiment with changes without affecting the original project. Most commonly, forks are used to either propose changes to someone else’s project or to use someone else’s project as a starting point for your own idea.

  2. Create a local clone of your fork

    1. On GitHub, navigate to your fork of the ESPD Git repository.

    2. Under your repository name, click the Copy to clipboard button to copy the URL for the repository.

    3. Run the git clone <URL> command on your computer, after pasting the URL you copied in the previous step. Now, you have a local copy of your fork of the ESPD Git repository.

  3. Configure Git to sync your fork with the original ESPD Git repository. When you fork a project in order to propose changes to the original repository, you can configure Git to pull changes from the original, or upstream, repository into the local clone of your fork.

    1. On GitHub, navigate to the ESPD Git repository repository.

    2. Under the repository name, click the Copy to clipboard button to copy the URL for the repository.

    3. Change directories to the location of the fork you cloned in the previous step.

    4. Execute git remote -v to see the current configured remote repositories for your fork.

    5. Type git remote add upstream <URL> by pasting the URL you copied in Step b.

    6. To verify the new upstream repository you’ve specified for your fork, execute git remote -v again. You should see the URL for your fork as origin, and the URL for the original repository as upstream.

$ git remote -v
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

Now you can keep your fork synced with the upstream repository with a few Git commands. For more information, please see the Syncing a fork page.

Quite often people working in a team and using the same repository or upstream prefer different operating systems. This may result in problems with line endings because Unix, Linux, and OS X use LF and Windows uses CRLF to denote the end of a line. To have Git solve such problems automatically, you need to set the core.autocrlf attribute to true on Windows and to input on Linux and OS X. For more details on the meaning of the core.autocrlf attribute, see the article Dealing with Line Endings. You can change the configuration manually by running git config --global core.autocrlf true on Windows or git config --global core.autocrlf input on Linux and OS X.
Each major application version will have a dedicated branch so you can checkout the code for a particular version. The name convention adopted for release branches is YYYY.MM. The master branch contains the version currently deployed in production. The develop branch contains the code for the next version of ESPD. The gh-pages branch is reserved for documentation. If you want to be isolated from changes you should branch from master or from a specific release branch.

Building and running the ESPD application

This section goes into detail about how you can build and run the ESPD application.

Building the application

The ESPD uses Maven as the primary build system and is structured as a multi-module Maven project.

After getting access to the source code and cloning it on your computer, you can now build the project with Maven.

  1. Change directories to the location of the cloned Git repository on your machine.

  2. Perform a mvn clean package and the project dependencies should be downloaded and the espd-web and espd-docs modules should be built.

Running the application

The easiest way to run the application is with an embedded container (default is Tomcat) by invoking the main method from the eu.europa.ec.grow.espd.config.EspdApplication class in the same way as you would start a normal Java application.

  1. Perform a mvn clean package from the root folder of the project:

    1. The build should generate a WAR file at ${baseDir}/espd-web/target/espd-web.war

  2. Add the following startup parameters to you server:

    1. -Dspring.profiles.active=${your desired profile} specifies the Spring Boot profile to be used

    2. -Dted.api.user=${your TED user} where ${your TED user} is replaced by the TED API username

    3. -Dted.api.password=${your TED password} where ${your TED password} must be replaced by the TED API password

The application can be started with a shell script that can contain the following minimum configuration:

start.sh
java -Dspring.profiles.active=prod -Xms768m -Xmx768m -jar espd-web.war

Other application parameters can also be specified in exactly the same way, i.e. by prefixing them with a -D followed by the name of the parameter. You can consult the application.properties files for finding out the available options but please note that the ones specified at start-up have higher precedence than the ones specified in the .properties files.

It is recommended to set up the context path of the application when running in the embedded mode. This can be done in the application.properties file located in the espd-web project resources folder.
application.properties
# Context path of the application
server.context-path=/espd

Deploying the web application on a servlet container

The application can be deployed as a WAR file on a Servlet 3 compliant container such as Tomcat. For this, you need to package it as a WAR for the non-embedded Maven profile and provide some startup parameters on your server.

  1. Perform a mvn clean package -Pnon-embedded from the root folder of the project:

    1. The build should generate a WAR file at ${baseDir}/espd-web/target/espd-web.war

  2. The other steps are similar to the embedded server deployment mode

Using an IDE

You can also run the ESPD application from your favourite IDE by importing the project as a multi-module Maven project first.

You will need to install the Lombok plugin for your particular IDE. Lombok is a library designed to reduce Java boilerplate code through the use of annotations.
If you have problems importing the project in Eclipse try running the Maven command mvn eclipse:eclipse before the import. If after the import the Problems view display errors of type Plugin execution not covered by lifecycle configutation right-click on the error and set Eclipse to ignore the execution of the plugin.