7 min read

Customizing Spring Boot startup Banner

November 30, 2020

When starting a Spring Boot application, you may have seen an ASCII art of the Spring Logo with the current spring version at the beginning of the logs. These banners are a callback to old days where displays and printers only supported ASCII. It is a nice thing that Spring Boot uses this concept to show its branding on the startup of the application.

The good news here is that we can fully customize the banner gets printed on the startup log. If you are an organization then you can put your company logo on the startup banner. Let’s see what I’m talking about. The default output at the startup looks like below.

Spring Boot default banner sample

In this output, first few lines show the text Spring in ASCII format followed by the spring boot version. Let’s See how to customize it.

Adding a custom banner

Spring Boot by default checks for banner content in the classpath with a file name banner.txt. So all you have to do is to create a file called banner.txt and keep it under src/main/resources directory. If you want to learn how the resources directory works, then read more about Spring Boot 2: Directory structure and Convention. Let’s test this by creating a banner.txt.

$ cat src/main/resources/banner.txt

  ____             _             _   _               
 / ___| _ __  _ __(_)_ __   __ _| | | | _____      __
 \___ \| '_ \| '__| | '_ \ / _` | |_| |/ _ \ \ /\ / /
  ___) | |_) | |  | | | | | (_| |  _  | (_) \ V  V / 
 |____/| .__/|_|  |_|_| |_|\__, |_| |_|\___/ \_/\_/  
       |_|                 |___/                     

Once the above file is added to the project, the startup message changes and here is the output. Same can be found in the GitHub link at the end of the post.

Spring Boot custom banner output

Adding Project Info to Banners

You can add context to the banner by adding predefined placeholders. For example, Adding the placeholders ${application.title}, ${application.formatted-version} and ${spring-boot.formatted-version} placeholders will pull information from the application JAR’s MANIFEST.MF file and display it on the banner section. Here is a sample output for that.

Spring Boot custom banner with placeHolders

Banners with colours and formatting

One more thing we can do is to add colours to our banners. This feature is possible due to ANSI encoding support in spring boot. To enable colours you need to follow two steps.

  1. Make sure the system supports ASCI colours.

    For instance, Windows CommandLine and Powershell don’t support asci with colours. So don’t bother wasting time with these environments. But IDEs like IntelliJ, Eclipse and others usually support ANSI colours regardless of the OS. For example, All the screenshots you see here are from Intellij running on my Windows PC.

    But most of the Linux shells would be able to show colours on a TTY session. Spring Boot has internal logic to detect if a system supports coloured output or not. So you don’t have to do anything in this regard. If you want to keep the colours as default behaviour you need to set spring.output.ansi.enabled property to always. The default value for this property is detect.

    spring.output.ansi.enabled=always
  2. Add ANSI colour encoding placeholders to banner.txt.

    To mark a text with yellow, wrap the content between ${AnsiColor.YELLOW} and ${AnsiColor.DEFAULT}. For background and text styles, the concept is the same but you should use AnsiBackground and AnsiStyle placeholder.

    ${AnsiStyle.BOLD}
       ${AnsiBackground.GREEN}${AnsiColor.BRIGHT_WHITE}  ____             _             _   _               ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
     ${AnsiBackground.GREEN}${AnsiColor.BRIGHT_WHITE}   / ___| _ __  _ __(_)_ __   __ _| | | | _____      __  ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
    ${AnsiBackground.GREEN}${AnsiColor.BRIGHT_WHITE}    \___ \| '_ \| '__| | '_ \ / _` | |_| |/ _ \ \/ \ / /   ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
    ${AnsiBackground.GREEN}${AnsiColor.BRIGHT_WHITE}     ___) | |_) | |  | | | | | (_| |  _  | (_) \ V  V /    ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
     ${AnsiBackground.GREEN}${AnsiColor.BRIGHT_WHITE}   |____/| .__/|_|  |_|_| |_|\__, |_| |_|\___/ \_/\_/    ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
       ${AnsiBackground.GREEN}${AnsiColor.BRIGHT_WHITE}       |_|                 |___/                     ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
    ${AnsiStyle.NORMAL}
    Artifact Name : ${AnsiBackground.BLUE}${AnsiColor.BRIGHT_WHITE} ${AnsiStyle.BOLD}${application.title}${AnsiStyle.NORMAL} ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
    Artifact Version: Artifact Version: ${AnsiBackground.BLUE}${AnsiColor.BRIGHT_WHITE}${AnsiStyle.BOLD}${application.formatted-version}${AnsiStyle.NORMAL} ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}
    Spring Boot Version: ${AnsiBackground.BLUE}${AnsiColor.BRIGHT_WHITE}${AnsiStyle.BOLD}${spring-boot.formatted-version}${AnsiStyle.NORMAL} ${AnsiColor.DEFAULT}${AnsiBackground.DEFAULT}

