Skip to content
  • There are no suggestions because the search field is empty.

Humly Print Service - Installation and Configuration

Humly Print Service (HPS) enables automatic printing of visitor labels and badges when used with Humly Visitor screens. This guide covers installation and configuration on both Windows and Linux (Ubuntu/Debian) systems.

Table of Contents

Prerequisites

Before installing HPS, ensure you have:

  • Humly Control Panel version 1.16 or later
  • Operating System:
    • Windows: Server 2016, 2019, 2022, 2025, or Windows 10, 11
    • Linux: Ubuntu 20.04, 22.04, 24.04 OR Debian 10, 11
  • Network Access: Connectivity to your Humly Control Panel server
  • Authentication: HCP Global Settings authentication token (see Step 6)
  • Printer: Physical label printer or PDF printer for testing
  • Administrative Access: Administrator (Windows) or sudo privileges (Linux)

Important: HPS cannot be installed on the same server as Humly Control Panel. Use a dedicated machine or separate virtual server.

Certificate Requirement: For on-premises Control Panel deployments, HCP must have a signed SSL certificate installed.

Installation

Windows Installation

  1. Download the installer from the Humly Downloads portal

  2. Launch the installer and accept the license terms

  3. Click Install to begin the installation process
    Screenshot_2022-10-28_at_11.31.30.png

  4. Click Next when the Setup Wizard launches
    Screenshot_2022-10-28_at_11.33.51.png

  5. Select the destination folder where HPS will be installed (default is recommended)
    Screenshot_2022-10-28_at_11.37.46.png

  6. Configure the HCP server URL:
    Screenshot_2022-10-28_at_11.52.png

    • For Humly Cloud: https://<your-cloud-id>.humly.com
    • For on-premises HCP: https://<your-hcp-server>:3002

  7. Obtain your authentication token:

    • Log into Humly Control Panel
    • Navigate to Settings > Global Settings
    • Locate the Print Service Authentication Token section
    • Copy the token value
      Screenshot_2022-10-28_at_12.07.png

  8. Enter the authentication token in the Setup Wizard password field
    Screenshot_2022-10-28_at_12.24.png

  9. Click Next to proceed to the installation phase
    Screenshot_2022-10-28_at_12.28.25.png

  10. Wait for the installation to complete

  11. Click Finish to close the Setup Wizard
    Screenshot_2022-10-28_at_12.28.25.png

  12. Restart the HPS Service:

    • Open Windows Services (services.msc)
    • Locate Humly Print Service
    • Right-click and select Restart
      Screenshot_2022-11-24_at_20.34.38.png

  13. Verify the connection:

    • Open a web browser
    • Navigate to http://localhost:3100
    • Connection status should display "Connected"
      Screenshot_2022-10-28_at_13.06.png

  14. Identify your printer name:

    • On the HPS web interface, view the list of connected printers
    • Note the exact printer name (e.g., "Brother QL-820NWB")
      Screenshot_2022-10-28_at_13.26.16.png

  15. Configure your Humly Visitor Screen:

    • In HCP, navigate to your Visitor screen settings
    • Enter the printer name in the printer configuration field
    • Save the configuration
      Screenshot_2022-10-28_at_13.32.png

  16. Test the setup: Check in a visitor and verify that the label prints automatically

Ubuntu/Debian Installation

  1. Download the installation archive from the Humly Downloads portal

  2. Extract the archive:

    tar -xzf hps_installation_vX.X.X.X.tar.gz

  3. Navigate to the extracted folder:

    cd hps_installation_vX.X.X.X

  4. Run the installation script:

    sudo bash install.sh

  5. Configure HCP connection when prompted:

    • HCP Server URL: Enter your HCP server address
      • For Humly Cloud: https://<your-cloud-id>.humly.com
      • For on-premises HCP: https://<your-hcp-server>:3000

  6. Obtain your authentication token:

    • Log into Humly Control Panel
    • Navigate to Settings > Global Settings
    • Locate the Print Service Authentication Token section
    • Copy the token value

  7. Enter the authentication token when prompted by the installer

  8. Wait for installation to complete (this includes automatic installation of CUPS printer system and dependencies)

  9. Verify the connection:

    • Check service status: hps status
    • The service should show as running and connected to HCP

  10. Identify your printer name:

    • Access the CUPS web interface: http://localhost:631
    • View available printers and note the printer name
    • Alternatively, use: lpstat -p -d

  11. Configure your Humly Visitor Screen:

    • In HCP, navigate to your Visitor screen settings
    • Enter the printer name in the printer configuration field
    • Save the configuration

  12. Test the setup: Check in a visitor and verify that the label prints automatically

Ubuntu Silent Installation

For automated deployments, use the silent installation mode with command-line parameters:

sudo bash install.sh -s -u https://hcp.example.com:3002 --username defaultPrinterIntegrationUser --password <your-token>

