# piomin/sample-spring-microservices-new: Spring Cloud Demo Architecture

> This Java repository demonstrates Spring Boot and Spring Cloud services connected through Eureka, Spring Cloud Config, Zuul, OpenFeign, Swagger, and tracing integrations. It is useful for studying distributed-service wiring, but it remains a demo with in-memory data and branch-specific examples.

**piomin/sample-spring-microservices-new** — Demo for Spring Boot and Spring Cloud microservices with distributed configuration (Spring Cloud Config), service discovery (Eureka), API gateway (Spring Cloud Gateway, Zuul), Swagger/OpenAPI documentation (Springdoc), logs correlation using Spring Cloud Sleuth/Micrometer OTEL and many more

- Repository: https://github.com/piomin/sample-spring-microservices-new
- Website: https://piotrminkowski.com
- Stars: 1,393 · Forks: 808
- Language: Java
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/piomin-sample-spring-microservices-new

## What the Spring Cloud Demo Is Built to Show

piomin/sample-spring-microservices-new is a collection of example microservices built with Spring Boot and Spring Cloud. It addresses the practical problem of showing how separate Spring applications obtain configuration, register themselves, locate one another, receive traffic through a gateway, and exchange requests. The intended reader is an engineer who understands basic Java and Spring application structure and wants to inspect the wiring of a distributed system.

The default branch is `master`, but the README documents several other branches with different designs. One uses Spring Cloud Alibaba Nacos for discovery and configuration. Another adds GraphQL and Apollo. Separate examples cover OpenShift deployment, local management with Trampoline, and Spring Boot 3 with Micrometer Tracing and Springdoc. This repository is therefore a set of demonstrations, not one architecture that has evolved uniformly. The selected branch must match the framework generation and infrastructure choices being studied.

## Module Boundaries in the Master Example

The master architecture is divided into six modules with separate responsibilities. `config-service` runs Spring Cloud Config Server in `native` mode, and the README says its configuration files are placed on the classpath. `discovery-service` runs an embedded Eureka discovery server. `gateway-service` uses Spring Cloud Netflix Zuul as a proxy and gateway.

The other modules represent domain services. `employee-service` provides CRUD operations over an in-memory employee repository. `department-service` provides CRUD operations over an in-memory department repository and communicates with `employee-service`. `organization-service` provides organization operations and communicates with other domain services according to the module description. OpenFeign is the stated communication mechanism for the master-branch example.

The module split makes ownership clear. Configuration is centralized, discovery is separate, gateway traffic is isolated from domain logic, and each domain module owns its operations. The in-memory repositories are also a clear limitation. They are useful for tracing calls, but they do not demonstrate durable storage, schema migration, cross-service transactions, or recovery after a process restart.

## Configuration, Eureka, Zuul, and OpenFeign

The documented data flow begins with Spring Cloud Config. Services load configuration through `config-service` instead of receiving every setting from a local file or a command-line argument. The server uses `native` mode, which means the repository structure and configuration files are part of the example rather than a separately documented Git-backed configuration repository. A reader should inspect the Config Server resources and client configuration to determine which values are centralized and which remain local.

Applications then register with `discovery-service`. Eureka provides a location for registered instances, allowing other services to avoid hard-coding remote hosts. OpenFeign is used for service-to-service communication in the documented example. The README does not reproduce the Feign interfaces or controller paths, so those details should be checked in the module source before writing a client.

Zuul provides the external proxy boundary through `gateway-service`. The README states that Eureka runs on port `8061` and the gateway is exposed on port `8060`. Swagger UI is available through the gateway at `http://localhost:8060/swagger-ui.html`, where the README says you can switch between services. Zipkin can optionally receive trace data on port `9411`. The repository description also mentions Spring Cloud Sleuth and Micrometer OTEL, but the README does not document the exact trace configuration for the master branch.

## Building and Starting the Spring Cloud Services

The README gives a Docker path and a local path. For Docker, build the application images first. The `build-image` profile is required because the README says `config-service` needs `ji` for `curl`.

```bash
$ mvn clean package -Pbuild-image
```

After the build, start the services with Docker Compose:

```bash
$ docker-compose up
```

The repository's `docker-compose.yml` defines Zipkin, `config-service`, `discovery-service`, `employee-service`, `department-service`, and `organization-service`. It also contains a `gateway-service` definition. The Compose file maps `config-service` to `8088`, `discovery-service` to `8061`, and Zipkin to `9411`. The domain services use dynamic port `8080` mappings rather than fixed host ports.

For local execution, the README says that Maven and JDK8+ are needed in most cases. Start `config-service` first, then `discovery-service`, then the three domain services, and finally `gateway-service`. The documented command for the configuration service is:

