Page tree
Skip to end of metadata
Go to start of metadata

Overview

The most convenient way to start your pulse™ server (or agent) is by installing it as a service, so that it will automatically start when the host machine boots. Pulse supports running as a service on most common architectures, either as a Windows service, via new Linux init systems like systemd and upstart, or via a SysV-style init script (on Unix-like systems). For the latter a native binary is used to integrate with the init system, and it must be installed separately (usually an appropriate version is available via your system's package manager).

Installation and configuration of services is platform-dependent, so each platform is addressed separately below. 

Running as a Windows Service

Installation

When you install pulse™ using the Windows installer package, it is automatically installed as a service for you. Start menu items are added to start and stop the service, and it may also be controlled using the normal Windows service tools.

If you install via another means, you can still install the Windows service using the batch file $PULSE_HOME/bin/install-service.bat. Once the service is installed in this manner, it may be started and stopped using the normal Windows service tools. To uninstall the service (without uninstalling pulse™ itself), run $PULSE_HOME/bin/uninstall-service.bat.

Configuration

The pulse™ Windows service is implemented using Apache Commons Daemon. Commons Daemon provides a simple GUI for monitoring and configuring the service which as added to the Start Menu. You can also run this utility directly from $PULSE_HOME/bin/PulseServerw.exe (PulseAgentw.exe on agents). Most configuration changes you are likely to make are available on the "Java" tab, e.g. the size of the heap and additional JVM options.

User

By default, the pulse™ Windows serice will run as the LocalSystem user. You can configure the user via Commons Daemon GUI tool on the "Log On" tab. If your builds require access to the desktop (e.g. your tests run GUI tools) then you should check the "Allow server to interact with desktop" option. Note that the user running pulse™ must have read/write access to both the $PULSE_HOME and $PULSE_DATA directories.

Troubleshooting

When running as a service on Windows Pulse and Commons Daemon output are captured to log files under $PULSE_HOME/logs. This is the best place to check for clues if you are having trouble configuring or running the service. If the logs are not present or unhelpful, you can also check the Windows event logs which record high-level errors from services. One common issue is permissions on the $PULSE_HOME or $PULSE_DATA directory, so ensure that the user running pulse™ has read/write access to both of these locations.

Running as a systemd Service

Systemd is the preferred way to run  pulse™ as a service on Linux. With the support of most major distributions, systemd looks likely to become the new standard for services on Linux.

Installation

Systemd services are configured using .service unit configuration files. A .service file for  pulse™ can be found at $PULSE_HOME/bin/pulse.service. The basic installation process follows:

  1. Install prerequisites, e.g. a JDK using your system package manager.
  2. Install pulse™ in your desired directory. We recommend making a symbolic link to the current version so you can refer to it in a version-independent way (this simplifies later upgrades).
  3. If running pulse™ as a dedicated non-root user (strongly recommended), create that user and make it the owner of both the $PULSE_HOME and $PULSE_DATA directories.
  4. Copy $PULSE_HOME/bin/pulse.service to /usr/lib/systemd/system.
  5. Edit /usr/lib/systemd/system/pulse.service to match your configuration. In particular you may need to edit the ExecStart and ExecStop paths, and you may need to uncomment the User and Group lines.
  6. Enable and start the service using systemctl.

To check the status of the service you can run systemctl status -l pulse.

Concrete Example

For clarity, here is an example of the above installation process on Fedora. In this case we install pulse™ in the default location /usr/local/pulse and create a dedicated zutubi-pulse user to run it. All commands are run with superuser privileges, and we assume the pulse™ package has been downloaded to /usr/local:

# adduser zutubi-pulse
# mkdir /var/pulse-data
(this directory will be referenced later in the Pulse setup wizard)
# cd /usr/local
# tar zxvf pulse-2.7.0.tar.gz
# chown -R zutubi-pulse:zutubi-pulse pulse-2.7.0 /var/pulse-data
# ln -s pulse-2.7.0 pulse
# cp pulse/bin/pulse.service /usr/lib/systemd/system
# vi /usr/lib/systemd/system/pulse.service
(uncomment the User and Group lines, then save)
# systemctl enable pulse
# systemctl start pulse
# systemctl status -l pulse
(shows stdout, you can see Pulse processes and it starting up)

Once pulse™ has started you may connect to it using your browser (at port 8080 by default) and follow the setup wizard.

If you make any changes to the service file after the initial installation, you need to run systemctl daemon-reload for them to take effect.

Configuration

In addition to the settings in the .service file, you can also configure the environment of the pulse™ process by setting variables in a file at /etc/zutubi-pulse (/etc/zutubi-pulse-agent on agents). You will need to create this file the first time you edit it.

Troubleshooting

If pulse™ does not start as expected, you should first check the status of the service using systemctl -l pulse. For further details check the logs in $PULSE_HOME/logs.

Running as an Upstart Job

Upstart is an init replacement from Ubuntu. Although Ubuntu have decided to switch to systemd, we've shipped Upstart support for pulse™ anyway as it is a fairly simple wrapper around the normal start script.

Installation

Upstart jobs are configured using .conf files in the /etc/init directory. A .conf file for pulse™ is provided at $PULSE_HOME/bin/pulse.conf. The basic installation process follows:

  1. Install prerequisites, e.g. a JDK using your system package manager.
  2. Install pulse™ in your desired directory. We recommend making a symbolic link to the current version so you can refer to it in a version-independent way (this simplifies later upgrades).
  3. If running pulse™ as a dedicated non-root user (strongly recommended), create that user and make it the owner of both the $PULSE_HOME and $PULSE_DATA directories.
  4. Copy $PULSE_HOME/bin/pulse.conf to /etc/init.
  5. Edit /etc/init/pulse.conf to match your configuration. In particular you may need to edit the PULSE_HOME variable, and you may need to uncomment the setuid and setgid lines.
  6. Reload your configuration and start the service using initctl.

To check the status of the job you can run initctl status pulse.

Concrete Example

For clarity, here is an example of installing pulse™ as an Upstart job on Ubuntu. In this case we install pulse™ in the default location /usr/local/pulse and create a dedicated zutubi-pulse user to run it. All commands are run with superuser privileges, and we assume the pulse™ package has been downloaded to /usr/local:

# apt-get install openjdk-7-jdk
# adduser zutubi-pulse
# mkdir /var/pulse-data
(this directory will be referenced later in the Pulse setup wizard)
# cd /usr/local
# tar zxvf pulse-2.7.0.tar.gz
# chown -R zutubi-pulse:zutubi-pulse pulse-2.7.0 /var/pulse-data
# ln -s pulse-2.7.0 pulse
# cp pulse/bin/pulse.conf /etc/init
# vi /etc/init/pulse.conf
(uncomment the setuid and setgid lines then save)
# initctl reload-configuration
# initctl start pulse
# tail -f /var/log/upstart/pulse.log
(this shows stdout so you can watch Pulse starting up)

Once pulse™ has started you may connect to it using your browser (at port 8080 by default) and follow the setup wizard.

Configuration

The .conf file is a thin wrapper around the normal pulse™ start script $PULSE_HOME/bin/pulse, which in turn wraps $PULSE_HOME/bin/common.sh. Thus configuration methods that work with these scripts also work under Upstart. The simplest way to set environment variables is via env stanzas in the .conf file, see the existing PULSE_HOME setting for an example.

Upstart Job Environment

 When running as an upstart job pulse™ may have a very bare environment. You can verify this on the server info tab (or agent info tab) where environment variables are shown. You may find some of your build tools expect variables such as $HOME and $LANG to be set. If you start seeing warnings suggesting missing configuration (which may normally be found via $HOME) or file encoding problems (the default may be ASCII unless you specify $LANG) then check the environment you normally build under and set appropriate variables via env stanzas in pulse.conf.

Troubleshooting

If pulse™ does not start as expected, you should first check the status of the service using initctl -l pulse. For further details check the output in /var/log/upstart/pulse.log and the full logs in $PULSE_HOME/logs.

Running as a Unix Daemon via SysV-style init

For non-Linux systems, or users that prefer a more traditional init script, pulse™ can also be run via a SysV-style init script.

OSX Users

If you would like to use jsvc on OSX, then you will need to obtain the source and build a binary yourself. Note that at the time of writing the latest Commons Daemon release (1.0.15) has a bug preventing it from working with JDK 1.7. For this reason we recommend obtaining the latest source from the Subversion repository and building from there.

Installation

A SysV-style init script for pulse™ can be found at $PULSE_HOME/bin/init.sh. This script requires you to install a suitable jsvc binary from the Apache Commons Daemon project separately. The basic installation process follows:

  1. Install prerequisites, particularly jsvc using your system package manager. (On some systems the package is called jsvc, on others apache-commons-daemon-jsvc.)
  2. Install pulse™ in your desired directory. We recommend making a symbolic link to the current version so you can refer to it in a version-independent way (this simplifies later upgrades).
  3. If running pulse™ as a dedicated non-root user (strongly recommended), create that user and make it the owner of both the $PULSE_HOME and $PULSE_DATA directories.
  4. Copy $PULSE_HOME/bin/init.sh to /etc/init.d/pulse.
  5. Set environment variables in a new file /etc/zutubi-pulse (or directly edit them in /etc/init.d/pulse) to match your configuration. In particular you may need to set appropriate values for PULSE_HOME and PULSE_USER.
  6. Add runlevel links to the init script (the script includes LSB metadata that can be used by chkconfig or update-rd.d to add these links for you).
  7. Start the daemon by running /etc/init.d/pulse start.

To check the status of the job you can tail the output file $PULSE_HOME/logs/pulse.out (pulse-agent.out for agents).

Concrete Example

For clarity, here is an example of the above installation process on Fedora. In this case we install pulse™ in the default location /usr/local/pulse and create a dedicated zutubi-pulse user to run it. All commands are run with superuser privileges, and we assume the pulse™ package has been downloaded to /usr/local:

# yum install apache-commons-daemon-jsvc
# adduser zutubi-pulse
# mkdir /var/pulse-data
(this directory will be referenced later in the Pulse setup wizard)
# cd /usr/local
# tar zxvf pulse-2.7.0.tar.gz
# chown -R zutubi-pulse:zutubi-pulse pulse-2.7.0 /var/pulse-data
# ln -s pulse-2.7.0 pulse
# cp pulse/bin/init.sh /etc/init.d/pulse
# vi /etc/zutubi-pulse
(add the two lines below and save the file)
PULSE_HOME=/usr/local/pulse
PULSE_USER=zutubi-pulse
# chkconfig --add pulse
# service pulse start
# tail -f /usr/local/pulse/logs/pulse.out
(shows stdout, you can see Pulse processes and it starting up)

Once pulse™ has started you may connect to it using your browser (at port 8080 by default) and follow the setup wizard.

Configuration

The preferred way to configure the pulse™ environment is via a file at /etc/zutubi-pulse (zutubi-pulse-agent for agents, if you have a sysconfig area you may prefer /etc/sysconfig/zutubi-pulse). If you need to pass extra options to the pulse™ JVM you can do so by setting the PULSE_OPTS variable (keep in mind you may want to include the default arguments as shown in the existing init script). You can also edit the init script directly, directed by the comments at the top of the file.

Troubleshooting

If pulse™ does not start as expected, you should first check the output in $PULSE_HOME/logs/pulse.out and then the full logs in the other files in the same $PULSE_HOME/logs directory.

Running as an OS X service

Installation

If you are looking to install Pulse on OS X using launchd, the following .plist might come in handy.

 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple/com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>RunAtLoad</key>
	<true/>
	<key>KeepAlive</key>
	<true/>
	<key>UserName</key>
	<string>eng</string>
	<key>Label</key>
	<string>com.zutubi.pulse</string>
	<key>Program</key>
	<string>/usr/local/pulse-agent/bin/init.sh</string>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/local/pulse-agent/bin/init.sh</string>
		<string>start</string>
	</array>
	<key>EnvironmentVariables</key>
	<dict>
		<key>JAVA_HOME</key>
		<string>/Library/Java/Home</string>
	</dict>
</dict>
</plist>

A special thanks to Kate for providing us with this sample.

  • No labels