Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add more non-platform extensions to dev services guide + make guide guide-ier #39913

Merged
merged 2 commits into from
Apr 7, 2024
Merged

Add more non-platform extensions to dev services guide + make guide guide-ier #39913

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6c75866
Add more non-platform extensions to dev services guide; make guide mo…
holly-cummins Apr 5, 2024
0e1733c
Add Microcks.
holly-cummins Apr 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/src/main/asciidoc/config-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,6 +341,7 @@ With the `dev` profile enabled, the property `bar` has the value `hallo`, but th
`bonjour`. If the `prod` profile is enabled, `bar` has the value `hello` (as there is no specific value for the `prod`
profile), and `baz` the value `bonjour`.

[[default-profiles]]
=== Default Profiles

By default, Quarkus provides three profiles, that activate automatically in certain conditions:
Expand Down
95 changes: 70 additions & 25 deletions docs/src/main/asciidoc/dev-services.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,46 +3,75 @@
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Dev Services Overview

Check warning on line 6 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Dev Services Overview'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Dev Services Overview'.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 6, "column": 3}}}, "severity": "INFO"}
include::_attributes.adoc[]
:categories: core
:summary: A list of all extensions that support Dev Services and their configuration options.
:summary: An introduction to dev services and a list of all extensions that support Dev Services and their configuration options.
:topics: dev-services,dev-mode,testing

== What Are Dev Services?

Check warning on line 12 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'What Are Dev Services?'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'What Are Dev Services?'.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 12, "column": 4}}}, "severity": "INFO"}

Check warning on line 12 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.HeadingPunctuation] Do not use end punctuation in headings.

Raw Output:
{"message": "[Quarkus.HeadingPunctuation] Do not use end punctuation in headings.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 12, "column": 24}}}, "severity": "INFO"}

Quarkus supports the automatic provisioning of unconfigured services in development and test mode. We refer to this capability
as Dev Services. From a developer's perspective this means that if you include an extension and don't configure it then
as Dev Services. If you include an extension and don't configure it then

Check warning on line 15 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 15, "column": 1}}}, "severity": "INFO"}
Quarkus will automatically start the relevant service (usually using https://www.testcontainers.org/[Testcontainers] behind the scenes) and wire up your

Check warning on line 16 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 16, "column": 63}}}, "severity": "INFO"}
application to use this service.

For a tutorial showing how to get started writing an application with persistence and Dev Services, see xref:getting-started-dev-services.adoc[Your Second Quarkus Application].


== Using Dev Services

Check warning on line 22 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Using Dev Services'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Using Dev Services'.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 22, "column": 4}}}, "severity": "INFO"}

Dev Services are designed to be frictionless, so they will be automatically started any time you include an extension which supports

Check warning on line 24 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 24, "column": 1}}}, "severity": "INFO"}

Check warning on line 24 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 24, "column": 118}}}, "severity": "INFO"}
Dev Services, as long as you don't configure a connection to an external service.

Check warning on line 25 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 25, "column": 15}}}, "severity": "INFO"}

Check warning on line 25 in docs/src/main/asciidoc/dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'if' or 'provided that' rather than 'as long as' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'if' or 'provided that' rather than 'as long as' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/dev-services.adoc", "range": {"start": {"line": 25, "column": 15}}}, "severity": "WARNING"}

NOTE: In order to use most Dev Services you will need a working container environment (remote environments are supported).
If you don't have a container environment, such as Docker or Podman, installed you will need to configure your services normally.

The default startup timeout for Dev Services is 60s, if this is not enough you can increase it with the `quarkus.devservices.timeout` property.

To configure a production service but continue to use Dev Services in development and test modes, use xref:config-reference.adoc#default-profiles[configuration profiles].

For example,

[source, properties]
----
# configure your datasource
%prod.quarkus.datasource.db-kind = postgresql
%prod.quarkus.datasource.username = prod-admin
%prod.quarkus.datasource.password = super-secret
%prod.quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/mydatabase
----

== Disabling Dev Services

All this functionality is part of the Quarkus `deployment` modules, so does not affect the production application in any
way. If you want to disable all Dev Services you can use the `quarkus.devservices.enabled=false` config property, although
in most cases this is not necessary as simply configuring the service will result in the Dev Service being disabled automatically.

Note that the default startup timeout is 60s, if this is not enough you can increase it with the `quarkus.devservices.timeout` property.


This page lists all the Dev Services that Quarkus supports.
== Platform Dev Services

This section lists all the Dev Services available in the Quarkus Platform.

NOTE: In order to use Dev Services you will generally need a working Docker environment (remote environments are supported).
If you don't have Docker installed you will need to configure your services normally.

== AMQP
=== AMQP

The AMQP Dev Service will be enabled when the `quarkus-messaging-amqp` extension is present in your application, and
the broker address has not been explicitly configured. More information can be found in the
xref:amqp-dev-services.adoc[AMQP Dev Services Guide].

include::{generated-dir}/config/quarkus-smallrye-reactivemessaging-amqp-config-group-amqp-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== Apicurio Registry
=== Apicurio Registry

The Apicurio Dev Service will be enabled when the `quarkus-apicurio-registry-avro` extension is present in your application, and it's
address has not been explicitly configured. More information can be found in the
xref:apicurio-registry-dev-services.adoc[Apicurio Registry Dev Services Guide].

