Spring Boot 003: Spring Boot Admin and GreenMail

Previous article: Spring Boot 002: A Simple Model with Faker

Well, hello again. In this article I’ll be introducing you to a library called Spring Boot Admin and walk you through its set up and integration. In order to use mail notifications of Spring Boot Admin I’ll be using a tool called GreenMail.

Spring Boot Admin’s logo

0. About

As mentioned in the library’s homepage Spring Boot Admin is a tool that provides an Admin UI for administration of spring boot applications. As far as I’ve seen, it’s the best monitoring library with really easy integration for Spring Boot applications. So let’s just start.

1. Set Up

Well, since I already built a Spring Boot application called Atem on previous articles I’ll be using it as client and going to create a new one called Atua as admin.

You can simply generate yours by clicking this link and customize it for yourself. Either way I’ll add final version of mine to the bottom of this article. (Tbh from this point on you can close this page and continue from the guide itself, it’s really good.)

I’d like to change properties file such as:

spring.application.name=atua
server.port=2882

This admin application requires 2 dependencies: Spring Boot Admin itself and Spring Web. So make sure that pom.xml file has following lines:

<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-server</artifactId>
    <version>2.1.6</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

• Currently start.spring.io is providing 2.1.5 as version however latest one is 2.1.6 so I’ll be using 2.1.6.

After that add these 2 annotations to your application’s starter class to make Spring Boot Admin configuration accessible by your application:

@Configuration
@EnableAdminServer
@SpringBootApplication
public class AtuaApplication {

   public static void main(String[] args) {
      SpringApplication.run(AtuaApplication.class, args);
   }

}

Actually only these steps are enough to get a runnable Spring Boot Admin application. At this point you can simply run it and visit http://localhost:2882/ for the following screen.

Admin UI — Applications

However, if you’re building an admin application you should have some level of security. So let’s add Spring Security dependency to our project and create a config class that handles requests.

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-security</artifactId>
</dependency>

SecuritySecureConfig.java

com.tahaburak.atua.config.SecuritySecureConfig.java

SecuritySecureConfig.java

It’s going to way better if you click this link to view this class. SecuritySecureConfig.java provides us the following:

• Grants public access to all static assets and the login page.
• Every other request must be authenticated.
• Configures login and logout.
• Enables HTTP-Basic support. This is needed for the Spring Boot Admin Client to register.
• Enables CSRF-Protection using Cookies.
• Disables CRSF-Protection the endpoint the Spring Boot Admin Client uses to register.
• Disables CRSF-Protection for the actuator endpoints.

Let’s run our application again.

Admin UI — Login

Yup, now we need a username and password to enter Admin’s UI. Since we implemented Spring Security without any properties that can be used for username and password it creates a user and generates a password.By default username is “user” and you can find the generated password in your consele at the following lines:

2019-12-09 00:07:36.459  INFO 75301 --- [           main] .s.s.UserDetailsServiceAutoConfiguration :
Using generated security password: ****

However setting up a username and password will be helping us a lot so let’s update application.properties file.

spring.application.name=atua
server.port=2882
spring.security.user.name=admin
spring.security.user.password=notSoSecurePassword

2. Client

In order integrate a Spring Boot application with an Admin application we need follow couple of steps. Visit your will-be-client application’s pom.xml file and add following dependency:

<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-client</artifactId>
    <version>2.1.6</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

And tweak the applications.properties file as such:

spring.boot.admin.client.url=http://localhost:2882/
management.endpoints.web.exposure.include=*
spring.boot.admin.client.username=admin
spring.boot.admin.client.password=notSoSecurePassword
spring.boot.admin.client.instance.prefer-ip=true
#logging.file=  Currently we don't have any

Let me explaint a bit:

• The url we’ve given is the address that Admin application is currently running.
• We’ve exposed all the endpoints since we’re working on simple application just serves the articles. But that’s certainly not a secure approach.
• If the address that you run your application has a specific domain name(such as localhost) you can show it on Admin’s UI. However I do prefer showing the ip.
• Spring Boot Admin is able to show log file or to change its log levels. However our application doesn’t have any log file as of now. So I just commented that one out.

We need to make the actuator endpoints accessible by creating a new class under a new package called config.

SecurityPermitAllConfig.java

@Configuration
public class SecurityPermitAllConfig extends WebSecurityConfigurerAdapter {
  @Override
  protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests().anyRequest().permitAll()
    .and().csrf().disable();
  }
}

So let’s run it.

atem on atua

• If you allowed Admin’s address to show notifications on your browser you got a notification when you ran your client application.

