A Quarkus application often needs a database, message broker, or identity provider before you can run it locally. Dev Services removes much of that setup: when a supporting extension is present and no remote-service connection is configured, Quarkus attempts to start a disposable service and wire the application to it. The service runs in Dev mode or during tests, not in production; production requires connection configuration for an actual service. section 3.4 section 5.6
To use Dev Services, keep these constraints in mind:
- Add an extension that supports the service. Most implementations need Docker or Podman; H2 and Derby are exceptions that run inside the application JVM. section 3.4
- Inspect running containers with docker ps, or press c in the Dev mode terminal to see Dev Services details, including injected configuration. section 3.4.1
- Expect containers to stop when Dev mode stops. A shared Keycloak instance can serve multiple Dev mode applications, but stopping the application that started it also stops the container. section 3.7 section 6.1.2
Try an OIDC-backed endpoint
Run quarkus extension add oidc with a working Docker or Podman runtime. Quarkus starts a Keycloak container; use Dev UI to obtain a token, then send an Authorization: Bearer request to an endpoint that reads SecurityContext.getUserPrincipal(). If tests do not need OIDC, set %test.quarkus.oidc.enabled=false to avoid starting Keycloak for them. section 3.4.1
Test against a real database
A @QuarkusTest can persist and read a reservation in a Dev Services PostgreSQL database rather than replacing persistence with a mock. Use @Transactional for the database-writing test. Container host ports are normally assigned dynamically; quarkus.datasource.devservices.port=5432 fixes the host port when needed. section 7.1.3
Listing 3.7 Listing running Dev Services containers
== Dev Services
keycloak
Container: d89a92d83c7a/epic_dhawan
quay.io/keycloak/keycloak:25.0.6
Network: bridge - 0.0.0.0:32768->8080/tcp ,:::32768->8080/tcp
Exec command: docker exec -it d89a92d83c7a /bin/bash
Injected config: - client.quarkus.oidc.auth-server-url=
http://localhost:32768/realms/quarkus
- keycloak.realms=quarkus
- keycloak.url=http://localhost:32768
- oidc.users=alice=alice,bob=bob
- quarkus.oidc.application-type=service
- quarkus.oidc.auth-server-url=
http://localhost:32768/realms/quarkus
- quarkus.oidc.client-id=quarkus-app
- quarkus.oidc.credentials.secret=secret
The running-container listing makes automatic wiring concrete: it shows the Keycloak container, mapped port, and OIDC configuration injected into the application. section 3.4.1
A service without built-in Dev Services support can be integrated through a custom Quarkus extension. The extension API can manage its container and inject connection details into application configuration; writing that extension is a separate task from using an existing one. section 12.1.6