include::{generated-dir}/config/quarkus-apicurio-registry-devservices-apicurio-registry-devservice-apicurio-registry-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== Databases
=== Databases

The database Dev Services will be enabled when a reactive or JDBC datasource extension is present in the application,
and the database URL has not been configured. More information can be found in the
Expand All @@ -60,84 +89,100 @@

include::{generated-dir}/config/quarkus-datasource-config-group-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== Kafka
=== Kafka

The Kafka Dev Service will be enabled when the `quarkus-kafka-client` extension is present in your application, and
the broker address has not been explicitly configured. More information can be found in the
xref:kafka-dev-services.adoc[Kafka Dev Services Guide].

include::{generated-dir}/config/quarkus-kafka-client-config-group-kafka-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== Keycloak
=== Keycloak

The Keycloak Dev Service will be enabled when the `quarkus-oidc` extension is present in your application, and
the server address has not been explicitly configured. More information can be found in the
xref:security-openid-connect-dev-services.adoc[OIDC Dev Services Guide].

include::{generated-dir}/config/quarkus-keycloak-devservices-keycloak-keycloak-build-time-config.adoc[opts=optional, leveloffset=+1]

== Kubernetes
=== Kubernetes

The Kubernetes Dev Service will be enabled when `kubernetes-client` extension is present in your application, and
the API server address has not been explicitly configured. More information can be found in the
xref:kubernetes-dev-services.adoc[Kubernetes Dev Services Guide].

include::{generated-dir}/config/quarkus-kubernetes-client-config-group-kubernetes-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== MongoDB
=== MongoDB

The MongoDB Dev Service will be enabled when the `quarkus-mongodb-client` extension is present in your application, and
the server address has not been explicitly configured. More information can be found in the
xref:mongodb.adoc#dev-services[MongoDB Guide].

include::{generated-dir}/config/quarkus-mongodb-config-group-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== RabbitMQ
=== RabbitMQ

The RabbitMQ Dev Service will be enabled when the `quarkus-messaging-rabbitmq` extension is present in your application, and
the broker address has not been explicitly configured. More information can be found in the
xref:rabbitmq-dev-services.adoc[RabbitMQ Dev Services Guide].

include::{generated-dir}/config/quarkus-smallrye-reactivemessaging-rabbitmq-config-group-rabbit-mq-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== Pulsar
=== Pulsar

The Pulsar Dev Service will be enabled when the `quarkus-messaging-pulsar` extension is present in your application, and
the broker address has not been explicitly configured. More information can be found in the
xref:pulsar-dev-services.adoc[Pulsar Dev Services Guide].

== Redis
=== Redis

The Redis Dev Service will be enabled when the `quarkus-redis-client` extension is present in your application, and
the server address has not been explicitly configured. More information can be found in the
xref:redis-dev-services.adoc[Redis Dev Services Guide].

include::{generated-dir}/config/quarkus-redis-config-group-client-dev-services-config.adoc[opts=optional, leveloffset=+1]

== Vault
=== Vault

The Vault Dev Service will be enabled when the `quarkus-vault` extension is present in your application, and
the server address has not been explicitly configured. More information can be found in the
link:{vault-guide}#dev-services[Vault Guide].

== Neo4j

The Neo4j Dev Service will be enabled when the `quarkus-neo4j` extension is present in your application, and
the server address has not been explicitly configured. More information can be found in the
link:{neo4j-guide}#dev-services[Neo4j Guide].

== Infinispan
=== Infinispan

The Infinispan Dev Service will be enabled when the `quarkus-infinispan-client` extension is present in your application, and
the server address has not been explicitly configured. More information can be found in the
xref:infinispan-dev-services.adoc[Infinispan Dev Services Guide].

include::{generated-dir}/config/quarkus-infinispan-client-config-group-infinispan-client-build-time-config-dev-service-configuration.adoc[opts=optional, leveloffset=+1]

== Elasticsearch
=== Elasticsearch

The Elasticsearch Dev Service will be enabled when one of the Elasticsearch based extensions (Elasticsearch client or Hibernate Search ORM Elasticsearch)
is present in your application, and the server address has not been explicitly configured.
More information can be found in the xref:elasticsearch-dev-services.adoc[Elasticsearch Dev Services Guide].

include::{generated-dir}/config/quarkus-elasticsearch-devservices-elasticsearch-dev-services-build-time-config.adoc[opts=optional, leveloffset=+1]

== Dev Services beyond the Quarkus Platform

Many Quarkiverse extensions which are not in the Quarkus Platform also offer Dev Services.
holly-cummins marked this conversation as resolved.
Show resolved Hide resolved

Here are some highlights.

=== Neo4j

The Neo4j Dev Service will be enabled when the `quarkus-neo4j` extension is present in your application, and
the server address has not been explicitly configured. More information can be found in the
link:{neo4j-guide}#dev-services[Neo4j Guide].

=== WireMock

The WireMock extension starts WireMock as a Dev Service. It is a test-focussed extension, designed to run in dev and test mode only.
More information can be found in the https://docs.quarkiverse.io/quarkus-wiremock/dev/index.html[WireMock Guide].

=== Microcks

The Microcks Quarkus extension includes a Microcks Dev Service. The Dev Service manages mocks for dependencies and contract-testing your API endpoints.
See the extension https://github.com/microcks/microcks-quarkus[README.md] for more information.