orachide.springboot_service

Ansible Role for Spring Boot App

This Ansible role installs a Spring Boot application as a service.

The role will copy the application's files to the server and start it. It can also create a system service (using SystemV init.d or Systemd) to manage the application.

Requirements

Your Spring Boot application should be packaged as a fully executable JAR, as explained here:

Spring Boot Deployment Guide

Here’s how to configure your Maven project:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <executable>true</executable>
    </configuration>
</plugin>

Role Variables

Variable	Required	Default Value	Description
sb_app_install_java	false	true	Install Java before installing the app.
sb_app_create_users	false	true	Create users before installing the app.
sb_app_name	true	None	Name of the application.
sb_app_group_id	true	None	Maven artifact group ID.
sb_app_artifact_id	true	None	Maven artifact ID.
sb_app_version	true	None	Maven artifact version.
sb_app_user	true	None	Owner of application files on the server.
sb_app_user_group	true	None	Group owning the application files.
sb_app_extension	true	jar	File extension of the artifact (e.g., jar, war).
sb_app_state	false	present	Set to present to install or absent to uninstall.
sb_app_classifier	false	None	Artifact file classifier (e.g., SOURCES, DOCS).
sb_maven_repository_url	false	Maven Official Repo	URL of the Maven repository.
sb_app_repository_username	false	None	Username for Maven repo authentication.
sb_app_repository_password	false	None	Password for Maven repo authentication.
sb_app_artifact_file	false	None	Local path to the artifact. If set, it won’t download from the Maven repo.
sb_local_maven_artifact_dowload	false	false	Should the artifact be downloaded locally first?
sb_applications_root_folder	false	/opt/applis	Root folder for application files.
sb_app_java_opts_xms	false	256M	Java XMS value.
sb_app_java_opts_xmx	false	1024M	Java XMX value.
sb_app_java_opts_others	false	None	Additional custom JAVA_OPTS.
sb_app_config_file_template_path	false	None	Path for the Spring application.yml template.
sb_app_config_file_final_name	false	application.yml	Final name of the configuration file (can be .yml or .properties).
sb_app_logback_file_template_path	false	None	Path for the Logback file template.
sb_app_healthcheck_urls	false	None	HTTP URLs for health checks (should be an array).
sb_app_healthcheck_ports	false	None	TCP ports for health checks (should be an array).
sb_app_service_java_home	false	None	Set the Java home to use.
sb_app_stop_wait_time	false	60 secs	Time in seconds to wait when stopping the application before a force shutdown.
sb_app_env	false	array with name and value	Environment variables that will be added to the EnvironmentFile.

Dependencies

This role can install Java using geerlingguy.java.
This role can create an application user using singleplatform-eng.users.

Example Playbook

Using Local Maven Artifact

- name: Converge
  hosts: all
  roles:
    - role: ansible-role-springboot
      sb_app_name: dummy-boot-app
      sb_app_group_id: fr.chidix
      sb_app_artifact_id: dummy-boot-app
      sb_app_version: 0.0.1-SNAPSHOT
      sb_app_extension: jar
      sb_app_user: sbuser
      sb_app_user_group: sbgroup
      sb_local_maven_artifact_dowload: false
      sb_app_artifact_file: "{{ playbook_dir }}/artifacts/dummy-boot-app-0.0.1-SNAPSHOT.jar"
      sb_app_config_file_template_path: "{{ playbook_dir }}/templates/dummy-boot-app-configuration.yml.j2"
      sb_app_java_opts_others: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=6006"
      sb_app_healthcheck_urls:
        - "http://localhost:8082/actuator/health"
      sb_app_healthcheck_ports:
        - 8082
      sb_app_env:
        - name: LOGGING_PATH
          value: "{{ sb_applications_root_folder }}/{{ sb_app_name | upper }}/logs"
        - name: SERVER_PORT
          value: 8080

Using Maven Artifact from Maven Repository

- name: Converge
  hosts: all
  roles:
    - role: ansible-role-springboot
      sb_app_as_a_service: true
      sb_app_name: dummy-boot-app
      sb_app_group_id: fr.chidix
      sb_app_artifact_id: dummy-boot-app
      sb_app_version: 0.0.1-SNAPSHOT
      sb_app_extension: jar
      sb_app_user: sbuser
      sb_app_user_group: sbgroup
      sb_maven_repository_url: https://my-private-maven-repository/repository/maven-snapshots/
      sb_app_repository_username: my-user
      sb_app_repository_password: my-very-secure-password
      sb_local_maven_artifact_dowload: false
      sb_app_config_file_template_path: "{{ playbook_dir }}/templates/dummy-boot-app-configuration.yml.j2"
      sb_app_healthcheck_urls:
        - "http://localhost:8082/actuator/health"
      sb_app_healthcheck_ports:
        - 8082
      sb_app_env:
        - name: LOGGING_PATH
          value: "{{ sb_applications_root_folder }}/{{ sb_app_name | upper }}/logs"
        - name: SERVER_PORT
          value: 8080

Deploy Multiple Microservices to the Same Hosts

- name: Converge
  hosts: all
  vars:
    sb_java_package: java-1.8.0-openjdk
    sb_app_as_a_service: true
    sb_app_extension: jar
    sb_applications_root_folder: /opt/applis
    sb_app_group_id: "org.springframework.samples.service.service"
  roles:
    - {
      role: "ansible-role-springboot",
      sb_app_name: "microservices-registration",
      sb_app_artifact_id: "my-frontend",
      sb_app_version: "2.0.0.RELEASE",
      sb_app_run_args: '"registration 8082"',
      sb_app_healthcheck_urls: [
        "http://localhost:8082/actuator/health"
      ]
    }
    - {
      role: "ansible-role-springboot",
      sb_app_name: "microservices-web",
      sb_app_artifact_id: "my-backend",
      sb_app_version: "2.0.0.RELEASE",
      sb_app_run_args: '"web 8083"',
      sb_app_healthcheck_urls: [
        "http://localhost:8083/actuator/health"
      ]
    }