Running as a Service

Configure BPDMX to start automatically and run in the background on your production systems.

Overview

Running BPDMX as a service ensures it:

Starts automatically when the system boots
Restarts automatically if it crashes
Runs in the background without requiring a logged-in user
Can be managed via standard system tools

Choose the section below for your operating system.

🐧 Linux (systemd)

Most modern Linux distributions use systemd for service management.

1. Create the Service File

Create /etc/systemd/system/bpdmx.service:

[Unit]
Description=BPDMX Server
After=network.target

[Service]
Type=simple
User=bpdmx
Group=bpdmx
WorkingDirectory=/opt/bpdmx
ExecStart=/opt/bpdmx/bpdmx serve --port 8512
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# Optional: Set environment variables
# Environment=ASPNETCORE_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

2. Create a Service User (Recommended)

# Create a dedicated user for the service
sudo useradd -r -s /bin/false bpdmx

# Set ownership of the installation directory
sudo chown -R bpdmx:bpdmx /opt/bpdmx

3. Enable and Start the Service

# Reload systemd to pick up the new service
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable bpdmx

# Start the service now
sudo systemctl start bpdmx

# Check status
sudo systemctl status bpdmx

4. View Logs

# View recent logs
sudo journalctl -u bpdmx -n 50

# Follow logs in real-time
sudo journalctl -u bpdmx -f

5. Managing the Service

sudo systemctl start bpdmx    # Start
sudo systemctl stop bpdmx     # Stop
sudo systemctl restart bpdmx  # Restart
sudo systemctl status bpdmx   # Check status

🍎 macOS (launchd)

macOS uses launchd for managing services (called "launch agents" or "launch daemons").

1. Create the Launch Agent

Create ~/Library/LaunchAgents/com.bpshowtools.bpdmx.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.bpshowtools.bpdmx</string>
    
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/bpdmx</string>
        <string>serve</string>
        <string>--port</string>
        <string>8512</string>
    </array>
    
    <key>RunAtLoad</key>
    <true/>
    
    <key>KeepAlive</key>
    <true/>
    
    <key>WorkingDirectory</key>
    <string>/usr/local/bin</string>
    
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/bpdmx.log</string>
    
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/bpdmx.error.log</string>
</dict>
</plist>

💡 User vs System Service:

~/Library/LaunchAgents/ — Runs when you log in (user agent)
/Library/LaunchDaemons/ — Runs at boot, even without login (system daemon, requires sudo)

2. Load the Service

# Load and start the service
launchctl load ~/Library/LaunchAgents/com.bpshowtools.bpdmx.plist

# Verify it's running
launchctl list | grep bpdmx

3. Managing the Service

# Stop the service
launchctl unload ~/Library/LaunchAgents/com.bpshowtools.bpdmx.plist

# Start the service
launchctl load ~/Library/LaunchAgents/com.bpshowtools.bpdmx.plist

# View logs
tail -f /usr/local/var/log/bpdmx.log

🪟 Windows

Windows offers two approaches: Task Scheduler (simpler) or Windows Service (more robust).

Option A: Task Scheduler (Recommended for Most Users)

1. Open Task Scheduler

Press Win + R, type taskschd.msc, and press Enter.

2. Create a New Task

Click Create Task (not "Create Basic Task")
General tab:
- Name: BPDMX
- Check "Run whether user is logged on or not"
- Check "Run with highest privileges"
Triggers tab:
- Click New → "At startup"
Actions tab:
- Click New → Action: "Start a program"
- Program: C:\Program Files\BPDMX\bpdmx.exe
- Arguments: serve --port 8512
- Start in: C:\Program Files\BPDMX
Settings tab:
- Uncheck "Stop the task if it runs longer than"
- Check "If the task fails, restart every" → 1 minute
Click OK and enter your password when prompted

Option B: Windows Service (Using sc.exe)

Windows includes sc.exe (Service Control) for creating native Windows Services. This requires no third-party tools.

1. Install the Service

Open PowerShell as Administrator:

# Create the service
sc.exe create "BPDMX" binpath= "C:\Program Files\BPDMX\bpdmx.exe serve --port 8512" start= auto DisplayName= "BPDMX Server"

# Set description (optional)
sc.exe description "BPDMX" "BPDMX DMX server for sACN and Art-Net"

# Configure recovery options (restart on failure)
sc.exe failure "BPDMX" reset= 86400 actions= restart/60000/restart/60000/restart/60000

💡 Note: The spaces after = in sc.exe commands are required (e.g., binpath= "..." not binpath="...").

2. Managing the Service

sc.exe start BPDMX    # Start
sc.exe stop BPDMX     # Stop
sc.exe query BPDMX    # Check status
sc.exe delete BPDMX   # Remove service

You can also manage it via services.msc (Windows Services GUI).

Option C: Windows Service (Using WinSW)

WinSW is an actively maintained service wrapper with XML configuration and built-in logging.

1. Download WinSW

Download WinSW-x64.exe from GitHub Releases and place it in your BPDMX folder as bpdmx-service.exe.

2. Create Configuration File

Create bpdmx-service.xml in the same folder:

<service>
  <id>BPDMX</id>
  <name>BPDMX Server</name>
  <description>BPDMX DMX server for sACN and Art-Net</description>
  <executable>bpdmx.exe</executable>
  <arguments>serve --port 8512</arguments>
  <log mode="roll"/>
</service>

3. Install and Start

# Install the service
bpdmx-service.exe install

# Start the service
bpdmx-service.exe start

# Check status
bpdmx-service.exe status

🔧 Troubleshooting

Port Already in Use

If port 8512 is already in use, specify a different port:

bpdmx serve --port 8520

Permission Denied (Linux/macOS)

Ports below 1024 require root privileges. Use a higher port number, or set up a reverse proxy.

Service Won't Start

Check the logs for error messages
Verify the executable path is correct
Ensure the service user has read/execute permissions
Try running the command manually first to test

Network Interface Issues

If sACN or Art-Net traffic isn't being received:

Ensure the service user has access to network interfaces
Check firewall rules allow multicast traffic
Verify the correct network interface is configured