With all the above completed, You can see the coloured banner at the startup. Coloured Spring Boot startup banner

Using Images as Banners

So far we saw the banner.txt and how to customize it. but the problem with Banner text is that it becomes complex to design a logo out of it. In these cases, You can use a banner.png or banner.jpg. Spring Boot will convert the image into ASCII text and use it at the startup. All you have to do for this is to keep the banner image under src/main/resources directory. Here is the logo image that I tried with my setup.

Sample logo

And here is the output that was automatically generated by the spring boot. The behaviour is the same for jpg images as well.

Banner generated from logo

The surprise doesn’t end there. You can keep a GIF as a banner as well. Yes, An animated gif. For this, the banner file will be banner.gif. I have a simple banner.gif as shown below.

Sample gif

And here is the result of adding gif file as a banner.

Banner generated from GIF.gif

At this point, I have to say that GIF based approach doesn’t fit for all. Only some Linux shells will show the animation correctly. But it is still fun and interesting to know that feature like these are buried in Spring Boot.

Using Image banners along with text banners

What is the point adding image banners if we can’t add the contextual information like application version etc? That is why Spring Boot will load one of the matching images in the classpath followed by a banner.txt if present. Here is an output of banner.png and banner.txt in the classpath. For the sake of simplicity, I kept just the version information.

Banner with image and text components

Changing Banner file location

The banner text and banner image files are by default under classpath:banner*. But if you want to move these files somewhere else but still want to print banners, you can use the spring.banner.location and spring.banner.image.location properties to set the appropriate file names/

spring.banner.location=banner-production.txt
spring.banner.image.location=banner-image.png

disabling Banners

You can turn off the banner by setting the spring.main.banner-mode property to off. The default value for this properties entry is console which means the output is not part of the logs. Apart from off and console this property can take log as one more value where the banner info is printed on the logs. When log is set, there is no guarantee that the colours would work.

spring.main.banner-mode=off

Programmatic Approach to Banners

In a programmatic approach, we can change the banner mode. The below example is to print banner directly to log entries. And the setBanner method helps us to provide a fallback Banner if both banner.txt and banner image is not present in the classpath.

        SpringApplication springApplication = new SpringApplication(SpringBootBannerExampleApplication.class);
        springApplication.setBannerMode(Banner.Mode.LOG);
        springApplication.setBanner((environment, sourceClass, out) -> out.println("A Fallback Banner...!"));
        springApplication.run(args);

Things to consider

  1. Banners run at the startup and image-based banners take some time to process and print the image. This is not good for time-sensitive production systems. Setting Banner.Mode to OFF may be a good idea.
  2. When a different type of banner images present, then Spring Boot will look for GIF first then PNG then JPG.
  3. For image banners, You can set the image width in terms of the number of characters. For example, spring.banner.image.width was set to 50 in my previous banner.png example (default value is 76).
  4. Setting up spring.banner.image.pixelmode to block would provide better visual appealing. For this to work, your console should support UTF-8. Using pixel mode BLOCK for image banner