Getting Started
Tooling
The following tooling is recommended.
You may use alternatives but don't expect too much support from us. Please contact us if you're convinced that you have a better tooling environment.
- JDK 8 (latest version)
- Maven (latest 3.x version)
- Java IDE
- Angular IDE
- IntelliJ (latest version)
or - Visual Studio Code
or - any other Editor like Notepad++
- IntelliJ (latest version)
- Git Client
- Command Line Interface (CLI)
- Cmder With git-for-windows (Windows)
- Use your package manager to install "git" (Unix)
- Graphical User Interface
- Git Extensions (Windows)
or - Source Tree (Windows)
- Git Extensions (Windows)
- Command Line Interface (CLI)
- Node.js (version 6.x)
Optional
- REST Client (to call the backend manually)
- Postman (see backend/Educama-Backend.postman_collection.json)
Source
Checking out the code
- Create an account on https://github.com/
Create a remote fork of https://github.com/Educama/Showcase
Fork A Repo (Github Help)
Install Git
Create a local clone
git clone https://github.com/<yourname>/Showcase.git
Create a remote for the upstream project so that it is later easier to retrieve changes from the main repository.
cd Showcase git remote add upstream https://github.com/Educama/Showcase.git
Compile and start the application
Backend
mvnw
We're using the Maven Wrapper (https://github.com/shyiko/mvnw#usage) here so must not install Maven first.
Use it just like you would use mvn, e.g. ./mvnw clean install
. It will automatically download and install Maven if needed.
Pre-Requisites
Set JAVA_HOME to a Java 8 JDK
Hint for Windows
Computer > Properties > Advanced Settings > Environment Variables > System Variables
Step | Linux | Windows |
---|---|---|
Change into the backend directory | cd Showcase/backend | cd Showcase\backend |
Compile and Run Unit Test | ./mvnw clean install | mvnw.cmd clean install |
Run the application locally | ./mvnw spring-boot:run | mvnw.cmd spring-boot:run |
The backend landing page is accessible at http://localhost:8082 in a browser. Usually, you will use the frontend (see next step) to access the backend. However, the landing page of the backend lists some interesting URLs.
If you have a Camunda Enterprise Edition License key you can integrate the Camunda EE Cockpit App. Configure the file "~./m2/settings.xml" as follows (or merge it into the existing file if it already exists):
<?xml version="1.0" encoding="UTF-8"?> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <servers> <server> <id>camunda-bpm-nexus</id> <username>{to be filled}</username> <password>{to be filled}</password> </server> </servers> </settings>
Then you can build with
./mvnw clean install -P enterprise
in the directory "backend" the full package with the Camunda EE Cockpit App.
API Gateway
Step | Linux | Windows |
---|---|---|
Change into the API Gateway directory | cd Showcase/api | cd Showcase\api |
Compile and Run Unit Test | ./mvnw clean install | mvnw.cmd clean install |
Run the application locally | ./mvnw spring-boot:run | mvnw.cmd spring-boot:run |
Frontend
Pre-Requisites
- Install Node.js and update PATH to include the "bin" directory of the node installation
- Install Gulp Command Line Interface with "npm install --global gulp-cli"
Step | Linux | Windows |
---|---|---|
Change into the frontend directory | cd Showcase/frontend | cd Showcase\frontend |
Download node packages (dependencies listed in package.json) | npm install | npm install |
Build the application | npm run build | npm run build |
Run the developer version locally
| npm run serve | npm run serve |
Node.js
File changes (type script files and sass files) will be recognized when the developer version is running. TypeScript and SASS files will be converted automatically and the browser is updated.
Flight Information Service
mvnw
We're using the Maven Wrapper (https://github.com/shyiko/mvnw#usage) here so must not install Maven first.
Use it just like you would use mvn, e.g. ./mvnw clean install
. It will automatically download and install Maven if needed.
Pre-Requisites
Set JAVA_HOME to a Java 8 JDK
Local MongoDB on port 27017
Hint for Windows
Computer > Properties > Advanced Settings > Environment Variables > System Variables
Step | Linux | Windows |
---|---|---|
Change into the flightinformation directory | cd Showcase/services/flightinformation | cd Showcase\services\flightinformation |
Compile and Run Unit Test | ./mvnw clean install | mvnw.cmd clean install |
Run the application locally | ./mvnw spring-boot:run | mvnw.cmd spring-boot:run |
After these steps the Flight Information Service is running at http://localhost:8083 but there is no content to visualize. In the next steps the airport, airlines and flight connections data got to be imported.
Step | |
---|---|
Upload Airport Data | Go to http://localhost:8083/csvUpload and upload file airport.csv from directory Showcase\services\flightinformation\src\main\resources\data |
Upload Airline Data | Go to http://localhost:8083/csvUpload and upload file airline.csv from directory Showcase\services\flightinformation\src\main\resources\data |
Upload Connection Data | Go to http://localhost:8083/csvUpload and upload file flightconnections.csv from directory Showcase\services\flightinformation\src\main\resources\data |
Acceptance-Tests
Before starting the acceptance tests make sure you have already built the backend and frontend version (as described above).
Please close any Firefox open on Windows before starting the tests. Otherwise the test execution will fail because the user profile is already in use.
- Install/Unzip Portable Firefox in Version 42
- Run the Tests:
Unix:cd Showcase/acceptance-tests
./mvnw clean verify -Dwebdriver.firefox.bin="PATH_TO_FIREFOX/firefox-bin"
Windows:cd Showcase\acceptance-tests
mvnw.cmd clean verify -Dwebdriver.firefox.bin="PATH_TO_FIREFOX\FirefoxPortable.exe"
The results can be viewed in a browser by opening Showcase/acceptance-tests/target/site/serenity/index.html after having executed the tests.
Open Project in IDE
The repository contains three main directories which can be edited using an IDE.
Directory | IntelliJ | Eclipse |
---|---|---|
frontend | File → Open → Select Directory of Showcase/frontend | Not recommended, no good plugin |
backend | File → Open → Select Directory of Showcase/backend | File → Import → Maven → Existing Maven Projects → Select Directory of Showcase/backend/pom.xml |
acceptance-tests | File → Open → Select Directory of Showcase/acceptance-tests | File → Import → Maven → Existing Maven Projects → Select Directory of Showcase/acceptance-tests/pom.xml |
Eclipse
If you use Eclipse for Java Development then please configure it to use spaces instead of tabs:
- Click Window→ Preferences
- Expand Java→Code Style
- Click Formatter
- Click the Edit button
- Click the Indentation tab
- Under General Settings, set Tab policy to:
Spaces only
- Set an explicit Profile Name at the top of the dialog (this enables the OK Button)
- Click OK to apply the changes.
IntelliJ
The run configuration of npm project does not show up in the run dashboard of IntelliJ by default. If you want to seem add them to the available configurations:
- Go to "Run" → "Edit Configurations"
- Select "Defaults"
- Under "Configurations available in Run Dashboard" press the plus sign
- Choose "npm" from the dropdown
IDEA Checkstyle Plugin
We are using Checkstyle to ensure a high quality of code. Checkstyle is part of the build process if you have not fullfiled all requirements of checkstyle you will get errors.
To avoid building the project a lot of times to resolve Checkstyle errors you can install and use the Checkstyle-IDEA Plugin.
Make sure to configure the right version of checkstyle in the settings of the Plugin (File/Settings/checkstyle). At the moment we are using Version 6.11.2
Updating the local working branch with upstream changes
To fetch upstream changes and rebase your locally commited changes against the upstream changes:
git pull --rebase
If you don't care about your locally commited and uncommited changes:
git fetch upstream
git reset --hard upstream/master
Contribution
You want to contribute a change? Please read the Contribution Guide first!
Documentation
- The documentation is hosted at http://educama.org
- If you wish to contribute you may create an account be clicking on "Sign up" on the top right hand side of the page. Preferably, select a user name like "firstname.lastname".
- Confirm the registration mail sent to you.
- Add a profile picture
- Click on the drop down on the top right
- Select menu entry "Profile"
- Select section "Picture
- Upload a photo
- Optional: You may wish to register yourself as watcher to the documentation space of Educama, so that you are notified by e-mail about changes. To do that click on "Watching" on the top right hand corner and select "Watch all content in this space".
Ticketing System
- The ticketing system is hosted at https://educama.atlassian.net/browse/ECM
- If you wish to contribute please use the same account as documented in the section "Documentation" above.
Your First Task
You want to start hacking? Have a look at our simple and bite-sized tasks with the label "SimpleTask".