Installation LabelServer4j

This page covers deploying LabelServer4j on a server or PC connected to the production network.

Requirements

Network access to each label printer (TCP/IP — Zebra port 9100, Logopak port 9100 or as configured)
Network access to the Commander4j server (to receive CSV request files)
Windows, Linux, or macOS
Java 21 — required only when running from the distribution archive; the native install package bundles its own Java runtime

Installation

Native install packages for Windows, macOS, and Linux are available from the Downloads page and are the preferred installation method. The installer creates the application directory, copies all configuration templates, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be extracted to a suitable directory, for example:

C:\Commander4j\LabelServer4j\          (Windows)
/opt/commander4j/labelserver4j/        (Linux)

The extracted directory contains:

LabelServer.jar
LabelServer.exe           (Windows — service launcher)
LabelServerDebug.exe      (Windows — console launcher for testing)
start_labeller.cmd        (Windows — fallback start script)
start_labeller.sh         (Linux/macOS — start script)
lib/
xml/config/
labeller_files/
labeller_requests/
labeller_cmd/
labeller_backups/
logs/

Configuration Before First Run

Before starting LabelServer4j, complete the following configuration steps.

1. Site and Labeller Definitions

Edit xml/config/config.xml to set the active site identifier. Then create or edit the labellers.xml file for that site in xml/config/. Each labeller entry defines:

The labeller name (must match the name used in Commander4j)
The printer IP address and TCP port
The path to the command script
The input directory where Commander4j writes CSV files

See LabelServer4j Configuration for the full XML structure.

2. Command Scripts

Place the command script files (plain text .txt files) for each labeller in the labeller_cmd/ directory. The script filename is referenced in labellers.xml.

3. Label Files (Logopak only)

If using Logopak printers with stored label templates, place the binary label files in the appropriate subdirectory of labeller_files/. LabelServer4j can upload these to the printer using the SEND_FILE_INTELHEX command.

4. Database Connection (Optional)

If the command scripts use DB_QUERY to enrich label data from the Commander4j database, configure the database connection in xml/config/config.xml with the JDBC URL, username, and AES-encrypted password.

5. Email Notifications (Optional)

To receive alerts on print failures or service events, configure xml/config/email.xml with SMTP server details and recipient addresses.

Installing as a Windows Service

The native install package includes LabelServer.exe, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper (such as WinSW) is required.

All service commands must be run from an elevated command prompt (Run as Administrator).

The default Windows service name is LabelService (the launcher name defined in the installer). You can specify a different name as an optional second parameter — useful if you need to run multiple instances on the same machine. If a custom name is used at install time, that same name must be passed to every subsequent command.

Command	Effect
`LabelServer.exe /install`	Register as LabelService with automatic startup on boot
`LabelServer.exe /install "My Label Service"`	Register with a custom service name
`LabelServer.exe /install-demand`	Register with manual startup only
`LabelServer.exe /start`	Start the service
`LabelServer.exe /stop`	Stop the service (waits for graceful shutdown)
`LabelServer.exe /restart`	Restart the service
`LabelServer.exe /status`	Query status (exit code: 0 = running, 3 = stopped)
`LabelServer.exe /uninstall`	Remove the service registration

If a custom service name was used at install time, append it to all subsequent commands:

LabelServer.exe /start "My Label Service"
LabelServer.exe /stop "My Label Service"
LabelServer.exe /uninstall "My Label Service"

Once installed, the service also appears in the Windows Services management console (services.msc) and can be started and stopped from there.

Testing Before Installing as a Service

Before committing to service installation, run LabelServer4j in a visible console window using the debug launcher:

LabelServerDebug.exe

This runs the same application code with all log output written to the console window. Use this mode to confirm that labellers connect to their printers and that the configuration is correct before installing as a service.

Starting on Linux / macOS

Use the provided shell script:

./start_labeller.sh

Or directly:

java -cp ./LabelServer.jar:./lib/devonly/i4jruntime.jar com.commander4j.labeller.Service

The process runs in the foreground. For production deployment, use a process manager (systemd, launchd, or nohup) to run it as a background service.

Verifying the Installation

After starting LabelServer4j:

Check logs/c4jLabelServer.log — there should be startup and thread initialisation messages.
Verify that each labeller thread reports a successful TCP connection to its printer.
Place a test CSV file in a labeller's input directory to trigger an end-to-end print cycle.
Confirm the CSV file is consumed (deleted on success, or moved to the error directory on failure).

Log Files

All activity is written to logs/c4jLabelServer.log. Log files rotate at 10 MB and are retained for 14 days.