Optional parameters:

  • -m, --memory_limit - Set application memory limit in MB (default: 1024)
  • -u, --server_url - HCP server URL
  • --username - HCP username (default: defaultPrinterIntegrationUser)
  • --password - HCP authentication token (can be found in HCP settings)

Managing the Service

Windows Service Management

Use Windows Services (services.msc) to manage HPS:

  • Start: Right-click Humly Print Service > Start
  • Stop: Right-click Humly Print Service > Stop
  • Restart: Right-click Humly Print Service > Restart
  • View Logs: Check Windows Event Viewer > Application logs

Ubuntu/Debian Service Management

Use the hps command to manage the service:

hps start      # Start the print service
hps stop       # Stop the print service
hps restart    # Restart the print service
hps status     # Show service status
hps tail       # View logs in real-time
hps clear      # Clear log files

Configuration file location: /home/<user>/Humly/PrintService/application_data/application.config.json

Log files location: /home/<user>/Humly/PrintService/application_data/logs/

Printer Setup

Windows Printer Configuration

  1. Install printer drivers according to your printer manufacturer's instructions

  2. Connect the printer:

    • Physical connection: USB or network connection
    • Add printer through Windows Settings > Devices > Printers & scanners

  3. Verify printer visibility:

    • Navigate to http://localhost:3100
    • Confirm the printer appears in the HPS web interface

  4. Test printing from Windows to ensure the printer works correctly

Ubuntu/Debian Printer Configuration

The installer automatically installs CUPS (Common UNIX Printing System) and a PDF printer (cups-pdf) for immediate testing.

PDF Printer:

  • Allows HPS to function without physical printers
  • PDF output location: /home/<user>/PDF/
  • Useful for testing visitor badge layouts

Adding Physical Printers:

  1. Using CUPS Web Interface:

    • Navigate to http://localhost:631
    • Go to Administration > Add Printer
    • Follow the wizard to add your printer
    • Note: You may need to log in with your system credentials

  2. Using Command Line:

    sudo lpadmin -p PrinterName -v usb://path/to/printer -E

  3. List available printers:

    lpstat -p -d

Note: The HPS service user is automatically added to the lpadmin group for printer management.

Troubleshooting

Connection Issues

Problem: HPS shows "Disconnected" status

Solutions:

  1. Verify HCP server URL is correct and accessible from the HPS server
  2. Check firewall settings: Ensure port 3002 (or your HCP port) is not blocked
  3. Validate authentication token: Token may have been regenerated in HCP
  4. Check certificate: For on-premises HCP, ensure SSL certificate is valid
  5. Review logs:
    • Windows: Event Viewer > Application logs
    • Linux: hps tail or tail -f /home/<user>/Humly/PrintService/application_data/logs/hps.out.log

Printing Issues

Problem: Labels are not printing automatically

Solutions:

  1. Verify printer name matches exactly in Visitor screen settings (case-sensitive)
  2. Check printer status: Ensure printer is online and ready
  3. Test printer directly: Print a test page from the operating system
  4. Restart HPS service:
    • Windows: Services > Humly Print Service > Restart
    • Linux: hps restart
  5. Check HPS connection: Verify HPS shows "Connected" status

Problem: Incorrect label format or cut-off text

Solutions:

  1. Verify printer model is supported (Brother QL series recommended)
  2. Check label size configuration in Visitor screen settings
  3. Update printer drivers to the latest version
  4. Adjust label template in HCP Visitor screen settings

Linux-Specific Issues

Problem: Permission denied errors

Solutions:

  1. Verify service user permissions: 
    sudo usermod -a -G lpadmin humlyHPSService
  2. Check file permissions: 
    ls -la /home/<user>/Humly/PrintService/
  3. Verify home directory permissions: 
    sudo chmod 755 /home/<user>

Problem: Service fails to start after reboot

Solutions:

  1. Check PM2 startup script: 
    hps status
  2. Reinstall startup script: 
    cd /home/<user>/Humly/PrintService
    sudo -u humlyHPSService pm2 startup
    sudo -u humlyHPSService pm2 save

Uninstallation

Windows Uninstallation

  1. Open Control Panel > Programs and Features
  2. Locate Humly Print Service
  3. Click Uninstall and follow the prompts

Ubuntu/Debian Uninstallation

Run the uninstallation script:

sudo bash /home/<user>/Humly/PrintService/dependencies/uninstall.sh

This removes:

  • HPS application files
  • Service user (humlyHPSService)
  • PM2 process manager configuration
  • Application configuration and logs

Note: CUPS and Node.js are not removed automatically as they may be used by other applications.

Related Documentation

Support

For additional assistance, contact Humly support:

Next...

Learn how to configure a Humly Visitor screen by following the How to Configure a Humly Visitor Screen.

Install and configure our recommended visitor badge printer Brother QL-820NWB by following
the How to Install &, Configure the Brother QL-820NWB Visitor Badge Printer guide.