{"id":17257107,"url":"https://github.com/waterlink/kotlin-spring-boot-mvc-starter","last_synced_at":"2025-04-14T06:10:45.142Z","repository":{"id":34326990,"uuid":"150397627","full_name":"waterlink/kotlin-spring-boot-mvc-starter","owner":"waterlink","description":"This is a starter repository for work with Kotlin on Back-end using Spring Boot 2 MVC, JdbcTemplate, Thymeleaf, Emails with Thymeleaf templates, Spring Security, Feature/UI tests using Fluentlenium, Clean Controller-\u003eService-\u003eRepository pattern that is a sweet spot as your starting architecture. Includes a small demo in its source code.","archived":false,"fork":false,"pushed_at":"2022-12-08T01:34:52.000Z","size":784,"stargazers_count":10,"open_issues_count":13,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-15T03:18:19.651Z","etag":null,"topics":["backend","best-practices","clean-code","jdbctemplate","kotlin","spring-boot","tdd","thymeleaf"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/waterlink.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-26T08:56:04.000Z","updated_at":"2024-03-19T22:00:20.000Z","dependencies_parsed_at":"2023-01-15T06:30:50.295Z","dependency_job_id":null,"html_url":"https://github.com/waterlink/kotlin-spring-boot-mvc-starter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterlink%2Fkotlin-spring-boot-mvc-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterlink%2Fkotlin-spring-boot-mvc-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterlink%2Fkotlin-spring-boot-mvc-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterlink%2Fkotlin-spring-boot-mvc-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waterlink","download_url":"https://codeload.github.com/waterlink/kotlin-spring-boot-mvc-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248830395,"owners_count":21168272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","best-practices","clean-code","jdbctemplate","kotlin","spring-boot","tdd","thymeleaf"],"created_at":"2024-10-15T07:16:23.832Z","updated_at":"2025-04-14T06:10:45.113Z","avatar_url":"https://github.com/waterlink.png","language":"Kotlin","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Kotlin + Spring Boot MVC Starter\n\n## Batteries included\n\n- Spring Boot 2 MVC\n- Works with JVM 8 and JVM 11\n- Ready for JdbcTemplate-style repositories + ready PostgreSQL setup\n- Database migrations with Flyway\n- Spring Security email/password login + signup\n- Thymeleaf templates for views + Layout dialect\n- Sending emails and creating them using Thymeleaf templates\n- Setup for unit testing with MockMvcTest, RepositoryTest, EmailTest, and normal JUnit4 tests for service layer\n- Fast UI testing with Fluentlenium and HtmlUnit with FeatureTest\n- Frontend module for your stylesheets with SCSS+Bootstrap4 included\n- Example application with a few features implemented\n\n## Table of contents\n\n1. [Run the Demo app locally](#run-the-demo-app-locally)\n1. [Running the tests](#running-the-tests)\n1. [Familiarizing yourself with demo app structure](#familiarizing-yourself-with-demo-app-structure)\n1. [Controller-Service-Repository pattern](#controller-service-repository-pattern)\n1. [Removing the demo app code](#removing-the-demo-app-code)\n1. [Removing the login-signup code if you do not need it](#removing-the-login-signup-code-if-you-do-not-need-it)\n1. [Setting up the database](#setting-up-the-database)\n1. [Setting up the database and email for deployment](#setting-up-the-database-and-email-for-deployment)\n\n## Run the Demo app locally\n\nFirst make sure, you have the `quizzy` and `quizzy_test` databases in your local PostgreSQL installation:\n\n```bash\n# needed to run the demo app locally\ncreatedb quizzy\ncreateuser quizzy\n\n# needed to run tests\ncreatedb quizzy_test\ncreateuser quizzy_test\n```\n\nTo run the app locally, you’ll need to activate the `dev` spring profile. For that provide the environment variable:\n\n```bash\nexport SPRING_PROFILES_ACTIVE=dev\n./gradlew bootRun\n```\n\nOnce the app is done booting, you can visit [localhost:8080](http://localhost:8080) to see that it works.\n\nActivating the `dev` profile gives you the following:\n\n- When editing static files and Thymeleaf templates there is no need to restart the server,\n  this allows for quicker development.\n- When sending e-mails there is no need to provide real SMTP config, instead all e-mails will be just logged in the\n  STDOUT of the running server (`./gradlew bootRun`).\n- When uploading pictures, local filesystem will be used, instead of any 3rd party service.\n\nTo understand this better, take a look at [application-dev.yml](./src/main/resources/application-dev.yml),\nand search the source code for the occurrence of `@Profile(\"dev\")` and `@Profile(\"dev\", \"test\")`.\n\nAlternatively, you can run the application from the IntelliJ IDEA. For that go to `Application.kt`\nand run the `main` function. This will fail because some spring beans will be missing.\n\nYou’ll need to set the `dev` spring profile. To do that, go to Run configurations -\u003e Edit configurations\n-\u003e Kotlin -\u003e app.ApplicationKt, then:\n\n1. Hit the `Save Configuration` button.\n1. Check the `Single instance only` checkbox.\n1. Go to `Environment Variables` dialog.\n1. Add `SPRING_PROFILES_ACTIVE` variable with value `dev`.\n1. Hit `OK` button.\n\nNow you should be able to run the application from IntelliJ IDEA.\n\n## Running the tests\n\nYou can run all the tests with Gradle:\n\n```bash\n./gradlew test\n```\n\nIf your setup is correct, then all the tests should pass.\n\nAlternatively, you can run tests in IntelliJ IDEA by selecting the directory `src -\u003e test -\u003e kotlin`\nand choosing `Run 'Tests' in 'kotlin'` from the context menu or by pressing the hot key to run the current selection\n(for Mac: CMD+SHIFT+R, for Linux/Win: CTRL+SHIFT+R).\n\nIf you want to run specific package or class, you can do that as well in IntelliJ.\n\n## Familiarizing yourself with demo app structure\n\nLet’s begin from the top level:\n\n```\nPROJECT/\n  frontend/          this is where SCSS+Bootstrap4 stylesheets live\n  src/               this is where your back-end application lives\n  build.gradle       this is where you define your dependencies with Gradle\n```\n\nNow, let’s dive into the structure of the production code for the back-end application:\n\n```\nsrc/\n  main/\n    kotlin/\n      app/\n        Application.kt                this is our Application class—entrypoint to the app\n        config/                       config package contains general configuration of the web app\n        email/                        email package contains code helping you send emails\n        util/                         various helper functions and classes needed throughout the codebase\n        auth/                         auth package contains security, login, signup, and logout concerns\n        quiz/                         example demo application code [can be safely removed before you start]\n    resources/\n      application.yml                 your main application configuration file [edit to your liking]\n      application-dev.yml             your local development configuration file\n      application-cloud.yml.example   copy this file to application-cloud.yml and fill in the blanks [for deployment]\n      db/\n        migration/                    this package contains Flyway migration files\n      static/ (soft-link)             this soft-link allows back-end to “see” the files generated by frontend module\n      translations/\n        messages*.properties          these files contain translations for different languages\n      templates/\n        layouts/                      this package contains Thymeleaf layouts (using layout dialect)\n        emails/                       this package contains Thymeleaf email templates, render them with EmailTemplate helper\n        auth/                         this package contains login, signup and logout related templates\n        quizzes/                      this package contains demo app’s templates\n```\n\nThe unit test side mirrors this structure exactly; more interesting are the feature tests:\n\n```\nsrc/\n  test/\n    kotlin/\n      app/\n        auth/\n        email/\n        quiz/\n      featuretests/                 this is where all UI/feature tests live\n        auth/                       feature tests for login, signup and logout\n        quiz/                       feature tests for demo application\n      helpers/\n        FeatureTest                 class that provides default feature test configuration\n        EmailTest                   class that provides default email test configuration\n        MockMvcTest                 class that provides a standalone mock mvc controller test configuration\n        RepositoryTest              class that provides default JdbcTemplate repository test configuration\n      templates/\n        emails/                     this package contains unit tests for email templates using EmailTemplate helper\n```\n\nFinally, let’s take a look at the front-end structure:\n\n```\nfrontend/\n  package.json                      this is where you define all your dependencies\n  node_modules/                     this is where your front-end dependencies live, get these with `npm install`\n  scss/\n    src/                            this package is where your SCSS code lives\n      index.scss                    your “root” file for stylesheets [run 'npm start' to compile \u0026 watch]\n  static/                           this is where compiled stylesheets end up\n```\n\n## Controller-Service-Repository pattern\n\nIf you take a look at the `auth` or `quiz` packages you’ll see that there is a repeating pattern:\n\n```\napp/\n  quiz/\n    QuizController                      [Controller]\n    QuizService                         [Service]\n    QuizRepository                      [Repository]\n    .. plus some data classes ..\n\n  auth/\n    signup/\n      SignupController                  [Controller]\n      ConfirmController                 [Controller]\n      ConfirmationLinkService           [Service]\n      ForceLoginService                 [Service]\n      .. plus some data classes ..\n    AuthService                         [Service]\n    user/\n      UserRepository                    [Repository]\n```\n\n- Controllers depend (via dependency injection) on Services, and call them.\n- Controller is never calling the repository.\n- Services depend (via dependency injection) on other services or repositories, and call them.\n- Repositories depend only on JdbcTemplate.\n  (You can also have JPA repositories here if you wanted, but I’ve found that they don’t scale very well,\n   and create more trouble for you than saving in the long run, especially if you are unit-testing them).\n\nI have found this pattern very useful on countless projects, and it is an architectural sweet spot\nfor most of the business domains. Moreover, when these three concepts are not enough, you can always\nhave services calling other services, thus the pattern can scale to any level of domain complexity.\n\n\u003c!--\nRight now I’m creating the video screencast series “Kotlin on Back-end: Best practices with Spring Boot.” where\nI’m going to cover this pattern, and much more. We’ll implement a full application together, and we’ll apply\nbest practices such as: Outside-in TDD, Dependency Injection, Controller-Service-Repository pattern, Clean code,\nwriting UI Feature tests that don't break all the time, and so much more.\n\nWatch the [introduction video](https://iwillteachyoukotlin.com/kotlin-backend-best-practices) here.\n--\u003e\n\n## Removing the demo app code\n\nTo remove the demo app code, you can run a single shell-script:\n\n```bash\n./remove-demo.sh\n```\n\n## Removing the login-signup code if you do not need it\n\nIf you don’t need the classic login/signup code, you can remove it with a single shell-script:\n\n```bash\n./remove-auth.sh\n```\n\n## Setting up the database\n\nAfter you have chosen the name for your development database (let’s pretend its name is `mydbname`),\nyou’ll need to create the database and the user to access it on your local postgres installation:\n\n```bash\ncreatedb mydbname\ncreateuser mydbname\n\n# and you’ll need a \"_test\" version of the db to use in the test suite:\ncreatedb mydbname_test\ncreateuser mydbname_test\n```\n\nNow, you’ll need to set this database name and user name in the `src/main/resources/application.yml`:\n\n```yml\nspring:\n  datasource:\n    url: jdbc:postgresql://localhost/mydbname\n    username: mydbname\n    password: mydbname\n    driver-class-name: org.postgresql.Driver\n```\n\nFinally, you’ll need to set similar values for the test environment in the\n`src/test/resources/application-test.yml`:\n\n```yml\nspring:\n  datasource:\n    url: jdbc:postgresql://localhost/mydbname_test\n    username: mydbname_test\n    password: mydbname_test\n    driver-class-name: org.postgresql.Driver\n```\n\n## Setting up the database and email for deployment\n\nNow, once you’ve decided how you will deploy your application, you could either provide an\n`application-cloud.yml` configuration file (see example in `application-cloud.yml.example`),\nor you could supply all the required variables through the environment variables, for example:\n\n```bash\nexport SPRING_DATASOURCE_URL=\u003cyour db url\u003e\nexport SPRING_DATASOURCE_USERNAME=\u003cyour db username\u003e\nexport SPRING_DATASOURCE_PASSWORD=\u003cyour db password\u003e\n\nexport SPRING_MAIL_HOST=\u003cyour smtp host\u003e\nexport SPRING_MAIL_PORT=\u003cyour smtp port\u003e\nexport SPRING_MAIL_USERNAME=\u003cyour smtp username\u003e\nexport SPRING_MAIL_PASSWORD=\u003cyour smtp password\u003e\n\nexport APP_AUTH_CONFIRMATION_EMAILS_FROM=\"Your Name \u003cyour-email@example.org\u003e\"\n```\n\n## Thanks!\n\nThank you for reading this and giving it a try.\n\nTo make me super happy you can star this repo and tweet about it!\n\n\u003c!--\nAnd make sure to check out the [introduction video](https://iwillteachyoukotlin.com/kotlin-backend-best-practices)\nabout Kotlin Back-end best practices.\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaterlink%2Fkotlin-spring-boot-mvc-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaterlink%2Fkotlin-spring-boot-mvc-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaterlink%2Fkotlin-spring-boot-mvc-starter/lists"}