trackr is an application to track petty much everything that is going on in your company. Keep track of vacations, sick days, invoices and many more.
trackr comes with a Java-based backend and a frontend written in AngularJS. This project is the Java/Spring based backend, a stateless REST API with either OAuth2 or basic authentication.
You can read all about trackr in our developer blog:
- Architecture and Backend
- Testing
- Mail Approvals with Spring Integration
- Frontend
- File Downloads with AngularJS
- Processes and Tools
For the API documentation just go here. There is also a Vagrant project building the whole application over here.
If you just want to mess around with the API a bit the default configuration is very sensible and has no external dependencies (well, except Java).
If you have gradle, just run
gradle run
If you don't have gradle and want to use the wrapper run
./gradlew run
# or
gradlew.bat run
If you want to start from your IDE, i.e. for debugging open the class Trackr and start the main method.
To verify it works you can use curl. The users don't have a password in this configuration, so just press enter when curl asks for one. If you don't like the usernames change them in import.sql.
curl --user moritz.schulze@techdev.de localhost:8080
The default config uses port 8080, if that is used on your system you can add
server:
port: $port
to the top of the application.yaml and choose a port that you want for $port.
trackr has a lot of Spring profiles to add/switch features.
| profile | description | notes |
|---|---|---|
| in-memory-database | uses a H2 database, creates the schema with hibernate | excluse with real-database |
| real-database | uses a configurable database, executes flyway | exclusive with in-memory-database |
| http-basic | protects the API with HTTP basic authentication | exclusive with oauth |
| oauth | protects the API as a OAuth2 resource server | exclusive with http-basic. Database for OAuth2 tokens needed. |
| granular-security | roles and per endpoint security | |
| gmail | sends mail with Gmail and enables mail receiving | when off, does not receive mails and uses a logging mail sender. |
| dev | initialize the database with data.sql | |
| prod | Just some different settings for our production env |
Take a look in the application.yaml to see what properties these profiles need.
The default profiles are in-memory-database,dev,granular-security,http-basic. If you want to use other profiles, there are several possible ways.
- You can change the
spring.profiles.activevalue in application.yaml - If you use
gradle runyou can prepend (example)SPRING_PROFILES_ACTIVE=dev,gmail,real-database. You can also use this to overwrite e.g. the port withSERVER_PORT=8000. - If you run from your IDE, you can add
--spring.profiles.active=dev,gmail,real-databaseas program arguments to the run configuration.
Please refer to the Spring Boot Reference for more information.
The oauth profile marks the trackr backend as a OAuth2 resource server, that means access is only possible with a valid access token issued by an authorization server. We use a JDBC token store, so valid tokens need to be put there. Please take a look at our (soon to be open sourced) techdev portal to see how we do this.
When this is not selected, to access the API the user needs to be authenticated. With granular security the access to some endpoints depend on the role of the user or even the id of the user. In trackr, the id of a user is the email address of the belonging employee.
When the oauth profile is switched off, all users have the role ROLE_ADMIN. When oauth is on, the roles must be stored in the access token.
Take a look at the @PreAuthorize and @PostAuthorize annotations in the code to see what this will activate.
Just run
gradle build
(or use the wrapper if you don't have gradle installed). The JAR file will be in build/libs and can just be run with java -jar. The application.yaml file has to be in the
working directory where the java command was issued.