mirror of
https://github.com/jlengrand/helidon.git
synced 2026-03-10 08:21:17 +00:00
docs overview page, reworked intro page (#418)
* docs overview page, reworked intro page * update sitegen version to 1.0.8
This commit is contained in:
Romain Grecourt
@@ -1,75 +0,0 @@
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
= Introduction
|
||||
:description: about Helidon
|
||||
:keywords: helidon, java, microservices, microprofile
|
||||
|
||||
== Introduction
|
||||
|
||||
Helidon is a collection of Java libraries for writing microservices.
|
||||
There is no unique tooling or deployment model. Your microservice is
|
||||
just a Java SE application.
|
||||
|
||||
The foundation of Helidon is composed of three components:
|
||||
|
||||
[PILLARS]
|
||||
====
|
||||
|
||||
[CARD]
|
||||
.WebServer
|
||||
[icon=settings_ethernet]
|
||||
--
|
||||
A programmatic HTTP API with reactive features, powered by Netty.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Config
|
||||
[icon=settings]
|
||||
--
|
||||
A flexible configuration framework with support for multiple sources and formats.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Security
|
||||
[icon=security]
|
||||
--
|
||||
A tool-chain to handle authentication, authorization and context propagation.
|
||||
--
|
||||
====
|
||||
|
||||
== MicroProfile
|
||||
|
||||
On top of this foundation Helidon supports the MicroProfile family of APIs,
|
||||
including JAX-RS and CDI. This means you can choose from one of two
|
||||
programming models:
|
||||
|
||||
* Helidon SE: a functional programming style that uses the Helidon WebServer,
|
||||
Config and Security APIs directly. This gives you full
|
||||
transparency and control.
|
||||
* Helidon MP: a more declarative model that supports the https://microprofile.io[MicroProfile]
|
||||
family of APIs. This will be familiar to Java EE developers.
|
||||
|
||||
Our <<getting-started/02_base-example.adoc,Quickstart Examples>> gets
|
||||
you started using either of these programming models.
|
||||
|
||||
=== Docker and Kubernetes support
|
||||
|
||||
The <<getting-started/02_base-example.adoc,Helidon Quickstart Examples>> contain
|
||||
support for Docker and Kubernetes. Just follow the examples and you'll have
|
||||
a simple service up and running in minutes.
|
||||
102
docs/src/main/docs/about/01_overview.adoc
Normal file
102
docs/src/main/docs/about/01_overview.adoc
Normal file
@@ -0,0 +1,102 @@
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
= Overview
|
||||
:description: Helidon documentation
|
||||
:keywords: helidon, java, microservices, microprofile, documentation
|
||||
|
||||
== Get going
|
||||
|
||||
[PILLARS]
|
||||
====
|
||||
[CARD]
|
||||
.Getting Started
|
||||
[icon=assistant,link=getting-started/02_base-example.adoc]
|
||||
--
|
||||
Quickly create your first application, in under 2 minutes.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Guides
|
||||
[icon=explore,link=guides/01_overview.adoc]
|
||||
--
|
||||
Follow step-by-step guides to build your applications.
|
||||
--
|
||||
====
|
||||
|
||||
== Components
|
||||
|
||||
[PILLARS]
|
||||
====
|
||||
[CARD]
|
||||
.WebServer
|
||||
[icon=settings_ethernet,link=webserver/01_introduction.adoc]
|
||||
--
|
||||
A programmatic HTTP API with reactive features, powered by Netty.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Config
|
||||
[icon=settings,link=config/01_introduction.adoc]
|
||||
--
|
||||
A flexible configuration framework with support for multiple sources and
|
||||
formats.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Security
|
||||
[icon=security,link=security/01_introduction.adoc]
|
||||
--
|
||||
A tool-chain to handle authentication, authorization and context propagation.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.MicroProfile
|
||||
[icon=widgets,link=microprofile/01_introduction.adoc]
|
||||
--
|
||||
A platform definition that is familiar to enterprise Java developers.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Extensions
|
||||
[icon=extension,link=extensions/01_overview.adoc]
|
||||
--
|
||||
A set of add-ons for your Helidon-based applications.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Metrics
|
||||
[icon=av_timer,link=metrics/01_metrics.adoc]
|
||||
--
|
||||
Instrumentation to expose metrics of your applications.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Tracing
|
||||
[icon=timeline,link=tracing/01_tracing.adoc]
|
||||
--
|
||||
Profile and monitor your applications across multiple services.
|
||||
--
|
||||
|
||||
[CARD]
|
||||
.Health Checks
|
||||
[icon=favorite_outline,link=health/01_health.adoc]
|
||||
--
|
||||
Expose health statuses of your applications.
|
||||
--
|
||||
====
|
||||
62
docs/src/main/docs/about/02_introduction.adoc
Normal file
62
docs/src/main/docs/about/02_introduction.adoc
Normal file
@@ -0,0 +1,62 @@
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
Copyright (c) 2018, 2019 Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
= Introduction
|
||||
:description: about Helidon
|
||||
:keywords: helidon, java, microservices, microprofile
|
||||
|
||||
== A collection of Java libraries
|
||||
|
||||
Helidon is a collection of Java libraries for writing microservices.
|
||||
|
||||
There's no need for any specific tooling or deployment model. Simply use your
|
||||
favorite tools !
|
||||
|
||||
NOTE: Your microservice is a plain Java application. You do not need an
|
||||
application server.
|
||||
|
||||
== Cloud-native Java
|
||||
|
||||
Helidon libraries interoperate with popular tools from the cloud-native space:
|
||||
|
||||
* https://www.docker.com/[Docker]
|
||||
* https://kubernetes.io/[Kubernetes]
|
||||
* https://prometheus.io/[Prometheus]
|
||||
* https://opentracing.io/[OpenTracing]
|
||||
* https://coreos.com/etcd/[Etcd]
|
||||
|
||||
TIP: The <<getting-started/02_base-example.adoc,Helidon Quickstart Examples>>
|
||||
contain support for Docker and Kubernetes.
|
||||
|
||||
== Helidon SE
|
||||
|
||||
Helidon SE is the functional programming style provided by all Helidon
|
||||
libraries.
|
||||
|
||||
NOTE: Helidon SE gives you full transparency and puts you in control. There is
|
||||
no magic!
|
||||
|
||||
== Helidon MP
|
||||
|
||||
Helidon MP is our MicroProfile implementation.
|
||||
|
||||
https://microprofile.io[MicroProfile] is a platform definition that is familiar
|
||||
to enterprise Java developers. It provides a declarative programming style that
|
||||
is portable. It includes popular Java APIs such as `JAX-RS` and `CDI`.
|
||||
|
||||
NOTE: Helidon MP is built on top of the Helidon libraries.
|
||||
@@ -24,7 +24,6 @@
|
||||
|
||||
[PILLARS]
|
||||
====
|
||||
|
||||
[CARD]
|
||||
.SE REST Web Service
|
||||
[link=guides/02_SE_REST_web-service.adoc]
|
||||
|
||||
@@ -42,7 +42,7 @@ pages:
|
||||
- "**/*.adoc"
|
||||
backend:
|
||||
name: "vuetify"
|
||||
homePage: "about/01_introduction.adoc"
|
||||
homePage: "about/01_overview.adoc"
|
||||
releases:
|
||||
- "${project.version}"
|
||||
navigation:
|
||||
|
||||
59
docs/src/main/docs/tracing/01_tracing.adoc
Normal file
59
docs/src/main/docs/tracing/01_tracing.adoc
Normal file
@@ -0,0 +1,59 @@
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
= Tracing
|
||||
:description: Helidon Tracing Support
|
||||
= :keywords: helidon, tracing
|
||||
|
||||
== Tracing Support
|
||||
Helidon includes support for tracing through the `https://opentracing.io/[OpenTracing]` APIs.
|
||||
Tracing is integrated with WebServer and Security.
|
||||
|
||||
Support for specific tracers is abstracted. Your application can depend on
|
||||
the abstraction layer and provide a specific tracer implementation as a Java
|
||||
`ServiceLoader` service.
|
||||
|
||||
|
||||
=== Maven Coordinates
|
||||
|
||||
Declare the following dependency in your project to use the tracer abstraction:
|
||||
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
.Tracer Abstraction
|
||||
----
|
||||
<dependency>
|
||||
<groupId>io.helidon.tracing</groupId>
|
||||
<artifactId>helidon-tracing</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
=== Configuring Tracing
|
||||
|
||||
To configure tracer with WebServer:
|
||||
|
||||
[source,java]
|
||||
.Configuring OpenTracing `Tracer`
|
||||
----
|
||||
ServerConfiguration.builder()
|
||||
.tracer(TracerBuilder.create("my-application") // <1>
|
||||
.collectorUri(URI.create("http://10.0.0.18:9411")) // <2>
|
||||
.build())
|
||||
.build()
|
||||
----
|
||||
<1> The name of the application (service) to associate with the tracing events
|
||||
<2> The endpoint for tracing events, specific to the tracer used, usually loaded from Config
|
||||
89
docs/src/main/docs/tracing/02_zipkin.adoc
Normal file
89
docs/src/main/docs/tracing/02_zipkin.adoc
Normal file
@@ -0,0 +1,89 @@
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
= Zipkin Tracing
|
||||
:description: Helidon Tracing Support
|
||||
:keywords: helidon, tracing
|
||||
|
||||
Helidon is integrated with the Zipkin tracer.
|
||||
|
||||
The Zipkin builder is loaded through `ServiceLoader` and configured. You could
|
||||
also use the Zipkin builder directly, though this would create a source-code dependency
|
||||
on the Zipkin tracer.
|
||||
|
||||
|
||||
== Prerequisites
|
||||
To use Zipkin as a tracer,
|
||||
add the following dependency to your project:
|
||||
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>io.helidon.tracing</groupId>
|
||||
<artifactId>helidon-tracing-zipkin</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
== Configuring Zipkin
|
||||
|
||||
The Zipkin tracer supports the following configuration options:
|
||||
|
||||
|===
|
||||
|Key |Default value |Builder method |Description
|
||||
|
||||
|service |N/A |serviceName |Name of the service, to distinguish traces crossing service boundaries;
|
||||
Zipkin is using lower-case only, name will be automatically lower-cased
|
||||
|protocol |http |collectorProtocol |Protocol of the Zipkin trace collector (http or https)
|
||||
|host |localhost |collectorHost |Host of the Zipkin trace collector (IP Address, hostname, or FQDN)
|
||||
|port |9411 |collectorPort |Port of the Zipkin trace collector
|
||||
|path |defined by version |collectorPath |Path of the Zipkin trace collector, each version uses a different path
|
||||
by default.
|
||||
|api-version |2 |version |Zipkin specific method, set the protocol version to communicate with
|
||||
trace collector
|
||||
|enabled |true |enabled |If set to false, tracing would be disabled
|
||||
|tags |N/A |addTracerTag(String, String) |`String` tags to add to each span
|
||||
|boolean-tags |N/A |addTracerTag(String, boolean)|`boolean` tags to add to each span
|
||||
|int-tags |N/A |addTracerTag(String, int) |`int` tags to add to each span
|
||||
|===
|
||||
|
||||
The following is an example of a Zipkin configuration, specified in the YAML format.
|
||||
[source,yaml]
|
||||
----
|
||||
tracing:
|
||||
zipkin:
|
||||
service: "helidon-service"
|
||||
protocol: "https"
|
||||
host: "192.168.1.1"
|
||||
port: 9987
|
||||
api-version: 1
|
||||
# this is the default path for API version 1
|
||||
path: "/api/v1/spans"
|
||||
tags:
|
||||
tag1: "tag1-value"
|
||||
tag2: "tag2-value"
|
||||
boolean-tags:
|
||||
tag3: true
|
||||
tag4: false
|
||||
int-tags:
|
||||
tag5: 145
|
||||
tag6: 741
|
||||
----
|
||||
|
||||
Example of Zipkin trace:
|
||||
|
||||
image::webserver/zipkin.png[Zipkin example, align="center"]
|
||||
2
pom.xml
2
pom.xml
@@ -187,7 +187,7 @@
|
||||
<version.plugin.resources>2.7</version.plugin.resources>
|
||||
<version.plugin.scm-publish-plugin>3.0.0</version.plugin.scm-publish-plugin>
|
||||
<version.plugin.site>3.7.1</version.plugin.site>
|
||||
<version.plugin.sitegen>1.0.7</version.plugin.sitegen>
|
||||
<version.plugin.sitegen>1.0.8</version.plugin.sitegen>
|
||||
<version.plugin.source>3.0.1</version.plugin.source>
|
||||
<version.plugin.spotbugs>3.1.3.1</version.plugin.spotbugs>
|
||||
<version.plugin.spotify-docker>1.0.0</version.plugin.spotify-docker>
|
||||
|
||||
Reference in New Issue
Block a user