Docs Developer Site

Run XP as a service

Contents

Step-by-step guide for running Enonic XP as a service.

Windows

Setup

Download service wrapper

Start by downloading Windows service wrapper binary from this popular Github repo. Rename the downloaded file to desired service name, i.e winsw-2.2.0-bin.exe → xp-service.exe

Create service config

Create new xml file named xp-service.xml in the same location as xp-service.exe file.

xml file must be named exactly the same as exe in order for the service to discover it

Refer to the config description to see all available options.

The %BASE% variable always points to the config file location:

<service>
    <id>xp-service</id>
    <name>Enonic XP Service</name>
    <description>Enonic XP distribution run as a MS Windows service.</description>
    <env name="XP_INSTALL" value="%BASE%/enonic-xp-windows-sdk-7.0.0"/> (1)
    <env name="JAVA_HOME" value="%XP_INSTALL%/jdk"/> (2)
    <env name="XP_HOME" value="%BASE%/xp-service-home"/> (3)
    <executable>%XP_INSTALL%/bin/server.bat</executable>
    <log mode="roll-by-size-time"> (4)
        <sizeThreshold>10240</sizeThreshold>
        <pattern>dd-MM-yyyy</pattern>
        <autoRollAtTime>00:00:00</autoRollAtTime>
        <keepFiles>7</keepFiles>
    </log>
    <serviceaccount> (5)
        <domain>***user domain***</domain>
        <user>***user name***</user>
        <password>***user password***</password>
        <allowservicelogon>true</allowservicelogon>
    </serviceaccount>
</service>
1 XP_INSTALL sets the location of your unzipped enonic XP distribution
2 JAVA_HOME specifies location of Java within the XP distro (system-wide JAVA_HOME will be used if omitted)
3 XP_HOME defines the location of Enonic XP home folder (defaults to %XP_INSTALL%/home)
4 log rotates log using <pattern> provided by both date and file size
5 serviceaccount specifies user account (and password) that the service will run as (allowservicelogon will automatically be set to true for specified user)
To know your user name and domain type set user in cmd and hit enter

Usage

You need to start cmd.exe with administrator permissions to run service commands

Install

First, we need to install our new service. Run the following command:

xp-service.exe install

Verify that the service was installed by looking at the output:

2019-06-20 18:09:38,107 INFO  - Installing the service with id 'xp-service'

where xp-service.exe is the name of the service wrapper you downloaded earlier.

Check status

You can check its status now by running following command:

xp-service.exe status

If you have not already started the service, you should see the following:

Stopped

Start

Service is stopped by default and must be started with the following command:

xp-service.exe start

You should see something like this in the output:

2019-06-20 18:12:44,698 INFO  - Starting the service with id 'xp-service'

Stop

To stop the service type:

xp-service.exe stop

You should now see something like this:

2019-06-20 18:17:14,588 INFO  - Stopping the service with id 'xp-service'

Uninstall

To uninstall the service execute:

xp-service.exe uninstall

Should produce output as follows:

2019-06-20 18:18:02,356 INFO  - Uninstalling the service with id 'xp-service'

Linux

Setup

Create a new systemd service file xp.service with the following command:

sudo touch /etc/systemd/system/xp.service

Once xp.service file is created you can add the service configuration options that allow to manage this service using systemctl. The template of service configuration you can find here.

Pay your attention to the following configuration options:

  • Environment=XP_INSTALL=/opt/enonic/xp - XP_INSTALL sets the location of your unzipped Enonic XP distribution.

  • Environment=XP_JAVA_HOME=${XP_INSTALL}/jdk - XP_JAVA_HOME specifies location of Java within the XP distro (system-wide JAVA_HOME will be used if omitted).

  • ExecStart=/opt/enonic/xp/bin/server.sh - commands with their arguments that are executed when this service is started. For each of the specified commands, the first argument must be an absolute path to an executable. You can find more details here.

  • User and Group - make sure that you have a user and a group in the system which are specified in your file with correct privileges to be able to execute files from directories specified in the XP_INSTALL env variable and ExecStart option.

It might also be useful to increase the operating system limits on mmap to avoid the out of memory exceptions. To set a new value permanently, update the vm.max_map_count=262144 setting in /etc/sysctl.conf.

Once the xp.service file is changed we can reload systemctl configuration to be able to start, stop, restart and check the status of the service with the following command:

sudo systemctl daemon-reload

Usage

Check status

You can check the status with the following command:

sudo systemctl status xp.service

You should see something like this in the output:

● xp.service - Enonic XP
 Loaded: loaded (/etc/systemd/system/xp.service; disabled; vendor preset: enabled)
 Active: inactive (dead)
   Docs: https://developer.enonic.com/docs

Start

Service is stopped by default and must be started it with the following command:

sudo systemctl start xp.service

If you check the status again you should see something like this in the output:

● xp.service - Enonic XP
   Loaded: loaded (/etc/systemd/system/xp.service; disabled; vendor preset: enabled)
   Active: active (running) since Fri 2020-11-20 23:46:34 +03; 4s ago
     Docs: https://developer.enonic.com/docs
 Main PID: 13406 (java)
    Tasks: 118 (limit: 4915)
   CGroup: /system.slice/xp.service
           └─13406 /opt/enonic/xp/jdk/bin/java -XX:+CMSParallelRemarkEnabled -XX:+UseCMSInitiatingOccupancyOnly

If you want to start the xp.service service automatically when the system boots up, execute the following command:

sudo systemctl enable xp.service

You should see something like this in the output:

Created symlink /etc/systemd/system/multi-user.target.wants/xp.service → /etc/systemd/system/xp.service.

If you check the service status you should see something like this in the output:

● xp.service - Enonic XP
   Loaded: loaded (/etc/systemd/system/xp.service; enabled; vendor preset: enabled)
   Active: inactive (dead)
     Docs: https://developer.enonic.com/docs

Stop

To stop the service use the following command:

sudo systemctl stop xp.service

Uninstall

To uninstall the service use the following commands:

sudo systemctl stop xp.service

sudo systemctl disable xp.service

sudo rm /etc/systemd/system/xp.service

sudo systemctl daemon-reload

sudo systemctl reset-failed

Contents