getting-started.adoc

[[getting-started]]
== Getting started ==

[[set-up-admin-server]]
=== Setting up Spring Boot Admin Server ===

First you need to setup your server. To do this just setup a simple boot project (using http://start.spring.io). As Spring Boot Admin Server is capable of running as servlet or webflux application, you need to decide on this and add the according Spring Boot Starter. In this example we're using the servlet web starter.

. Add Spring Boot Admin Server starter to your dependencies:
+
[source,xml,subs="verbatim,attributes"]
.pom.xml
----
<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-server</artifactId>
    <version>{project-version}</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
----

. Pull in the Spring Boot Admin Server configuration via adding `@EnableAdminServer` to your configuration:
+
[source,java]
----
@Configuration
@EnableAutoConfiguration
@EnableAdminServer
public class SpringBootAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootAdminApplication.class, args);
    }
}
----

NOTE: If you want to setup the Spring Boot Admin Server via war-deployment in a servlet-container, please have a look at the https://github.com/codecentric/spring-boot-admin/blob/master/spring-boot-admin-samples/spring-boot-admin-sample-war/[spring-boot-admin-sample-war].

See also the https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-servlet/[spring-boot-admin-sample-servlet] project, which also adds security.

[[register-client-applications]]
=== Registering client applications ===

To register your application at the SBA Server you can either include the SBA Client or use http://projects.spring.io/spring-cloud/spring-cloud.html[Spring Cloud Discovery] (e.g. Eureka, Consul, ...). There is also a <<spring-cloud-discovery-static-config,simple option using a static configuration on the SBA Server side>>.

[[register-clients-via-spring-boot-admin]]
==== Spring Boot Admin Client ====

Each application that wants to register has to include the Spring Boot Admin Client. In order to secure the endpoints also add the `spring-boot-starter-security`.

. Add spring-boot-admin-starter-client to your dependencies:
+
[source,xml,subs="verbatim,attributes"]
.pom.xml
----
<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-client</artifactId>
    <version>{project-version}</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
----

. Enable the SBA Client by configuring the URL of the Spring Boot Admin Server:
+
[source,yml]
.application.yml
----
spring.boot.admin.client.url: "http://localhost:8080"  #<1>
management.endpoints.web.exposure.include: "*"  #<2>
----
<1> The URL of the Spring Boot Admin Server to register at.
<2> As with Spring Boot 2 most of the endpoints aren't exposed via http by default, we expose all of them. For production you should carefully choose which endpoints to expose.

. Make the actuator endpoints accessible:
+
[source,java]
----
    @Configuration
    public static class SecurityPermitAllConfig extends WebSecurityConfigurerAdapter {
        @Override
        protected void configure(HttpSecurity http) throws Exception {
            http.authorizeRequests().anyRequest().permitAll()  //<1>
                .and().csrf().disable();
        }
    }
----
<1> For the sake of brevity we're disabling the security for now. Have a look at the <<securing-spring-boot-admin,security section>> on how to deal with secured endpoints.


[[discover-clients-via-spring-cloud-discovery]]
==== Spring Cloud Discovery ====

If you already use Spring Cloud Discovery for your applications you don't need the SBA Client. Just add a DiscoveryClient to Spring Boot Admin Server, the rest is done by our AutoConfiguration.

The following steps uses Eureka, but other Spring Cloud Discovery implementations are supported as well. There are examples using https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-consul/[Consul] and https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-zookeeper/[Zookeeper].

Also have a look at the http://projects.spring.io/spring-cloud/spring-cloud.html[Spring Cloud documentation].

. Add spring-cloud-starter-eureka to you dependencies:
+
[source,xml]
.pom.xml
----
include::{samples-dir}/spring-boot-admin-sample-eureka/pom.xml[tags=dependency-eureka,indent=0]
----

. Enable discovery by adding `@EnableDiscoveryClient` to your configuration:
+
[source,java]
----
@Configuration
@EnableAutoConfiguration
@EnableDiscoveryClient
@EnableAdminServer
public class SpringBootAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootAdminApplication.class, args);
    }

    @Configuration
    public static class SecurityPermitAllConfig extends WebSecurityConfigurerAdapter {
        @Override
        protected void configure(HttpSecurity http) throws Exception {
            http.authorizeRequests().anyRequest().permitAll()  //<1>
                .and().csrf().disable();
        }
    }
}
----
<1> For the sake of brevity we're disabling the security for now. Have a look at the <<securing-spring-boot-admin,security section>> on how to deal with secured endpoints.


. Tell the Eureka client where to find the service registry:
+
[source,yml]
.application.yml
----
include::{samples-dir}/spring-boot-admin-sample-eureka/src/main/resources/application.yml[tags=configuration-eureka]
----
<1> Configuration section for the Eureka client
<2> As with Spring Boot 2 most of the endpoints aren't exposed via http by default, we expose all of them. For production you should carefully choose which endpoints to expose.

See also https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples/spring-boot-admin-sample-eureka/[spring-boot-admin-sample-eureka].

TIP: You can include the Spring Boot Admin Server to your Eureka server. Setup everything as described above and set `spring.boot.admin.context-path` to something different than `"/"` so that the Spring Boot Admin Server UI won't clash with Eureka's one.