Justification: Kotlin and Spring Boot are a productive combo, but it takes significant setup to get past all of the configuration.
Goal: an example project that can be forked to save significant time in creating a headless Kotlin + Spring Boot API.
Current version: v0.2.4
Why "Ischia?" It's a cool island.
- Modular Gradle build that separates domain classes, business logic, and web concerns
- Fast restart time after initial build, even for large/complex projects
- Incremental Kotlin compilation
- Lightning-fast test iteration cycles inside modules
- Embedded servlet container and runnable jar
- Type-safe config values
- Only the topmost web layer depends on Spring Boot
- Kotlin 1.7.10
- Java 11 (or Java 8)
- Spring Boot 2.7
- Spring Security 5.7
- Github OAuth2
- JPA and Hibernate
- Mariadb JDBC connector
- Spring Docs
- Embedded Jetty servlet container
- SLF4J with Jetty Util Logging
- JUnit + Mockito (testing)
- Liquibase (database migrations)
Requirements:
- Java JDK 11
- MariaDB (10.4.11 recommended) or MySQL (requires additional configuration)
The project is missing several configuration values which you must set up before it will run for the first time.
From the project root, run the following commands to copy the template application-dev.properties.sample
and application.properties.sample
to ones that can be used by Spring by removing the .sample
suffix:
cp src/main/resources/application-dev.properties.sample src/main/resources/application-dev.properties
cp src/main/resources/application.properties.sample src/main/resources/application.properties
You should have a MariaDB database with a user and password that you can log into MariaDB. (You can check that your user and password work by running mysql -u<YOUR USER> -p
and typing your password.)
Then, add the user and password to src/main/resources/application-dev.properties
spring.datasource.url=jdbc:mysql://localhost:3306/ischia?useLegacyDatetimeCode=false&serverTimezone=UTC&createDatabaseIfNotExist=true
spring.datasource.username=<YOUR MARIADB USER>
spring.datasource.password=<YOUR MARIADB PASSWORD>
Log into Github to create a Github application. Click your user icon (top right) and select "Settings." On the far left (bottom), select "Developer Settings." On the left, select "Oauth Apps." Click "Create new Oauth App."
Add Application Name, Url, and Description to any values you desire.
Set "Application Callback Url" to http://localhost:8080/login/oauth2/code/github
(IMPORTANT).
Save your new oauth app.
Now copy the Client ID and Client Secret fields from the Github UI to your application.properties
:
# OAuth2 configuration
ischia.oauth2.github.client-id=<GITHUB OAUTH2 CLIENT ID>
ischia.oauth2.github.client-secret=<GITHUB OAUTH2 CLIENT SECRET>
The application is now ready to run!
For convenience, a shell script has been included to simplify startup. From the project root, first make the script executable:
chmod +x ischia
Then start the app using ./ischia 1
This set's Springs active profile to dev
, and tells Spring to read first any settings in application.properties
, and to overwrite them with any values contained in application-dev.properties
.
To debug the application, set up a remote debug run profile in IntelliJ with the default settings. The application does not suspend, so you may connect and disconnect your debugger at any time.
Ischia is an example project that is meant to be forked directly and transformed into your application.
- Create the domain class in the module
1.domain
- Add an accompanying DAO interface in the module
1.domain
and any access methods - Add a repository in
src/main/kotlin/io/ischia/repository/Repositories.kt
with the following features:
- It should extend
CrudRepository<T, ID>
, whereT
is the domain class andID
is the class of the class's@Id
-annotated field - It should override any methods that Hibernate cannot create automatically using
@Query
andoverride fun <function name>()
Ischia's module setup uses naming system that ensures the dependency graph remains a DAG. Recommendations for adding new modules:
- Begin the name of the module with a number that is one greater its highest-numbered dependency
- Favor depending on api/interface modules over implementation modules (e.g. depend on
2.api
rather than3.service
)
If you prefer to target JDK 1.8, you can do so by changing four values in the top-level build.gradle
, all marked with the following comment:
"11" // or "1.8" for Java 8
To package for deployment, first build a runnable jar:
./ischia 3
Deploy to your favorite Java 11 (or Java 8) runtime environment!
- Upgrade to Kotlin 1.7.10
- Upgrade to Gradle 7.5.1
- Upgrade to Spring Boot 2.7.3
- Upgrade to Spring Security 5.7.1 and use new API for http security config
- Upgrade to Guava 31.1-jre
- Add docs for some interfaces
- Upgrade to Gradle 7
- Upgrade to Spring Boot 2.5.0
- Upgrade to Spring Security 5.5.0
- Upgrade to JDK 11
- Upgrade to Kotlin 1.5.10
- Upgrade to Spring Security 5.4.6
- Added 1.util module for utility methods and interfaces
- Added ./ischia shell script for startup
- Added liquibase for DB migrations
- Upgrade to Spring Security 5.2 and eliminate the deprecated
@EnableOauth2Sso
- Added TypedConfig and TypedSpringConfig implementation
- Switched to Github oauth
- Fix failing test in UserServiceSpec
- Initial commit, spring boot + spring security + google oauth + JPA/Hibernate