Just click on the application to see details.

Admin UI — Application Details

And that’s all you need to integrate your client application to an Admin application. From this point on you can see lots of details like metrics, configuration properties, jvm status, log file, caches etc. of your client applications.

3. GreenMail

GreenMail is an open source, intuitive and easy-to-use test suite of email servers for testing purposes. The best part is GreenMail provides different deployment models, such as a simple standalone JVM process, as a WAR module, as a JBoss GreenMail Service or docker image. If you have an application that sends mails you can use GreenMail by implementing it to your project or by running it on a docker environment.

I’ll be using stand alone version with following steps:

• Visit the download section at this link.
• Download the latest stand alone version.
• Then run it via: java [OPTIONS] -jar greenmail-standalone.jar

Let’s look at the [OPTIONS] section:

• -Dgreenmail.setup.all : Start all default mail services using default ports. SMTP : 25, IMAP : 143, POP3 : 110
• -Dgreenmail.hostname : Configures the default hostname or ip bind address. Default hostname is 127.0.0.1 .
• -Dgreenmail.users=user1[, …, userN] : Configures the user mail boxes including password. The list of users is comma separated.A single user is of format logon:password[@domain] , where the domain part is optional.
• -Dgreenmail.auth.disabled : Disables user authentication check, so that any password works. Useful if you do not want to preconfigure user/passwords. GreenMail automatically creates non existent users.
• -Dgreenmail.verbose : Enables verbose mode. Useful if you want to see debug and protocol level output.

For example you can run your mail server by pasting following lines to your terminal:

sudo java -Dgreenmail.setup.all  -Dgreenmail.verbose -Dgreenmail.startup.timeout=20000 -Dgreenmail.users=admin:notSoSecurePassword@localhost.com,receiver:notSoSecurePassword@localhost.com\  -jar greenmail-standalone-1.5.11.jar

Well, let me explain a bit. I’ve decided to run two users on my GreenMail instance so that I can test if it’s able send and receive emails from another account.

GreenMail is using SMTP and IMAP protocols so lots of mail clients are able to integrate with it. I’ve decided to use Thunderbird because it supports lots of operations systems and languages. Just download it and implement your mail accounts as shown.

Repeat the same steps for receiver account. After that you should be able to see your inbox. Just send a random email to receiver one and check if it’s there.

Voilà! We have implemented GreenMail successfully.

4. Mail and Slack Integration

The notification we got from the browser is great, if you have your admin address is open on your browser and you were looking at the screen. However, most of the time that’s not the case in real life. Things usually go sideways when you’re not looking at it 😑.

Luckily Spring Boot Admin provides couple of other notification integrations such as Mail, Slack, Discord, Hipchat, Telegram. Since we’ve implemented GreenMail let’s test is out.

First of all add Spring Mail dependency to your Admin application’s pom.xml file.

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-mail</artifactId>
</dependency>

And update your application.properties file as below:

# spring mail properties
spring.mail.host=127.0.0.1
spring.mail.port=25
spring.mail.username=admin
spring.mail.password=notSoSecurePassword
spring.mail.protocol=smtp
spring.mail.test-connection=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.timeout=20000
spring.mail.properties.mail.smtp.starttls.required=false
spring.mail.default-encoding=UTF-8
# spring boot admin mail notification properties
spring.boot.admin.notify.mail.enabled=true
spring.boot.admin.notify.mail.from="admin@localhost"
spring.boot.admin.notify.mail.to=receiver@localhost.com

In order to test if we’re able to integrate mail notifications:

1. Run your admin application.
2. Run the client application.
3. Close the client application.

You should be able view an email on your receiver account as such:

You can simply run the client application again:

Let’s try to connect a Slack channel to our Admin application with the following steps:

• You might want to create a new channel where you’ll get the notifications.

• Visit this link to create new Slack app.

• Activate Incoming WebHooks and add new one to your workspace.

• Copy generated webhook link and add it application properties file of your Admin application as shown below:

# spring boot admin slack notification properties
spring.boot.admin.notify.slack.enabled=true
spring.boot.admin.notify.slack.webhook-url= https://hooks.slack.com/services/***
spring.boot.admin.notify.slack.channel=atua

That’s it. Just follow the steps we did for testing mail integration to see results.

5. Conclusion

Well, if you created an application with Spring Boot it’s most likely that you’ll be creating another one sooner or later. So my suggestion is that to create an Admin application and integrate your applications with it. As you can see it’s really easy to create one and get notifications out of it.

Admin project Atua is at Github.

Client project Atem is at Github.

Sincerely,
Burak.