{"id":19178410,"url":"https://github.com/starichkov/kotlin-ktor-micro-service","last_synced_at":"2026-06-24T09:33:36.366Z","repository":{"id":54574993,"uuid":"489929988","full_name":"starichkov/kotlin-ktor-micro-service","owner":"starichkov","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-17T12:57:16.000Z","size":246,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-17T22:56:19.130Z","etag":null,"topics":["docker","dockerfile","gradle","jvm","kotlin","ktor","microservice"],"latest_commit_sha":null,"homepage":"","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/starichkov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["starichkov"],"ko_fi":"starichkov","buy_me_a_coffee":"starichkov"}},"created_at":"2022-05-08T11:55:50.000Z","updated_at":"2026-01-17T12:57:17.000Z","dependencies_parsed_at":"2026-01-17T14:04:16.984Z","dependency_job_id":null,"html_url":"https://github.com/starichkov/kotlin-ktor-micro-service","commit_stats":null,"previous_names":["starichkov/kotlin-ktor-micro-service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/starichkov/kotlin-ktor-micro-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fkotlin-ktor-micro-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fkotlin-ktor-micro-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fkotlin-ktor-micro-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fkotlin-ktor-micro-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starichkov","download_url":"https://codeload.github.com/starichkov/kotlin-ktor-micro-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fkotlin-ktor-micro-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34724746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["docker","dockerfile","gradle","jvm","kotlin","ktor","microservice"],"created_at":"2024-11-09T10:39:19.262Z","updated_at":"2026-06-24T09:33:36.361Z","avatar_url":"https://github.com/starichkov.png","language":"Kotlin","funding_links":["https://github.com/sponsors/starichkov","https://ko-fi.com/starichkov","https://buymeacoffee.com/starichkov"],"categories":[],"sub_categories":[],"readme":"[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/starichkov/kotlin-ktor-micro-service/gradle.yaml?style=for-the-badge)](https://github.com/starichkov/kotlin-ktor-micro-service/actions/workflows/gradle.yaml)\n[![codecov](https://img.shields.io/codecov/c/github/starichkov/kotlin-ktor-micro-service?style=for-the-badge)](https://app.codecov.io/github/starichkov/kotlin-ktor-micro-service)\n[![GitHub license](https://img.shields.io/github/license/starichkov/kotlin-ktor-micro-service?style=for-the-badge)](https://github.com/starichkov/kotlin-ktor-micro-service/blob/main/LICENSE.md)\n\n# Kotlin Ktor Microservice\n\nA demonstration of a Kotlin microservice built with the Ktor framework, showcasing a clean, layered architecture and modern development practices.\n\n## Technical Information\n\n| Piece of Tech | Version |\n|---------------|---------|\n| Kotlin        | 2.3.x   |\n| Ktor          | 3.3.x   |\n| Gradle        | 9.3.x   |\n| JVM           | 25      |\n\n## Requirements\n\n- **JDK 25**: The project is configured to use Java 25 via Gradle Toolchain.\n- **Docker**: (Optional) Required for building and running the application in a containerized environment.\n\n## Setup and Run\n\n### Running Locally\n\nTo start the application locally using Gradle:\n\n```shell\n./gradlew run\n```\n\nThe server starts on port `8080`.\n\n### Building the Project\n\n- **Assemble**: `./gradlew assemble`\n- **Install Distribution**: `./gradlew installDist` (creates an executable in `build/install/kotlin-ktor-micro-service`)\n\n## Docker\n\nYou can build and run the application using Docker.\n\n### Building and Running Locally\n\nTo build the Docker image locally, first ensure you have the application distribution ready:\n\n```shell\n./gradlew installDist\ndocker build -t ktor-app .\n```\n\nTo run the container:\n\n```shell\ndocker run -d -p 8080:8080 --name ktor-container ktor-app\n```\n\nTo shut down the application gracefully and remove the container:\n\n```shell\ncurl -s http://localhost:8080/ktor/application/shutdown\ndocker rm -f ktor-container\n```\n\n### Testing the Docker Setup\n\nA script is provided to automate the build, run, health check, and shutdown process:\n\n```shell\n./scripts/test-docker.sh\n```\n\nYou can skip the Gradle tests by setting `SKIP_TESTS=true`:\n\n```shell\nSKIP_TESTS=true ./scripts/test-docker.sh\n```\n\n## Scripts\n\n- `./gradlew build`: Full build, including tests and coverage verification.\n- `./gradlew test`: Runs unit and integration tests.\n- `./gradlew check`: Executes all verification tasks, including JaCoCo coverage checks.\n- `./gradlew wrapper --gradle-version 9.3.0`: Updates the Gradle Wrapper version.\n- `./scripts/test-docker.sh`: Automates Docker build and verification.\n\n## Environment Variables\n\n- `JAVA_HOME`: Path to the JDK 25 installation (if not auto-detected).\n- `SKIP_TESTS`: Used by `test-docker.sh` to bypass the test phase during build.\n\n## API Endpoints\n\n- `GET /`: Health check / Welcome message.\n- `GET /json/kotlinx-serialization`: Example JSON response.\n- `GET /customer`: List all customers.\n- `GET /customer/{id}`: Get a specific customer.\n- `POST /customer`: Create a new customer.\n- `DELETE /customer/{id}`: Delete a customer.\n- `GET /order`: List all orders.\n- `GET /order/{number}`: Get a specific order.\n- `GET /order/{number}/total`: Get the total for a specific order.\n- `POST /order`: Create a new order.\n- `DELETE /order/{number}`: Delete an order.\n- `GET /ktor/application/shutdown`: Gracefully shut down the application.\n\nManual testing files (`.http`) are available in `src/test/resources/tests/`.\n\n## Testing and Coverage\n\nThe project uses JUnit and Ktor Test Host for testing. JaCoCo is used to enforce code coverage.\n\n**Coverage Thresholds:**\n- Instructions: **83%**\n- Branches: **89%**\n\nTo run tests and generate a coverage report:\n```shell\n./gradlew check\n```\nReports are generated at `build/reports/jacoco/test/html/index.html`.\n\n## Project Structure\n\n```text\n.\n├── Dockerfile                  # Docker image configuration\n├── build.gradle.kts           # Gradle build configuration\n├── gradle.properties           # Version and property definitions\n├── scripts/                    # Utility and automation scripts\n│   └── test-docker.sh         # Docker verification script\n├── src/\n│   ├── main/\n│   │   ├── kotlin/             # Application source code\n│   │   │   └── com/templatetasks/kotlin/ktor/\n│   │   │       ├── Application.kt      # Application entry point\n│   │   │       ├── api/                # API response models and extensions\n│   │   │       ├── models/             # Domain entities\n│   │   │       ├── plugins/            # Ktor plugins configuration\n│   │   │       ├── routes/             # API route definitions\n│   │   │       └── service/            # Business logic implementation\n│   │   └── resources/          # Configuration files (e.g., logback.xml)\n│   └── test/\n│       ├── kotlin/             # Unit and integration tests\n│       └── resources/          # Test resources and .http files\n└── LICENSE.md                  # Project license\n```\n\n## About TemplateTasks\n\nTemplateTasks is a personal software development initiative by Vadim Starichkov, focused on sharing open-source libraries, services, and technical demos.\n\nIt operates independently and outside the scope of any employment.\n\nAll code is released under permissive open-source licenses. The legal structure may evolve as the project grows.\n\n## License \u0026 Attribution\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE.md) file for details.\n\n### Using This Project?\n\nIf you use this code in your own projects, attribution is required under the MIT License:\n\n```text\nBased on kotlin-ktor-micro-service by Vadim Starichkov, TemplateTasks\nhttps://github.com/starichkov/kotlin-ktor-micro-service\n```\n\n**Copyright © 2026 Vadim Starichkov, TemplateTasks**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarichkov%2Fkotlin-ktor-micro-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarichkov%2Fkotlin-ktor-micro-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarichkov%2Fkotlin-ktor-micro-service/lists"}