View source for 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 <code>xml/config/config.xml</code> to set the active site identifier. Then create or edit the <code>labellers.xml</code> file for that site in <code>xml/config/</code>. 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 <code>.txt</code> files) for each labeller in the <code>labeller_cmd/</code> directory. The script filename is referenced in <code>labellers.xml</code>.

=== 3. Label Files (Logopak only) ===

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

=== 4. Database Connection (Optional) ===

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

=== 5. Email Notifications (Optional) ===

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

== Installing as a Windows Service ==

The native install package includes <code>LabelServer.exe</code>, 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.

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>LabelServer.exe /install</code> || Register as '''LabelService''' with automatic startup on boot
|-
| <code>LabelServer.exe /install "My Label Service"</code> || Register with a custom service name
|-
| <code>LabelServer.exe /install-demand</code> || Register with manual startup only
|-
| <code>LabelServer.exe /start</code> || Start the service
|-
| <code>LabelServer.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>LabelServer.exe /restart</code> || Restart the service
|-
| <code>LabelServer.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>LabelServer.exe /uninstall</code> || 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 (<code>services.msc</code>) 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 <code>logs/c4jLabelServer.log</code> — 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 <code>logs/c4jLabelServer.log</code>. Log files rotate at 10 MB and are retained for 14 days.

See also: [[Overview LabelServer4j]], [[LabelServer4j Operation]], [[LabelServer4j Configuration]], [[LabelServer4j Example User Interface]]

[[Category:LabelServer4j]]