```bash
cd config-service
mvn spring-boot:run
```

The README's next local example repeats `cd config-service` before the discovery command. Since the corresponding module is named `discovery-service`, verify the working directory before copying that step. The first useful check is the gateway's Swagger UI at `http://localhost:8060/swagger-ui.html`, where the README says you can switch between services.

## Health Checks, Startup Order, and Failure Conditions

The Docker setup expresses dependencies through health checks and `depends_on`. The Config Server health check calls `curl --fail http://localhost:8088/employee/docker || exit 1`. The discovery service health check calls `curl --fail http://localhost:8061/eureka/v2/apps || exit 1`. Discovery waits for Config Server to become healthy, while the domain services wait for discovery.

That ordering helps the Compose environment start in a predictable sequence, but it does not provide complete failure recovery. A service that becomes healthy can still lose its configuration source or registration later. The README does not document retries for Feign calls, circuit breakers, authentication, authorization, secret management, or persistent data backup. Those omissions matter for production use because a successful health check only confirms that one local endpoint responded at one moment.

The gateway is also a single documented proxy. The README does not specify fallback routing, request size limits, timeout behavior, or gateway authentication. A team expecting the gateway to provide a complete external security boundary would need to inspect its configuration and test those cases directly.

## Branch Choices and Alternative Spring Cloud Arrangements

The default example uses Zuul as its gateway and Eureka as its discovery system. Routes, filters, and request handling are configured differently, so the gateway technology cannot be exchanged by changing a label alone. The repository description mentions Spring Cloud Gateway, but the README does not give a complete Gateway-specific startup sequence for the master branch.

The `alibaba` branch provides another comparison. It uses Spring Cloud Alibaba Nacos instead of Eureka and Zuul in the example described by the README. Nacos is used for discovery and configuration, whereas the default arrangement separates Spring Cloud Config Server from Eureka. This is a concrete architectural difference, not merely a naming change: the service responsible for configuration and the registration model change together.

GraphQL and Apollo appear in another branch, while the OpenShift branch focuses on deployment. Engineers choosing among these examples should compare the branch configuration and startup files rather than combining features from different branches. The project is better used as a set of references for specific Spring Cloud mechanisms than as a single baseline for every deployment environment.

## Maintenance, Licence, and Upgrade Boundaries

The repository is not archived, and its last push was on 2026-10-03. That confirms recent repository activity, but it does not establish a release cadence or a compatibility commitment. There are no GitHub releases, so dependency upgrades are not presented through a formal release history in the repository information. A `.java-version` file, a root `pom.xml`, and `renovate.json` are present, but the README does not explain the complete dependency update policy.

The README's JDK8+ requirement should be checked against the branch and Maven files before compiling. The repository description mentions both Spring Boot 2 and Spring Boot 3 topics, while the default usage text points to an older Spring Boot 2.0 article. That difference matters when selecting dependencies, Spring Cloud train versions, or tracing libraries. The documented startup commands are not a substitute for a compatibility matrix.

The repository licence is listed as unknown. No licence file or licence identifier appears in the README information or the listed top-level entries. Reusing code requires checking the repository's licensing status directly. The source can be studied without assuming permission to copy or redistribute it.

## Conclusion

Engineers learning Spring Cloud service discovery, centralized configuration, gateway routing, and inter-service calls can use the master branch as a concrete reference. Teams needing persistent data, production operations, or a documented upgrade path should not treat it as a complete application. Verify the Maven and JDK requirements and inspect the selected branch before adoption.

## FAQ

### How do I run piomin/sample-spring-microservices-new locally?

The README says to start `config-service` with `mvn spring-boot:run`, followed by the discovery service, the three domain services, and `gateway-service`. Eureka is documented on port `8061` and the gateway on port `8060`.

### Does piomin/sample-spring-microservices-new use Docker Compose?

Yes. The README documents `mvn clean package -Pbuild-image` followed by `docker-compose up`. The Compose file defines configuration, discovery, domain, gateway, and Zipkin services.

### Does piomin/sample-spring-microservices-new persist employee, department, and organization data?

No durable persistence behavior is documented. The README describes the repositories as in-memory, so data should not be treated as surviving application restarts.

## Sources

- [Issues](https://github.com/piomin/sample-spring-microservices-new/issues)
- [piomin/sample-spring-microservices-new on GitHub](https://github.com/piomin/sample-spring-microservices-new)
- [Project website](https://piotrminkowski.com)
- [README](https://github.com/piomin/sample-spring-microservices-new/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/piomin-sample-spring-microservices-new