Run JBoss as macOS Service

Overview

This guide provides step-by-step instructions for configuring JBoss Enterprise Application Platform (EAP) to run as a background service on macOS using launchd, the native macOS service management framework. Running JBoss as a service ensures automatic startup at boot time and provides better process management.

What is launchd?

launchd is macOS's built-in service management framework that replaces traditional Unix init systems. It manages daemons, applications, processes, and scripts that run automatically.

Prerequisites

Before you begin, ensure you have the following:

macOS system with administrator privileges
JBoss EAP 6.3 or later installed
Basic knowledge of terminal commands
Text editor for creating configuration files

Important Considerations

Root/sudo access is required to install the service
The service will run with the specified user's permissions
Ensure JBoss is properly configured and tested before converting to a service

Installation Steps

Step 1: Create the Launch Daemon Configuration

Create a property list (plist) file that defines the JBoss service configuration. This file tells macOS how to run and manage the JBoss process.

/Library/LaunchDaemons/jboss.plist

<?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>Label</key>
            <string>jboss</string>
        <key>Disabled</key>
        <false/>
        <key>KeepAlive</key>
            <dict>
                <key>SuccessfulExit</key>
                <false/>
            </dict>
        <key>Program</key>
            <string>/Users/sky/jboss-eap-6.3/bin/standalone.sh</string>
        <key>StandardOutPath</key>
            <string>/Users/sky/jboss-eap-6.3/out.log</string>
        <key>RunAtLoad</key>
            <true/>
        <key>UserName</key>
            <string>sky</string>
    </dict>
</plist>

Configuration Parameters

Key Parameters Explained:

Label: Unique identifier for the service (use lowercase, no spaces)
Disabled: Set to false to enable the service
KeepAlive: Automatically restart if the process exits
Program: Full path to the JBoss startup script
StandardOutPath: Location for stdout/stderr logs
RunAtLoad: Start service automatically at boot
UserName: User account to run the service

Customization Required

Replace the following values with your actual configuration:

/Users/sky/jboss-eap-6.3/bin/standalone.sh → Your JBoss installation path
/Users/sky/jboss-eap-6.3/out.log → Desired log file location
sky → Your macOS username

Step 2: Set Correct File Permissions

Set the appropriate file permissions to ensure the plist file can be read by the system but not modified by unauthorized users.

chmod 644 /Library/LaunchDaemons/jboss.plist

Permission Explanation

The 644 permission means:

Owner: read + write (6)
Group: read only (4)
Others: read only (4)

Step 3: Set File Ownership

Change the file ownership to root with the wheel group, which is required for system-level launch daemons.

sudo chown root:wheel /Library/LaunchDaemons/jboss.plist

Why root:wheel?

Launch daemons in /Library/LaunchDaemons/ must be owned by root:wheel to prevent unauthorized modifications and ensure proper execution by the system.

Step 4: Load and Start the Service

Load the service configuration into launchd to activate the JBoss service.

sudo launchctl load /Library/LaunchDaemons/jboss.plist

The service will start automatically according to the RunAtLoad setting in your plist file.

Service Management

Check Service Status

Verify that the JBoss service is running:

sudo launchctl list | grep jboss

Stop the Service

To stop the JBoss service:

sudo launchctl stop jboss

Unload the Service

To completely remove the service from launchd:

sudo launchctl unload /Library/LaunchDaemons/jboss.plist

Restart the Service

To restart the service:

sudo launchctl unload /Library/LaunchDaemons/jboss.plist
sudo launchctl load /Library/LaunchDaemons/jboss.plist

Troubleshooting

Service Not Starting

If the service fails to start, check the following:

Verify file paths are correct in the plist file
Check log files at the location specified in StandardOutPath
Ensure JBoss starts manually before converting to a service
Verify permissions on JBoss installation directory

# Test manual startup
/Users/sky/jboss-eap-6.3/bin/standalone.sh

Permission Errors

If you encounter permission errors:

# Ensure correct ownership
sudo chown -R sky:staff /Users/sky/jboss-eap-6.3

# Verify executable permissions
chmod +x /Users/sky/jboss-eap-6.3/bin/standalone.sh

View Service Logs

Monitor the service output:

# Real-time log monitoring
tail -f /Users/sky/jboss-eap-6.3/out.log

# View launchd system logs
log show --predicate 'subsystem == "com.apple.launchd"' --last 1h

Additional Configuration

Environment Variables

If JBoss requires specific environment variables, add them to your plist:

<key>EnvironmentVariables</key>
<dict>
    <key>JAVA_HOME</key>
    <string>/Library/Java/JavaVirtualMachines/jdk1.8.0_311.jdk/Contents/Home</string>
    <key>JBOSS_HOME</key>
    <string>/Users/sky/jboss-eap-6.3</string>
</dict>

Custom Startup Arguments

To pass arguments to JBoss, modify the Program key to ProgramArguments:

<key>ProgramArguments</key>
<array>
    <string>/Users/sky/jboss-eap-6.3/bin/standalone.sh</string>
    <string>-c</string>
    <string>standalone-full.xml</string>
    <string>-b</string>
    <string>0.0.0.0</string>
</array>

Best Practices

Recommendations

Use absolute paths for all file references in the plist
Test manually first before creating the service
Monitor logs regularly to catch issues early
Document customizations for future reference
Backup configuration files before making changes
Use separate log files for stdout and stderr if needed

Security Considerations

Run JBoss with a dedicated non-admin user when possible
Ensure log directories have appropriate permissions
Regularly update JBoss EAP to patch security vulnerabilities
Restrict network access to necessary ports only

Last Updated: October 19, 2025
Categories: Java, Linux, Web Servers
Tags: JBoss, macOS, launchd, service management