spring-boot-traefik

Instruction file imported from lsampaioweb/ai-instructions (.cursor/rules/spring-boot-traefik.mdc). Copyright stays with the author.

Spring Boot Traefik Contract

Apply this contract when a Spring Boot app (or HTTP sidecar UI) is routed through Traefik. Traefik proxy Compose, dashboard, sockets, and cert files stay in the infrastructure runbook for the environment.

Container owns image build, resources, healthchecks, profiles, and generic networks. TLS owns application keystores when the app terminates TLS itself. Actuator and security own health exposure and actuator credentials.

App Compose routing

• Join the shared external Docker network used by Traefik and the apps it routes.
• Enable Traefik on the service with traefik.enable=true.
• Route with an explicit Host rule (for example Host(\app.example.com`)`). Changing a Traefik domain env var does not rewrite these labels — edit the Host rule when the suffix changes.
• Set traefik.http.services.<name>.loadbalancer.server.port to the container listen port (aligned with the active Spring profile / SERVER_PORT).
• Default entrypoint is web. For Traefik HTTPS termination, switch to websecure and tls=true together.
• Keep Traefik → app traffic HTTP on that loadbalancer port. Do not point Traefik at an HTTPS-only app listener unless the deployment explicitly terminates TLS in the app (container TLS-boundary rule).

Traefik-only ingress

When Compose intends Traefik as the only ingress:

• Do not publish app ports: on the host; Traefik is the entrypath.
• Keep the Host rule, enable flag, loadbalancer port, and shared-network declarations present and consistent.

Optional service labels

• HTTP UIs on other infra services may use the same label pattern. Non-HTTP protocols stay on their native ports and are not Traefik-routed.

Forbidden

• Never expect Traefik to discover an app that is off the shared Traefik network or missing traefik.enable=true.
• Never publish host ports: for an app that claims Traefik-only ingress.
• Never leave Host labels on an old domain after changing the DNS suffix without updating those labels.
• Never point loadbalancer.server.port at a different port than the process actually listens on inside the container.