{"id":19178409,"url":"https://github.com/starichkov/micronaut-micro-service","last_synced_at":"2026-05-07T08:32:59.055Z","repository":{"id":61901960,"uuid":"534700271","full_name":"starichkov/micronaut-micro-service","owner":"starichkov","description":"Micronaut framework based example of the micro-service with HTTP endpoints (often called as REST) and multiple additional features.","archived":false,"fork":false,"pushed_at":"2025-02-22T11:51:49.000Z","size":188,"stargazers_count":0,"open_issues_count":11,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-22T12:28:34.214Z","etag":null,"topics":["docker","docker-compose","java","micronaut","micronaut-framework","microservice"],"latest_commit_sha":null,"homepage":"","language":"Java","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":null,"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}},"created_at":"2022-09-09T15:30:41.000Z","updated_at":"2025-02-22T11:51:53.000Z","dependencies_parsed_at":"2023-02-16T09:00:31.361Z","dependency_job_id":"4efd3fe0-df75-4f59-b462-b27d5092355e","html_url":"https://github.com/starichkov/micronaut-micro-service","commit_stats":null,"previous_names":["starichkov/micronaut-micro-service"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fmicronaut-micro-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fmicronaut-micro-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fmicronaut-micro-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starichkov%2Fmicronaut-micro-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starichkov","download_url":"https://codeload.github.com/starichkov/micronaut-micro-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240255303,"owners_count":19772594,"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":["docker","docker-compose","java","micronaut","micronaut-framework","microservice"],"created_at":"2024-11-09T10:39:19.237Z","updated_at":"2026-05-07T08:32:59.043Z","avatar_url":"https://github.com/starichkov.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/starichkov/micronaut-micro-service/maven.yml?style=for-the-badge)](https://github.com/starichkov/micronaut-micro-service/actions/workflows/maven.yml)\n[![codecov](https://img.shields.io/codecov/c/github/starichkov/micronaut-micro-service?style=for-the-badge)](https://app.codecov.io/github/starichkov/micronaut-micro-service)\n[![GitHub license](https://img.shields.io/github/license/starichkov/micronaut-micro-service?style=for-the-badge)](https://github.com/starichkov/micronaut-micro-service/blob/main/LICENSE.md)\n\nMicronaut microservice\n=\nThis project is a Micronaut framework based, 'ready-to-play' micro-service with a simple UI for managing notes and tags.\n\n## Features\n\n- RESTful API for managing notes and tags\n- Simple and responsive UI for creating, editing, and deleting notes and tags\n- Ability to associate tags with notes for better organization\n- Full-text search in notes (coming soon)\n\n## Technical information\n\n| Name           | Version |\n|----------------|---------|\n| Java           | 25      |\n| Maven          | 3.8.1+  |\n| Micronaut      | 4.10.13 |\n| PostgreSQL     | 17.6    |\n| Testcontainers | 2.0.x   |\n\n## Prerequisites\n\n### Database Setup\n\nThe application requires a PostgreSQL database. You need to:\n\n1. Install PostgreSQL 17 or later\n2. Create a database named `micro_notes` (or use a custom name and configure it in environment variables)\n   ```postgresql\n   CREATE DATABASE micro_notes;\n   CREATE USER micro_user WITH PASSWORD '\u003c\u003cpassword_here\u003e\u003e';\n   GRANT ALL PRIVILEGES ON DATABASE micro_notes TO micro_user;\n   ```\n3. Set the following environment variables:\n   - `DATABASE_HOST` - PostgreSQL host (default: localhost)\n   - `DATABASE_PORT` - PostgreSQL port (default: 5432)\n   - `DATABASE_NAME` - Database name (default: micro_notes)\n   - `DATABASE_USER` - Database username\n   - `DATABASE_PASS` - Database password\n\nThe application uses Flyway for database migrations, which will automatically create the necessary tables when the application starts.\n\n## Running the Application\n\n### Standard Run\n\n```shell\nmvn mn:run\n```\n\nThe application will start on port 8080 by default. You can access the UI by navigating to:\n\n```\nhttp://localhost:8080\n```\n\n### API documentation (Swagger/OpenAPI)\n\nSwagger UI: http://localhost:8080/swagger-ui\n\nIf you change the host or port, adjust the URLs accordingly.\n\n### Docker Run\n\n#### Using Micronaut Maven Plugin\n\n```shell\n# Build the Docker image\nmvn clean package -Dpackaging=docker\n\n# Run the Docker container\ndocker run -p 8080:8080 micronaut-micro-service\n```\n\n#### Using Docker Compose\n\nThis project includes a Docker Compose setup that runs both the application and a PostgreSQL database.\n\nThe project uses a `.env` file to store environment variables for Docker Compose, including database credentials. This approach prevents sensitive information from being hardcoded in the docker-compose.yml file.\n\n```shell\n# Build and start the containers\ndocker-compose up -d\n\n# Stop the containers\ndocker-compose down\n\n# Stop the containers and remove volumes\ndocker-compose down -v\n```\n\nThe Docker Compose setup includes:\n- The application running on port 8080\n- PostgreSQL 17.6 with Alpine 3.22 running on port 5432\n- Prometheus for metrics monitoring on port 9090\n- Jaeger for distributed tracing on port 16686 (UI) and 4318 (OTLP)\n- Health checks for both services\n- Volume for PostgreSQL data persistence\n- Environment variables loaded from `.env` file\n\n##### Environment Variables\n\nThe `.env` file contains the following variables:\n- `DATABASE_HOST`: PostgreSQL host (set to \"postgres\" for Docker Compose)\n- `DATABASE_PORT`: PostgreSQL port\n- `DATABASE_NAME`: Database name\n- `DATABASE_USER`: Database username\n- `DATABASE_PASS`: Database password\n- `POSTGRES_DB`: PostgreSQL database name\n- `POSTGRES_USER`: PostgreSQL username\n- `POSTGRES_PASSWORD`: PostgreSQL password\n\nYou can modify these variables in the `.env` file to customize your setup.\n\n## Monitoring and Observability\n\nWhen running the application with Docker Compose, you have access to monitoring and observability tools:\n\n### Jaeger (Distributed Tracing)\n\nJaeger UI is accessible at:\n```\nhttp://localhost:16686\n```\n\nHere you can:\n- View distributed traces of HTTP requests through the application\n- Analyze request latency and performance bottlenecks\n- Search and filter traces by service, operation, tags, and duration\n- Visualize the flow of requests across different components\n\nThe application sends trace data to Jaeger using the OpenTelemetry Protocol (OTLP) over HTTP on port 4318.\n\n### Prometheus (Metrics Monitoring)\n\nPrometheus UI is accessible at:\n```\nhttp://localhost:9090\n```\n\nHere you can:\n- Query application metrics using PromQL\n- View time-series data for JVM metrics, HTTP requests, and custom application metrics\n- Create graphs and dashboards\n- Monitor resource usage and application performance\n\nThe application exposes metrics at the `/prometheus` endpoint, which Prometheus scrapes every 15 seconds.\n\n### How Distributed Tracing Works\n\nThe application uses a hierarchical span architecture for distributed tracing:\n\n#### Automatic HTTP Instrumentation (Root Spans)\n\nThe `micronaut-tracing-opentelemetry-http` dependency provides automatic HTTP instrumentation without requiring any annotations on controllers. This library includes HTTP filters that:\n\n- Automatically intercept all incoming HTTP requests\n- Create a root span for each request at the controller entry point\n- Extract trace context from incoming HTTP headers (for distributed tracing across services)\n- Inject trace context into outgoing HTTP headers\n- Capture HTTP-specific metadata (method, URL, status code, etc.)\n\nThis means that every REST API endpoint (like `GET /v1/notes` or `POST /v1/tags`) automatically gets a root span created without any explicit code or annotations in the controller classes.\n\n#### Service Layer Spans (Child Spans)\n\nWhile HTTP instrumentation handles the entry points automatically, the `@NewSpan` annotation is used on service methods to create child spans that provide detailed visibility into the service layer:\n\n- Each `@NewSpan` annotation creates a child span linked to its parent (the HTTP request span)\n- These child spans help track performance of individual business operations\n- Custom span names (e.g., `\"note-service-create\"`, `\"tag-service-get\"`) make it easy to identify operations in Jaeger\n\n**Example trace hierarchy:**\n```\nHTTP GET /v1/notes/1          (root span - automatic)\n  └─ note-service-get          (child span - @NewSpan annotation)\n```\n\nThis architecture follows OpenTelemetry best practices: automatic instrumentation at integration points (HTTP) combined with manual instrumentation at business logic boundaries (service methods).\n\n## Using the Notes and Tags UI\n\nThe UI provides a simple interface for managing your notes and tags. The interface is divided into two main sections:\n\n- **Notes Section**: For creating, viewing, editing, and deleting notes\n- **Tags Section**: For creating, viewing, editing, and deleting tags\n\nThere's also a tag management panel that appears when you click \"Manage Tags\" on a note, allowing you to associate tags with notes.\n\n### Working with Notes\n\n1. **View Notes**: All your notes are displayed in the Notes section.\n2. **Create a Note**: \n   - Fill in the title and content in the \"Add/Edit Note\" form\n   - Click \"Save\"\n3. **Edit a Note**:\n   - Click the \"Edit\" button on a note\n   - Update the title and/or content\n   - Click \"Save\"\n4. **Delete a Note**:\n   - Click the \"Delete\" button on a note\n   - Confirm the deletion\n\n### Working with Tags\n\n1. **View Tags**: All your tags are displayed in the Tags section.\n2. **Create a Tag**:\n   - Enter a label in the \"Add/Edit Tag\" form\n   - Click \"Save\"\n3. **Edit a Tag**:\n   - Click the \"Edit\" button on a tag\n   - Update the label\n   - Click \"Save\"\n4. **Delete a Tag**:\n   - Click the \"Delete\" button on a tag\n   - Confirm the deletion\n\n### Managing Tags for Notes\n\n1. Click the \"Manage Tags\" button on a note\n2. In the tag management panel:\n   - Click on an available tag to add it to the note\n   - Click on a selected tag to remove it from the note\n3. Click \"Close\" when finished\n\n## API Endpoints\n\n### Notes API\n\n- `GET /v1/notes` - Get all notes\n- `GET /v1/notes/{id}` - Get a specific note\n- `POST /v1/notes` - Create a new note\n- `PATCH /v1/notes/{id}` - Update a note\n- `DELETE /v1/notes/{id}` - Delete a note\n- `POST /v1/notes/{noteId}/tags/{tagId}` - Add a tag to a note\n- `DELETE /v1/notes/{noteId}/tags/{tagId}` - Remove a tag from a note\n\n### Tags API\n\n- `GET /v1/tags` - Get all tags\n- `GET /v1/tags/{id}` - Get a specific tag\n- `POST /v1/tags` - Create a new tag\n- `PATCH /v1/tags/{id}` - Update a tag\n- `DELETE /v1/tags/{id}` - Delete a tag\n\n### Health API\n\n- `GET /health` - Get application health status\n  - Returns a JSON object with the following structure:\n    ```json\n    {\n      \"status\": \"UP\",\n      \"timestamp\": 1234567890123,\n      \"database\": {\n        \"status\": \"UP\"\n      }\n    }\n    ```\n  - If the database is down, the response will include an error message and the overall status will be \"DOWN\"\n\n## GraalVM build\n\n### Generate a native executable using Maven\n\n```shell\nmvn clean package -Pgraalvm -Dpackaging=native-image\n```\n\n### Generate a native executable inside Docker\n\n```shell\nmvn clean package -Dpackaging=docker-native\n```\n\n---\n\n## Micronaut\n\n- [Releases](https://github.com/micronaut-projects/micronaut-core/releases)\n- [User Guide](https://docs.micronaut.io/latest/guide/index.html)\n- [API Reference](https://docs.micronaut.io/latest/api/index.html)\n- [Configuration Reference](https://docs.micronaut.io/latest/guide/configurationreference.html)\n- [Micronaut Guides](https://guides.micronaut.io/index.html)\n\n---\n\n## Feature http-client documentation\n\n- [Micronaut HTTP Client documentation](https://docs.micronaut.io/latest/guide/index.html#httpClient)\n\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```\nBased on micronaut-micro-service by Vadim Starichkov, TemplateTasks\n\nhttps://github.com/starichkov/micronaut-micro-service\n```\n\n**Copyright © 2025 Vadim Starichkov, TemplateTasks**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarichkov%2Fmicronaut-micro-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarichkov%2Fmicronaut-micro-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarichkov%2Fmicronaut-micro-service/lists"}