Spring Boot Application as a Service
Last modified: June 25, 2020
1. Overview
This article explores some options of running Spring Boot applications as a service.
Firstly, we are going to explain web applications’ packaging options and system services. In the subsequent sections, we explore different alternatives we have when setting up a service for both Linux as Windows based systems.
Finally, we will conclude with some references to additional sources of information.
2. Project Setup and Build Instructions
2.1. Packaging
Web applications are traditionally packaged as a Web Application aRchives (WAR) and deployed to a web server.
Spring Boot applications may be packaged both as WAR and JAR files. The latter embeds a web server within a JAR file, which allows you to run applications without the need of an installation and configuration of an application server.
2.2. Maven Configuration
Let’s start by defining the configuration of our pom.xml file:
The packaging must be set to jar. We are using the latest stable version of Spring Boot at the time of writing, but any version after 1.3 will be enough. You can find more information about available versions here.
Notice that we have set the parameter to true for the spring-boot-maven-plugin artifact. This makes sure that a MANIFEST.MF file is added to the JAR package. This manifest contains a Main-Class entry that specifies which class defines the main method for your application.
2.3. Building Your Application
Run the following command inside your application’s root directory:
The executable JAR file is now available in the target directory and we may start up the application by executing the following command on the command line:
At this point, you still need to invoke the Java interpreter with the -jar option. There are many reasons why it would be preferable to have your app started by being able to invoke it as a service.
3. On Linux
In order to run a program as a background process, we could simply use the nohup Unix command, but this is not the preferred way either for various reasons. A good explanation is provided in this thread.
Instead, we are going to daemonize our process. Under Linux, we may choose to configure a daemon either with a traditional System V init script or with a Systemd configuration file. The former is traditionally the most well-known option but is gradually being replaced by the latter.
You may find more details on this difference here.
For enhanced security we first create a specific user to run the service with and change the executable JAR file permissions accordingly:
3.1. System V Init
A Spring Boot executable JAR file makes the service setup process very easy:
The above command creates a symbolic link to your executable JAR file. You must use the full path to your executable JAR file, otherwise, the symbolic link will not work properly. This link enables you to start the application as a service:
The script supports the standard service start, stop, restart and status commands. Moreover:
- it starts the services running under the user baeldung we have just created
- it tracks the application’s process ID in /var/run/your-app/your-app.pid
- it writes console logs to /var/log/your-app.log, which you may want to check in case your application fails to start properly
3.2. Systemd
The systemd service setup is very simple as well. Firstly, we create a script named your-app.service using the following example and put it in /etc/systemd/system directory:
Remember to modify Description, User and ExecStart fields to match your application. You should be able to execute the aforementioned standard service commands at this point as well.
As opposed to the System V init approach described in the previous section, the process ID file and console log file should be configured explicitly using appropriate fields in the service script. An exhaustive list of options may be found here.
3.3. Upstart
Upstart is an event-based service manager, a potential replacement for the System V init that offers more control on the behavior of the different daemons.
The site has good setup instructions that should work for almost any Linux distribution. When using Ubuntu you probably have it installed and configured already (check if there are any jobs with a name starting with “upstart” in /etc/init).
We create a job your-app.conf to start our Spring Boot application:
Now run “start your-app” and your service will start.
Upstart offers many job configuration options, you can find most of them here.
4. On Windows
In this section, we present a couple of options that may be used to run a Java JAR as a Windows service.
4.1. Windows Service Wrapper
Due to difficulties with the GPL license of the Java Service Wrapper (see next subsection) in combination with e.g. the MIT license of Jenkins, the Windows Service Wrapper project, also known as winsw, was conceived.
Winsw provides programmatic means to install/uninstall/start/stop a service. In addition, it may be used to run any kind of executable as a service under Windows, whereas Java Service Wrapper, as implied by its name, only supports Java applications.
First, you download the binaries here. Next, the configuration file that defines our Windows service, MyApp.xml, should look like this:
Finally, you have to rename the winsw.exe to MyApp.exe so that its name matches with the MyApp.xml configuration file. Thereafter you can install the service like so:
Similarly, you may use uninstall, start, stop, etc.
4.2. Java Service Wrapper
In case you don’t mind the GPL licensing of the Java Service Wrapper project, this alternative may address your needs to configure your JAR file as a Windows service equally well. Basically, the Java Service Wrapper also requires you to specify in a configuration file which specifies how to run your process as a service under Windows.
This article explains in a very detailed way how to set up such an execution of a JAR file as a service under Windows, so we there’s no need to repeat the info.
5. Additional References
Spring Boot applications may also be started as Windows service using Procrun of the Apache Commons Daemon project. Procrun is a set of applications that allow Windows users to wrap Java applications as Windows services. Such a service may be set to start automatically when the machine boots and will continue to run without any user being logged on.
More details on starting Spring Boot applications under Unix may be found here. There are also detailed instructions on how to modify Systemd unit files for Redhat based systems. Finally
Finally, this quick howto describes how to incorporate a Bash script into your JAR file, so that it becomes an executable itself!
6. Conclusion
Services allow you to manage your application state very efficiently and, as we have seen, service setup for Spring Boot applications is now easier than ever.
Just remember to follow the important and simple security measures on user permissions to run your service.
Начало работы с микросервисами в Spring Boot
В этой статье мы продемонстрируем основные компоненты для создания RESTful микросервисов, используя реестр служб Consul, Spring Boot для всего скаффолдинга, инжекции зависимостей, Maven для сборки, а также Spring REST и Jersey/JaxRS API Java RESTful.
Основные преимущества микросервисов:
- Микросервисы позволяют ослабить зацепленность вашего кода
- Микросервисы позволяют различным командам работать над небольшими составляющими, используя независимые технологии, обеспечивая более безопасное и частое развертывание Spring Boot поддерживает различные реализации для создания REST API
- Обнаружение и вызов сервисов не зависят от сервисной платформы
- Swagger создает надежную документацию API и интерфейс вызова
Если вы еще не используете микросервисы, вы благополучно не успели в фазу ранних последователей на кривой восприятия технологии, и, вероятно, как раз самое время начинать.
За последние два десятилетия предприятие стало очень гибким в нашем SDLC-процессе, но наши приложения, как правило, по-прежнему остаются монолитными, с огромными jar-ами, поддерживающими все разнообразные API и версии на рынке. Но в настоящее время существует стремление к более Lean, DevOps-ным процессам, а функциональность становится «безсерверной». Рефакторинг в микросервисы может уменьшить зацепленность кода и ресурсов, сделать сборки меньше, релизы безопаснее, а API более стабильными.
В этой статье мы создадим простое приложение для управления портфелем на фондовом рынке, которое клиенты могут вызывать для оценки своего портфеля акций (биржевые тикеры и величины). Микросервис портфеля будет извлекать портфель клиента, отправлять его в микросервис ценообразования для применения последних цен, а затем возвращать полностью оцененный и субтотализированный портфель, демонстрируя все это посредством rest-вызова.
Прежде чем мы начнем работу над созданием наших микросервисов, давайте подготовим нашу среду, настроив Consul.
Загрузите Consul
Мы будем использовать Hashicorp Consul для обнаружения сервисов, поэтому перейдите на www.consul.io/downloads.html и загрузите Consul для Windows, Linux, Mac и т.д. Это предоставит вам исполняемый файл, который нужно добавить к своему пути.
Запустите Consul
В командной строке запусктие Consul в режиме dev:
Чтобы убедиться, что он запущен, перейдите в браузер и получите доступ к интерфейсу консула http://localhost:8500. Если все будет хорошо, консул должен сообщить, что он жив и здоров. Нажав на службу консула (слева), вы получите дополнительную информацию (справа).
Если на данный момент есть какие-либо проблемы, убедитесь, что вы добавили Consul к пути выполнения, и доступны порты 8500 и 8600.
Создайте приложение SpringBoot
Мы будем использовать Spring Initializr, который интегрирован в большинство IDE, для скаффолдинга наших SpringBoot приложений. Скриншоты ниже используют IntelliJ IDEA.
Выберите «File/New Project», чтобы открыть новый шаблон проекта, и затем «Spring Initializr».
Вообще, вы можете настроить скаффолдинг без IDE, заполнив онлайн-форму через веб-страницу SpringBoot Initializr start.spring.io, которая создаст zip-файл вашего пустого проекта, готовый для загрузки.
Нажмите «Next» и заполните метаданные проекта. Используйте следующую конфигурацию:
Нажмите «Next», чтобы выбрать зависимости, и введите «Jersey» и «Consul Discovery» в поиске зависимостей. Добавьте эти зависимости:
Нажмите «Next», чтобы указать название проекта и его расположение. Сохраните имя по умолчанию «portfolio» и укажите предпочтительное расположение проекта, затем нажмите «finish», чтобы создать и открыть проект:
Мы можем использовать сгенерированные application.properties, но SpringBoot также распознает формат YAML, что немного легче визуализировать, поэтому давайте переименуем его в application.yml.
Назовем микросервис «portfolio-service». Мы можем указать порт или использовать порт 0, чтобы приложение использовало доступный порт. В нашем случае мы будем использовать 57116. Если вы разместите эту службу в качестве контейнера Docker, вы сможете сопоставить ее с любым выбранным вами портом. Назовите приложение и укажите наш порт, добавив следующее к нашему application.yml:
Чтобы сделать наш сервис доступным, добавим аннотацию к нашему классу приложений SpringBoot. Откройте приложение PortfolioApplication и добавьте @EnableDiscoveryClient над объявлением класса.
Подтвердите импорты. Класс должен выглядеть следующим образом:
(Чтобы продемонстрировать, как микросервисы могут состоять из независимых платформ, мы будем использовать Jersey для этого сервиса и Spring REST для следующего).
Чтобы настроить веб-службу RESTful на Jersey, нам нужно указать класс конфигурации ResourceConfig. Добавьте класс JerseyConfig (для демонстрации мы сохраним его в том же пакете, что и наш класс приложения). Это должно выглядеть так, плюс правильный пакет и импорт:
Обратите внимание, что он наследуется от ResourceConfig, чтобы обозначить его как класс конфигурации Jersey. Атрибут @ApplicationPath («portfolios») определяет контекст вызова, а это означает, что вызовы должны начинаться с элемента пути «portfolios». (Если вы его опустите, контекст по умолчанию «/»).
Класс PortfolioImpl будет обслуживать два запроса: portfolios/customer/
Ваша IDE попросит вас создать PortfolioImpl; сделайте это сейчас. Для демонстрации добавим его в тот же пакет. Введите код ниже и подтвердите все импорты:
Аннотация Component обозначает это как класс компонента Spring и предоставляет его как эндпоинт. Аннотации Path о объявлении класса объявляют, что к классу обращаются через элемент пути “/”, а два поддерживаемых вызова api доступны через portfolios/customer/
(Для нашего демо мы возвращаем захардкоженные значения. Конечно, на практике реализация будет запрашивать базу данных или другую службу или источник данных вместо хардкода.)
Теперь создайте проект и запустите его. Если вы используете IntelliJ, он создаст исполняемый файл по умолчанию, поэтому просто нажмите зеленую стрелку «run». Вы также можете использовать
Или вы можете выполнить установку maven и запустить приложение с помощью java -jar, указав на сгенерированный jar в целевом каталоге:
Теперь мы должны увидеть этот сервис в Consul, поэтому давайте вернемся к нашему браузеру, загрузите http://localhost:8500/ui/#/dc1/services (или обновите, если вы уже там).
Хм, мы видим там наш сервис, но он отображен как неудавшийся. Это потому, что Consul ожидает «здорового» heartbeat-сигнала от нашей службы.
Чтобы генерировать heartbeat-сигналы, мы можем добавить зависимость от службы Spring «Actuator» к pom нашего приложения.
В то время как мы находимся в pom-е, обратите внимание, что существует конфликт версий с Jersey между Consul-стартером и Jersey-стартером. Чтобы сгладить это, назначьте Jersey-стартер первой зависимостью.
Теперь ваш pom должен содержать следующие зависимости:
Перезапустив Consul, служба Portfolio отображает счастливое:
Теперь в portfolio-service есть два передающих узла: один из них — наша реализация портфельного сервиса, а другой — heartbeat.
Давайте проверим порт, который был назначен. Вы можете видеть, что в выводе приложения:
Вы также можете увидеть порт непосредственно в пользовательском интерфейсе Consul. Нажмите «customer-service», затем выберите ссылку «Service ‘customer-service’ check link», в которой отображается служебный порт, в данном случае 57116.
Наш первый микросервис открыт для бизнеса!
Сервис ценообразования
Далее мы создадим наш сервис ценообразования, на этот раз используя Spring RestController вместо Jersey.
Служба ценообразования будет принимать в качестве параметров идентификатор клиента и идентификатор портфеля и будет использовать RestTemplate для запроса услуги портфеля, получения тикеров и акций и возврата текущих цен. (Мне не нужно говорить вам, что эти значения — это поддельные новости, поэтому не используйте их для принятия торговых решений!)
Создайте новый проект, используя следующую информацию:
На этот раз выберите зависимости Web, Consul Discovery и Actuator:
Оставьте название проекта по умолчанию «pricing» и создайте проект в выбранном вами каталоге.
На этот раз мы будем использовать application.properties вместо application.yml.
Задайте имя и порт в application.properties как:
Аннотируйте PricingApplication с @EnableDiscoveryClient. Класс должен выглядеть так, плюс пакет и импорт.
Затем мы создадим класс PricingEndpoint. Здесь я приведу более подробный пример, поскольку он демонстрирует несколько важных функций, включая обнаружение сервисов (поиск портфельной службы) и использование RestTemplate для запроса:
Чтобы найти портфельный сервис, нам необходимо иметь доступ к DiscoveryClient. Его легко получить с помощью аннотации Spring’s @Autowired.
Этот экземпляр DiscoveryClient затем используется для поиска службы в вызове:
После того, как служба найдена, мы можем использовать ее для выполнения нашего запроса, который мы составляем в соответствии с вызовом api, созданным в нашем портфельном сервисе.
Наконец, мы используем RestTemplate для выполнения нашего GET-запроса.
Обратите внимание, что для Rest-контроллеров (как и для Spring MVC Request Controller) переменные пути извлекаются с помощью аннотации PathVariable, в отличие от Jersey, который, как мы видели, использует PathParam.
На этом мы завершаем наше ценообразование с помощью Spring RestController.
Документация
Мы решили все эти проблемы, чтобы создать наши микросервисы, но они не будут приносить достаточно пользы, если мы не дадим миру знание о том, как их использовать.
Для этого мы используем удобный и простой в использовании инструмент Swagger, который не только документирует наши вызовы API, но также предоставляет удобный веб-клиент для их вызова.
Во-первых, давайте укажем Swagger в нашем pom:
Затем нам нужно указать Swagger, какой из наших классов мы хотим документировать. Давайте представим новый класс SwaggerConfig, содержащий спецификацию Swagger.
Посмотрим, что делает этот класс. Сначала мы обозначили это как конфигурацию Swagger с аннотацией @ EnableSwagger2.
Затем мы создали компонент Docket, который сообщает Swagger, какие API-интерфейсы должны отображаться. В приведенном выше примере мы сказали Swagger продемонстрировать любой путь, начинающийся с «/pricing». Альтернативой было бы указать классы для документирования, а не для путей:
Перезапустите ценовой микросервис и вызовите из браузера http://localhost:57216/swagger-ui.html
Нажмите «List Operations», чтобы подробно просмотреть операции сервиса.
Нажмите «Expand Operations», чтобы создать запрос на основе формы. Задайте некоторые параметры, нажмите «Try it out!» и дождитесь ответа:
Вы можете добавить намного больше цветов, добавив аннотации Swagger к вашим методам.
Например, украсьте существующий метод PricingImpl.getPricedPortfolio, используя аннотацию @ApiOperation, как показано ниже:
Перезагрузите и обновите swagger-ui, чтобы увидеть новую уточненную документацию:
И это далеко не все, что вы можете сделать с Swagger, поэтому ознакомьтесь с документацией.
Еще больше о работе Spring Boot вам расскажет Юрий Дворжецкий, преподаватель нашего курса «Разработчик на Spring Framework»: