Web Stack Migration to Virtual Appliance

Moving to the Virtual Appliance from Web Stack is both an upgrade and a migration. It’s an upgrade to a new on-prem version of PrinterLogic, but it is also a migration to a different platform. Web Stack runs on a Windows server and the Virtual Appliance comes as a pre-installed Virtual Appliance running on Ubuntu server utilizing Docker containers and microservices. The MySQL database gets migrated during the process, which includes the configuration, printer drivers and reporting data.

Prerequisites and Requirements

Minimum System Requirements

Depending on the configured features and user count, the minimum requirements for the Virtual Appliance may increase. Use the recommendations below when creating your Virtual Appliance, but continue to monitor the CPU and RAM utilization and allocate additional resources as needed.

  • Four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.
  • 16GB RAM for up to 15,000 users.
    • Add 2 CPUs / 8GB RAM for each additional 15,000 users.
    • Add a minimum of 2 CPUs and 4GB RAM if using the Internal Service Client.
    • Add 2 CPUs and 4GB RAM per 500 CPA/Simple Badge Release installations.
  • 80GB free hard disk space for the host disk.
  • There should be 50GB of free hard disk space on the persistent storage disk (add 4GB for every 100 printers).
  • There is a requirement for NTLMv2 to connect to the appliance-storage shared folder of the PrinterLogic Virtual Appliance.

Authorization codes are required on the Virtual Appliance. This will ensure communication and security between the client and Virtual Appliance.

Readiness Checklist

  1. Web Stack instance must be at version 19.1 Service Pack 3.
  2. MySQL must be version 8 or higher. Contact PrinterLogic support for instructions to upgrade MySQL.

    If an update needs to be made, as a best practice, make sure to make a backup of the printer_installer database before performing the MySQL update.

  3. MySQL configured to allow external access.
    1. Locate your root password. This is found in c:\inetpub\wwwroot\config\settings.php

    2. Open a MySQL command prompt from the Web Stack server and run the following query (all on one line):

      use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

      • On the server hosting Web Stack, open the Start Menu.
      • Select MySQL from the menu items.
      • Select the MySQL 8.0 Command Line Client option.
      Copy Code
      use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

    3. When you are prompted for a password, enter the root password obtained in step a.

  4. DNS configured properly.
    1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
    2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
    3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
  5. SSL certificates created and available.
    1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
  6. Verify if your current Web Stack instance is configured to use authorization codes and if the clients were installed with authorization codes. This will help determine the type of cut-over performed.
    1. Check the OAUTH_ENABLED and ALWAYS_GRANT_READ_INSTANCE_SCOPE in the C:\inetpub\wwwroot\.env file.
      1. If ALWAYS_GRANT_READ_INSTANCE_SCOPE=false and OAUTH_ENABLED=true, this indicates that Auth Codes are being used. You can then check to see if you have a non-expiring Auth Code by going to Tools > Authorized Devices in the Admin Console. If so, then Auth Codes won’t be an issue if a DNS cut-over is desired.
      2. If ALWAYS_GRANT_READ_INSTANCE_SCOPE=true and OAUTH_ENABLED=true, this indicates that Auth codes aren’t being used, but the handshake has been authorized. Therefore, a DNS cut-over can still be successful. If it is not, it would require a reinstallation of clients. A Client Cut-over is the recommended option in this case.
      3. If ALWAYS_GRANT_READ_INSTANCE_SCOPE=true and OAUTH_ENABLED=false, this indicates Auth Codes are not required and are not being used. A DNS cut-over would require a client to reinstall during the cut-over, which will be challenging to do if all workstations are not accessible during cut-over. A Client Cut-over is the recommended option in this case.
  7. Open ports for DB access from your machine:
    1. TCP 3306 - MySQL
    2. TCP 80 - HTTP
    3. TCP 443 - HTTPS
    4. TCP 8000 - Configuration API
    5. TCP 8080 - Configuration UI
    6. TCP 445 - SMB

Migration Stages

  1. Ensure the readiness checklist is complete.
  2. Decide on type of cut-over desired (DNS cut-over vs. Client cut-over). Note the requirements above for DNS cut-over.
  3. Deploy the Virtual Appliance using a supported hypervisor:
    1. Hyper-V
    2. Workstation Pro
    3. ESXi
    4. Google Cloud Platform
    5. New Install: Virtual Machine Manager

    (Hypervisor deployment steps are also included in Step 6 of each cutover option below)

  4. Perform the migration from Web Stack to the newly configured Virtual Appliance.
    1. DNS Cut-over
    2. Client Cut-over

Option 1 – Client Cut-over

With this method, you will end up with a different FQDN than the current prod environment. It also requires a re-install of the client, which gets it re-homed and updated. The advantage of this method is that you can do more testing of the Virtual Appliance environment and you don’t have the downtime of a single all-at-once cut-over. Another advantage is you don’t have to create two sets of license files, DNS records and cert files.

A potential downside of this method is you have to re-install all the clients to achieve the cut-over and you have to choose a different FQDN.

Client Cut-over Steps

This example will use printers.company.org as the production FQDN running on Web Stack. The Web Stack server’s host name is server1.company.org and is also listed in the license file. The FQDN for the Virtual Appliance will be printers2.company.org. After the cut-over, the production FQDN will be printers2.company.org.

  1. If Web Stack is not running on version 19.1 SP3, perform an upgrade to 19.1 SP3.
  2. If the version of MySQL is 5.5, upgrade MySQL to version 8 or higher.
    • Contact PrinterLogic support for instructions to upgrade MySQL at support@printerlogic.com.
  3. Create a DNS A record for the FQDN of the Virtual Appliance (printers2.company.org) and a wildcard CNAME record for the wildcard underneath the FQDN of the Virtual Appliance (*.printers2.company.org) which points to the FQDN of the Virtual Appliance (printers2.company.org).
  4. [Optional] If you plan on using any features that require HTTPS, create both:
    • A SAN certificate (following the Virtual Appliance SSL Certificates) for the FQDN of the Virtual Appliance (printers2.company.org)
    • And the wildcard underneath the FQDN of the Virtual Appliance (*.printers2.company.org),
  5. Download the latest Virtual Appliance image. Release Notes 2024.
    • Links are also included in the drop-downs below.
  6. Deploy the image to your hypervisor.

    • Prerequisites

      1. Download the Virtual Appliance ova file.
      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB

      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Configure Virtual Machine

      1. Connect to your ESXi web management interface.

        ESXI web management interface login screen.

      2. From the Virtual Machines object, choose the action Create/Register VM.

        Create/Register VM button highlighted in the upper left of the ESXI management interface.

      3. Choose Deploy a virtual machine from an OVF or OVA file, and click Next.

        New virtual machine ESXi wizard, showing the Deploy a virtual machine from an OVF or OVA file options and the Next button highlighted in the lower right.

      4. Enter the name for the VM and then Click to select files, and select the OVA file you downloaded earlier.

        New Virtual Machine window showing the fields to enter the virtual machine name and upload the OVA file in ESXi highlighted.

      5. With the OVA file selected, click Next, and allow time for the OVA file to be extracted.

        ESXi wizard's Next button in the lower right that starts the OVA file extraction.

      6. Select the storage to be used for the VM and click Next.

        ESXi wizard where you select the storage option for the virtual machine, and the Next button in the lower right is highlighted.

      7. Select the Network mapping for the VM, select whether you want Thin or Thick Disk provisioning, and un-check the Power on automatically option so you can configure other settings prior to powering on. Click on Next.

        Esxi wizard showing the network mappings drop-down, disk provisioning options, and power on automatically option.

      8. Review your settings summary and then click Finish. Wait for upload to complete.

        ESXi wizard summary settings with the Finish button highlighted in the lower right. ESXi console with the Tasks section highlighted, showing the virtual machine being created.

      9. Select the newly created VM and then click Edit.

        ESXi interface with after the virtual machine is created, with the Edit button in the upper right highlilghted.

      10. Increase the memory to 16 GB minimum.

        PrinterLogic recommends 16GB RAM for up to 15,000 users (add 8GB for every additional 15,000 users)

        ESXi virtual hardware pop-up with the Memory section highlighted where minimum size can be adjusted.

      11. Click Add hard disk, then select New standard hard disk.

        ESXi virtual machine Edit settings with Add hard disk and New standard hard disk options highlighted.

      12. Select the new hard disk and adjust to the recommended minimum size of 50 GB.

        ESXi virtual hardware pop-up with the Memory section highlighted where minimum size can be adjusted.

        PrinterLogic recommends a minimum of 50 GB free persistent hard disk space (add 4 GB for every 100 printers).

      1. Click the drop-down arrow next to the New Hard Disk and adjust the location, Disk Provisioning and other settings as needed. Click on Save.

        ESXi edit settings pop-up with the disk provisioning options displayed in the middle.

      2. Power on the VM and open a console to it.

        ESXi interface with the Power On button highlighted in the upper middle.

      3. Click on Console.

        ESXi interface with the Console, and Open browser console options highlighted in the upper right.

      4. After VM starts, document the displayed IP address given.

      5. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings or make adjustments to IP address ranges.

        Virtual machine browser console window displays with the virtual appliance version, IP address to visit, and nertwork login settings.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Download the latest Virtual Appliance vhd.xz file.
      2. After downloading the vhd.xz file, you will need to extract the VHD from the vhd.xz file. The extracted VHD file should then be placed in your Hyper-V server folder.
      3. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      4. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      5. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      6. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Configure Virtual Machine

      1. Open up your Hyper-V Manager Console.

        HyperV Manager Console showing the main interface and settings.

      2. Right click on your server, hover your pointer over New, then click on Virtual Machine.

        New Virtual Machine setting seen after right-clicking the server icon in the interface.

      3. Click on Next.

        New virtual machine wizard pop-up with the Next button highlighted.

      4. Specify the new Virtual Machines Name, then click Next.

        VM Wizard with an arrow pointing to the virtual machine name and the Next button is highlighted in the bottom middle.

      5. Select Generation 1 and click Next.

        Virtual machine wizard with an arrow pointing to the Generation 1 option near the top.

      6. Change the memory to 16000 MB and click Next.

        PrinterLogic recommends 16GB RAM for up to 15,000 users (add 4GB for every additional 15,000 users)

        VM wizard showing the Assign Memory tab with an arrow pointing to the Startup memory box adjusted for more RAM.

      7. Select the Virtual Switch you have configured in Hyper-V and click Next.

        VM Wizard showing the Connection drop-down with New Virtual Switch highlighted.

      8. Select the option to Use an existing virtual hard disk, and browse to the downloaded PrinterLogic VHD file. Select the file, and click on Next.

        VM Wizard with an arrow pointing to the Use an existing virtual hard disk option and field to browse for the location path.

      9. Click Finish at the bottom of the summary screen.

        VM Wizard summary page with the Finish button showing in the bottom right.

      10. In the Actions pane to the right, under the virtual machine you just created, click on Settings.

        Actions tab on the right of the VM interface with an arrow pointing to the Settings option in the New Virtual Machine section.

      11. With Add Hardware selected in the left pane and SCSI Controller selected in the right pick list, click on Add.

        Settings pop-up showing the Add Hardware option selected and an arrow pointing to the SCSI Controller option with the Add button to its lower right.

      12. Select Hard Drive, and click Add.

        SCSI Controller tab with Hard Drive option selected and the Add button showing to the lower right.

      13. Select New.

        Hard Drive section with an arrow pointing to the New button to start the hard disk wizard.

      14. Click Next.

      15. Keep the default VHDX selected and click on Next.

        New Hard disk wizard with the VHDX option selected.

      16. Select the appropriate disk type for your environment and click Next.

        Disk type options including Fixed Size, Dynamically expanding, and Differencing.

      17. Name the disk, and click Next.

        Wizard tab where you specify to name of the hard disk and the location of the file.

      18. Select the new hard disk and adjust to the recommended minimum size of 50 GB and click Next.

        PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

        Wizard showing the configure disk section and an arrow to the Size field to specify the size of the virtual hard disk.

      19. Review the summary page and then click Finish.

        Hard disk wizard showing the Finish button on the Summary tab.

      20. After the wizard finishes building you will be returned to the Settings dialog.

      21. Select Processor from the left pane and increase to a minimum of 4 processors.

        PrinterLogic recommends four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.

        Settings tab with Processor selected, and processor count changed to four.

      22. Click on OK.

      23. In the VM's action pane click on Start.

        HyperV main interface with an arrow pointing to the Start button in the Actions menu to the lower right.

      24. After the VM starts, open the VM screen and annotate the provided IP address.

      25. Log in using the displayed login and password to configure the network settings. This allows you to configure a static IP, default gateway, search domain, subnet IP address ranges, and the DNS servers.

        VA Web Console showing the URL to continue setup, and the network settings credentials.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Download the Virtual Appliance ova file.
      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Configure Virtual Machine

      Virtual Appliance should be able to work on any supported version of VM Workstation Pro, but it has been successfully tested on versions 12 and 15.

      1. Open VMWare Workstation Pro.

      2. Click Open a Virtual Machine.

        Open a Virtual Machine button as seen in the VMware Workstation Pro interface.

      3. Navigate to the .ova file you downloaded.

        File explorer view after navigating to the OVA file to upload.

      4. Click Open.

      5. Click Edit virtual machine settings.

        An arrow pointing to the Edit virtual machine settings option in the upper left of the VMware interface.

      6. Click Network Adapter.

        VM settings pop-up with the Hardware tab selected, and the Network Adapter option highlighted.

      7. Select Bridged: Connected directly to the physical network (if it is not already selected).

        An arrow pointing to the Bridged: Connected directly to the physical network option in the Network Adapter tab in the VM settings.

      8. Click Add.

        VM settings pop-up with an arrow pointing to the Add button in the lower middle.

      9. Select Hard Disk and click Next.

        Add Harware wizard pop-up with the Hard Disk option and selected and the Next button highlighted.

      10. Keep SCSI selected and click Next.

        Add Harware wizard with the SCSI option selected.

      11. Keep Create a new virtual disk selected and click Next.

        Add hardware wizard with the Create a new virtual disk setting checked.

      12. Adjust the disk size to the minimum recommended setting of 50 GB and click Next.

        PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

        Add harware wizard on the Specify Disk Capacity step where the maximum disk size is edited.

      13. Click Finish.

        Add hardware wizard final step with the path to the disk file and Finish button.

      14. Click OK.

      15. Click Power on this virtual machine.

        VMware VM main interface with the new VM selected, and the Power on this machine option highlighted in the upper left.

      16. When the virtual machine loads, you will see the following message.

        Web console view of the IP address to continue setup, and the network settings login credentials for the VM.

      17. The IP address will be specific to your PrinterLogic Virtual Appliance. You will want to note it for a following step.

      18. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings..

        Web console image with the IP address and network settings credentials highlighted.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Download the Virtual Appliance vmdk file.
      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Initial Configuration

      1. Log into Google Cloud Platform.

      2. Select Storage from the menu on the left.

        Google Cloud platform interface with an arrow pointing to the Storage option in the left-side menu.

      3. Either create a new storage bucket or select an existing storage bucket.

        Storage browser interface with an arrow pointing to the Create Bucket option at the top, and also showing exisiting storage buckets.

      4. After creating or selecting a storage bucket, select Upload Files.

        Bucket Details tab with an arrow pointing to the Upload files button in the middle.

      5. Upload the Virtual Machine Disk file (.vmdk) that was downloaded in the prerequisites.

        It is recommended that this step be done from a PC with an internet connection that supports high upload speeds due to the large file size.

      Convert the VMDK

      This process can take up to 40mn.

      1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        Google cloud platform home screen with an arrow pointing to the Compute Engine option on the left of the screen.

      2. From the new menu displayed on the left, select Images.

        Compute engine menu displayed with an arrow pointing to the Images option on the left .

      3. From the top menu, select Create Image.

        An arrow pointing to the Create Image button at the top of the screen after selecting the Images option.

      4. On the Create Image screen:
        1. Give it a name.
        2. Select Virtual disk (VMDK, VHD) as the source to be used.
        3. Select the Cloud Storage File
        4. In the Operating system on virtual disk section, Select Ubuntu 18.04 Bionic.
        5. Ensure that the Install guest packages box is checked.

        6. Click on Create.

          Create an image wizard with the name, source, cloud storage file path, Operating system on Virtual Disk option, and Install gues packages option highlighted.

      Configure the Image

      1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        Google cloud platform home screen with an arrow pointing to the Compute Engine option on the left of the screen.

      2. From the new menu displayed on the left, select Images.

        Compute engine menu displayed with an arrow pointing to the Images option on the left .

      3. Click on the newly created image name, then select Create Instance at the top.

        Images window with the new image selected in the middle of the screen and an arrow pointing to the Create Instance button in the upper right.

      4. Give the instance a name, select appropriate Region and Zone, and select the Machine Type that meets the recommended system requirements of:

        2. Four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.
        3. 16GB RAM for up to 15,000 users.
          • Add 2 CPUs / 8GB RAM for each additional 15,000 users.
          • Add a minimum of 2 CPUs and 4GB RAM if using the Internal Service Client.
          • Add 2 CPUs and 4GB RAM per 500 CPA/Simple Badge Release installations.
        4. 80GB free hard disk space for the host disk.
        5. There should be 50GB of free hard disk space on the persistent storage disk (add 4GB for every 100 printers).

        Create an Instance wizard with name, region, and machine type options highlighted.

        Port 8080, 8000, 3306 and 443 must be open to complete the setup phase.

      5. Scroll down to the Firewall section and select the appropriate settings to allow your workstation to communicate with the Virtual Appliance.

        Create an Instance wizard with an arrow pointing to the Firewal section, showing the Allow Http and Allow Https traffic options selected.

      6. Select Disks, and then scroll down and select the Add new disk button.

        Disks section with an arrow pointing to the Add New Disk button.

      7. Give the new disk a name and set a size (50 GB is recommended).

        New disk section of the Create an Instance wizard with an arrow pointing to the Size field near the bottom.

      8. Scroll down and select Done on the bottom left.

      9. Click Create on the bottom left.

        Create Wizard with arrows pointing to the Done and Create options at the bottom.

      10. Start the newly created VM instance.

      11. Locate the IP of the newly created virtual machine and copy it.

        VMware VM Instances screen with the newly created machine showing, and the area to copy its IP address highlighted.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Contact your PrinterLogic sales representative to provide you with access to the Virtual Appliance AMI.

        Only a PrinterLogic representative can provide the Virtual Appliance AMI. It is not available as a Public AMI.

      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Setup

      AWS is a supported platform to run the PrinterLogic Virtual Appliance. Currently, a PrinterLogic sales representative will need to assist you with getting access to the AMI.

      Please be prepared to provide the PrinterLogic sales representative with your AWS Account number so they can share the most current AMI to your account. You can find your account number in your AWS console by clicking on the drop-down next to your login name.

      My Account option to find your AWS account number, as seen in the AWS console.

      Copy the AMI

      1. In your AWS EC2 Dashboard, in the Images drop-down, select AMIs.

        AMI option within the Images drop-down in the AWS EC2 Dashboard.

      2. Set your AWS region to the region provided by your PrinterLogic representative.

        US East (Ohio) option in the AWS region menu options.

      3. On the AMI list screen, select Private Images.

        Private images option displayed in the AWS images sort drop-down.

      4. Locate the AMI that was provided to you in the list.
      5. Right click the image and select Copy AMI.

      6. On the Copy AMI screen, select your Destination Region and click Copy AMI.

        The copy process can take several minutes to complete.

      7. Back on the AMI screen, select the region you copied the AMI to.

      8. Locate the AMI you just copied from the list.

        The copied AMI will display a different AMI ID now that it is in your region. However, the AMI name will stay the same.

      9. Rename or tag the AMI as needed for your use.

      Launch the AMI

      1. Right click on the AMI and select Launch Instance from AMI.
      2. Provide the Virtual Appliance instance a name.
      3. Scroll down and select the Instance type ensuring you are meeting the Web Stack Migration to Virtual Appliance.
      4. Scroll down and select the Key Pair (login) you want to use.
      5. Scroll down to the Network settings section and select the VPC you want the instance installed in.
      6. Select the Subnet you want the instance deployed to.

      The steps to launch the instance from AMI, selecting the key pair for logins, and setting the VPC and subnet for deployment.

      1. In the Firewall (security groups) section, select your Existing security group if you have configured a Virtual Appliance in the past. If this is your first deployment in AWS, it will be necessary to create a security group following the steps in the drop-down option below:

        1. In the Firewall (security group) section, select Create Security Group.
        2. Enter a Security Group Name.
        3. Enter a Description for the security group.

        4. Enter the following security group rules:

          Security Group Rules
          TypeProtocolPortSource

          MySQL/Aurora

          		TCP3306Anywhere
          HTTPTCP80Anywhere
          HTTPSTCP443Anywhere
          Custom TCPTCP8000Anywhere
          Custom TCPTCP8080Anywhere
          SMBTCP445Anywhere
          Custom ICMP - IPv4Echo Request 8Anywhere
      2. The Advance Network Configuration section is optional for the following scenario:
        1. If a Static IP address for the Virtual Appliance is desired:
          1. Create a Network Interface and assign it the desired IP address.
          2. Attach that network interface in these settings.
        2. If DHCP will be used, nothing needs to be done with these settings.

      3. Scroll down to the Configure Storage section and ensure there's a minimum of 80 GB. We also suggest that an SSD (gp3) gets used to offer the ability to specify IOPS for the volume.

        Do not add the additional data volume at this time. You will add that in a later step..

      4. Scroll down to the Advanced Details section and expand it.

      5. Scroll to the bottom and paste the following code into the User Data field.

        Set the DOCKER_NETWORK IP address to the desired private TCP/IP network with a /20 or lower.

        Copy Code
        #!/bin/bash -x
        DOCKER_NETWORK="172.16.0.0/16"
        echo "*** cloud-init script begin ***"
        # Wait for Docker to become available
        until systemctl is-active docker >/dev/null 2>&1
        do
          echo "Waiting for Docker to become available..."
          sleep 5
        done
        echo "Setting Docker network to $DOCKER_NETWORK..."
        set-network "$DOCKER_NETWORK"
        echo "*** cloud-init script end ***"
      6. Select Launch Instance.
      7. Select View All Instances.
      8. Wait for the Virtual Appliance instance to completely launch.

      Attach Data Volume

      1. Select Volumes under the Elastic Block Store section of the menu.

        Instances window with an arrow pointing to the Volumes option in the AWS Elastic Block Store left-side menu section.

      2. Click on Create Volume.
      3. Select the Volume Type. It is suggested that an SSD (gp3) be used to give the ability to specify IOPS for the volume.

      4. Select the Volume Size.

        PrinterLogic recommends a minimum of 50 GB of free persistent hard disk space (add 4 GB for every 100 additional printers).

      5. Select the Availability Zone, ensuring it is in the same zone as your Virtual Appliance instance.

        Create Volume window with the Availability zone drop-down highlighted in the middle.

      6. (Optional) Select the Encryption checkbox and your desired master key if you want drive encryption.

      7. Click on Click to add a Name tag, and give your volume a name.

        Create Volume window with an arrow pointing to the Click to add a Name Tag link in the lower middle.

      8. Click on Create Volume.
      9. The Volume Created Successfully message will display, click on Close to return to your list of volumes.

      10. Locate the newly created volume, right-click on it, and select Attach Volume.

        Created volume window in AWS, with the right-click menu expanded to display the Attach Volume option.

      11. In the instance field, select the Virtual Appliance you just created.

      12. In the Device field, enter /dev/sdp.

        Attach Volume pop-up with the Device field highlighted and showing the /dev/sdp value.

      13. Click on Attach.
      14. Return to your Virtual Appliance instance by clicking on Instances.
      15. Locate and select your Virtual Appliance instance.

      16. Copy the IP Address of your Virtual Appliance.

        Instance details tab with the Private IPV4 addresses highlighted in the upper right.

  7. If not already started, start the Virtual Appliance.
  8. For VM Workstation Pro, HyperV, and ESXi hypervisors ONLY. (For AWS and Google Cloud Platform skip to Step 9.)
    • Launch the remote VM console of your hypervisor and login to the Virtual Appliance Console with the network user credentials specified. Configure TCP/IP settings as applicable (use either manual settings or DHCP reservation).
    • The Virtual Appliance starts as a DHCP client. It’s possible to leave it that way and configure the TCP/IP settings via DHCP Reservation. Otherwise, use the steps below to configure a static IP and to optionally change the private IP range that the Virtual Appliance uses by default so that it doesn’t conflict with existing subnets in the environment.
      1. In the hypervisor where the Virtual Appliance runs, open the web console to access the Virtual Appliance Linux terminal interface.
      2. Login with the credentials supplied in the terminal banner for the network user.

        VA web console showing basic settings with the network settings credentials highlighted.

      3. Enter "Y" to change the network settings.
      4. Enter "Y" to change the network mode.

      5. Enter the TCP/IP settings.

        The image below is just an example. Ensure you use the settings specific to your network.

        VA web console, after logging in with network settings credentials, with the adjustable network settings all displayed and highlighted.

      6. If the existing address pool does not conflict with any subnets in the environment, enter “N”. Otherwise, enter “Y” to set a different address range.

        VA web console, Would you like to change the unassigned address pool for your network setting highlighted.

        If needing to adjust IP addresses, be sure to read and understand the network range options you are presented with. Any range used must have a netmask < 20.

        VA web console, with the network range IP requirements highlighted.

      7. If needing to adjust the IP address ranges, configure the address range.

        The image below is just an example. Ensure you use the settings specific to your network.

        VA web console, example highlighted of the unassigned CIDR range.

      8. Press any key to exit.

  9. Run the Virtual Appliance Configuration UI by navigating to http://VA_IP_Address:8080 .

    VA configuration wizard with the orange Lets do this button in the lower middle.

  10. On the Configure Storage page, select VM-Attached Virtual Disk for the Storage Type and click Format Attached Storage.

    Configure Storage tab of wizard displaying the Storage Type drop-down and the Format Attached Storage button.

  11. Choose the Upgrade my Current Instance option.

    VA wizard interface with and arrow pointing to the Upgrade my Current Instance button.

  12. On the Migrate Database page, enter the FQDN of the production Web Stack instance (printers.company.org) in the Host field.

    Migrate Database window showing the field for Host highlighted in the middle.

  13. Enter in your Username and Password.

    Migrate Database tab with the Username and Password fields highlighted.

  14. Enter the APP_KEY from your Web Stack instance.

    1. Browse to your Web Stack .ENV file.
      1. Default path is: C:\intetpub\wwwroot\.env

    2. Open the file with a text editor and locate the APP_KEY and copy it.

      .env file for reference with the App_Key highlighted.

    Migrate database tab with the field for the App Key highlighted.

    15. By default, the Web Stack MySQL instance is configured to only allow local connections. If the MySQL Connection Test fails on this step, this restriction can be lifted so that the Virtual Appliance Migration can access the production MySQL database.

    Run the following command at a MySQL Command Prompt on the production Web Stack server (the MySQL root password can be found inside the c:\inetpub\wwwroot\config\settings.php file on the production Web Stack instance):

    use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

    Copy Code 
    use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

    To revert this setting, run the following command at a MySQL Command Prompt on the production Web Stack server:

    use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

    Copy Code 
    use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

  15. On the General Settings page, enter the FQDN of the Virtual Appliance (printers2.company.org) in the Domain Name field. Keep the suggested Shared Storage Password or set it to something else, and click Continue. Ensure you document the password!

    Va wizard General Settings tab with the Domain Name and Shared Storage Password highlighted.

  16. Request that your PrinterLogic representative give you your Virtual Appliance license that will match your Web Stack license capabilities, except use the new FQDN of the Virtual Appliance (printers2.company.org).

    General Settings tab with the License file field and Upload button highlighted.

  17. [Optional] If you created a SSL certificate for the Virtual Appliance, upload the certificate and key here, and click Continue.

    General Settings tab with the SSL Certificate, SSL Key, and their related Upload buttons highlighted.

  18. Select Continue on the Setup Database page.

  19. Click the final Finish Upgrade button and wait for it to complete.

    VA Wizard, Let's Migrate your WebStack database tab with an arrow pointing to the Start Migration button.

    A large database could take a couple hours to complete.

  20. Perform any testing with clients that are re-homed to printers2.company.org.

  21. After successful testing, setup the uninstall/reinstall script and start pushing it out.

    1. To uninstall/reinstall the client follow these steps:
      1. In Apps and Features, uninstall the Printer Installer Client.
      2. Delete the following directory on the workstation: C:\Program Files (X86)\Printer Properties Pro
      3. Install new client with new URL and Auth Code.

    Further information on Installing and Uninstalling the Client can be found in the PrinterLogic Client section.

  22. New clients will start pointing to the Virtual Appliance and old clients will continue to point to Web Stack until they are updated.
  23. After all the clients are converted, have your PrinterLogic representative update the prod license file to reflect the new single URL .
  24. Copy the license file to the /pi/storage folder on the shared drive.

Option 2 – DNS Cut-over

This method eliminates the need to re-install the clients during cut-over. However, you will still want to update the clients after migration, since the latest client provided by Web Stack does not support every new feature in the Virtual Appliance. The clients can be updated after the migration using the auto-update settings in the Admin Console.

You will use a different (temporary) FQDN during the migration so that you can access both the Virtual Appliance and the Web Stack server while testing. This will require a temporary DNS A/CNAME record and license file as well. When you are ready to cut-over, shut down Web Stack, change the FQDN of the Virtual Appliance, the DNS A/CNAME records, and the license file to the production FQDN. The next time the clients check in, they will be accessing the Virtual Appliance instead of Web Stack.

A potential downside of this method is that you can’t test the Virtual Appliance with the production FQDN prior to cut-over (unless you are able to change DNS temporarily during off-hours). Because the Virtual Appliance leverages DNS to communicate with the individual microservices internally, it's not possible to simply change the hosts file on a workstation to test connectivity to the Virtual Appliance using a different IP for the FQDN. The Virtual Appliance will still be pointing to the company's DNS servers, which will not include these temporary DNS settings -- the production FQDN will still resolve to the Web Stack instance, and the Virtual Appliance microservices will fail on name resolution. The FQDN of the Virtual Appliance must be changed in the secrets.env file at the same time DNS is changed.

When editing the secrets.env file, an editor like Notepad ++, Sublime Text, or Visual Studio Code must be used to ensure the file uses Unix line endings (LF only) and is saved in UTF-8 format with no byte-order mark.

DNS Cut-over Steps

This example will use printers.company.org as the production FQDN running on Web Stack. The Web Stack server’s host name is server1.company.org and is also listed in the license file. The temporary FQDN for the Virtual Appliance will be va.company.org. After the cut-over, the Virtual Appliance will be using printers.company.org.

  1. If Web Stack is not running on version 19.1 SP3, perform an upgrade to 19.1 SP3.
  2. If the version of MySQL is 5.5, upgrade MySQL to version 8 or higher.
    • Contact PrinterLogic support for instructions to upgrade MySQL at support@printerlogic.com.
  3. Create a DNS A record for the temporary FQDN of the Virtual Appliance (va.company.org) and a wildcard CNAME record for the wildcard underneath the temporary FQDN of the Virtual Appliance (*.va.company.org) which points to the temporary FQDN of the Virtual Appliance (va.company.org).
  4. [Optional] If you plan on using any features that require HTTPS, create both:
    • A temporary SAN certificate (following the Virtual Appliance SSL Certificates) for the temporary FQDN of the Virtual Appliance (va.company.org).
    • And the wildcard underneath the temporary FQDN of the Virtual Appliance (*.va.company.org).
  5. Download the latest Virtual Appliance image. Release Notes 2024.
    • Links are also included in the drop-downs below.
  6. Deploy the image to your hypervisor.

    • Prerequisites

      1. Download the Virtual Appliance ova file.
      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB

      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Configure Virtual Machine

      1. Connect to your ESXi web management interface.

        ESXI web management interface login screen.

      2. From the Virtual Machines object, choose the action Create/Register VM.

        Create/Register VM button highlighted in the upper left of the ESXI management interface.

      3. Choose Deploy a virtual machine from an OVF or OVA file, and click Next.

        New virtual machine ESXi wizard, showing the Deploy a virtual machine from an OVF or OVA file options and the Next button highlighted in the lower right.

      4. Enter the name for the VM and then Click to select files, and select the OVA file you downloaded earlier.

        New Virtual Machine window showing the fields to enter the virtual machine name and upload the OVA file in ESXi highlighted.

      5. With the OVA file selected, click Next, and allow time for the OVA file to be extracted.

        ESXi wizard's Next button in the lower right that starts the OVA file extraction.

      6. Select the storage to be used for the VM and click Next.

        ESXi wizard where you select the storage option for the virtual machine, and the Next button in the lower right is highlighted.

      7. Select the Network mapping for the VM, select whether you want Thin or Thick Disk provisioning, and un-check the Power on automatically option so you can configure other settings prior to powering on. Click on Next.

        Esxi wizard showing the network mappings drop-down, disk provisioning options, and power on automatically option.

      8. Review your settings summary and then click Finish. Wait for upload to complete.

        ESXi wizard summary settings with the Finish button highlighted in the lower right. ESXi console with the Tasks section highlighted, showing the virtual machine being created.

      9. Select the newly created VM and then click Edit.

        ESXi interface with after the virtual machine is created, with the Edit button in the upper right highlilghted.

      10. Increase the memory to 16 GB minimum.

        PrinterLogic recommends 16GB RAM for up to 15,000 users (add 8GB for every additional 15,000 users)

        ESXi virtual hardware pop-up with the Memory section highlighted where minimum size can be adjusted.

      11. Click Add hard disk, then select New standard hard disk.

        ESXi virtual machine Edit settings with Add hard disk and New standard hard disk options highlighted.

      12. Select the new hard disk and adjust to the recommended minimum size of 50 GB.

        ESXi virtual hardware pop-up with the Memory section highlighted where minimum size can be adjusted.

        PrinterLogic recommends a minimum of 50 GB free persistent hard disk space (add 4 GB for every 100 printers).

      1. Click the drop-down arrow next to the New Hard Disk and adjust the location, Disk Provisioning and other settings as needed. Click on Save.

        ESXi edit settings pop-up with the disk provisioning options displayed in the middle.

      2. Power on the VM and open a console to it.

        ESXi interface with the Power On button highlighted in the upper middle.

      3. Click on Console.

        ESXi interface with the Console, and Open browser console options highlighted in the upper right.

      4. After VM starts, document the displayed IP address given.

      5. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings or make adjustments to IP address ranges.

        Virtual machine browser console window displays with the virtual appliance version, IP address to visit, and nertwork login settings.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Download the latest Virtual Appliance vhd.xz file.
      2. After downloading the vhd.xz file, you will need to extract the VHD from the vhd.xz file. The extracted VHD file should then be placed in your Hyper-V server folder.
      3. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      4. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      5. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      6. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Configure Virtual Machine

      1. Open up your Hyper-V Manager Console.

        HyperV Manager Console showing the main interface and settings.

      2. Right click on your server, hover your pointer over New, then click on Virtual Machine.

        New Virtual Machine setting seen after right-clicking the server icon in the interface.

      3. Click on Next.

        New virtual machine wizard pop-up with the Next button highlighted.

      4. Specify the new Virtual Machines Name, then click Next.

        VM Wizard with an arrow pointing to the virtual machine name and the Next button is highlighted in the bottom middle.

      5. Select Generation 1 and click Next.

        Virtual machine wizard with an arrow pointing to the Generation 1 option near the top.

      6. Change the memory to 16000 MB and click Next.

        PrinterLogic recommends 16GB RAM for up to 15,000 users (add 4GB for every additional 15,000 users)

        VM wizard showing the Assign Memory tab with an arrow pointing to the Startup memory box adjusted for more RAM.

      7. Select the Virtual Switch you have configured in Hyper-V and click Next.

        VM Wizard showing the Connection drop-down with New Virtual Switch highlighted.

      8. Select the option to Use an existing virtual hard disk, and browse to the downloaded PrinterLogic VHD file. Select the file, and click on Next.

        VM Wizard with an arrow pointing to the Use an existing virtual hard disk option and field to browse for the location path.

      9. Click Finish at the bottom of the summary screen.

        VM Wizard summary page with the Finish button showing in the bottom right.

      10. In the Actions pane to the right, under the virtual machine you just created, click on Settings.

        Actions tab on the right of the VM interface with an arrow pointing to the Settings option in the New Virtual Machine section.

      11. With Add Hardware selected in the left pane and SCSI Controller selected in the right pick list, click on Add.

        Settings pop-up showing the Add Hardware option selected and an arrow pointing to the SCSI Controller option with the Add button to its lower right.

      12. Select Hard Drive, and click Add.

        SCSI Controller tab with Hard Drive option selected and the Add button showing to the lower right.

      13. Select New.

        Hard Drive section with an arrow pointing to the New button to start the hard disk wizard.

      14. Click Next.

      15. Keep the default VHDX selected and click on Next.

        New Hard disk wizard with the VHDX option selected.

      16. Select the appropriate disk type for your environment and click Next.

        Disk type options including Fixed Size, Dynamically expanding, and Differencing.

      17. Name the disk, and click Next.

        Wizard tab where you specify to name of the hard disk and the location of the file.

      18. Select the new hard disk and adjust to the recommended minimum size of 50 GB and click Next.

        PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

        Wizard showing the configure disk section and an arrow to the Size field to specify the size of the virtual hard disk.

      19. Review the summary page and then click Finish.

        Hard disk wizard showing the Finish button on the Summary tab.

      20. After the wizard finishes building you will be returned to the Settings dialog.

      21. Select Processor from the left pane and increase to a minimum of 4 processors.

        PrinterLogic recommends four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.

        Settings tab with Processor selected, and processor count changed to four.

      22. Click on OK.

      23. In the VM's action pane click on Start.

        HyperV main interface with an arrow pointing to the Start button in the Actions menu to the lower right.

      24. After the VM starts, open the VM screen and annotate the provided IP address.

      25. Log in using the displayed login and password to configure the network settings. This allows you to configure a static IP, default gateway, search domain, subnet IP address ranges, and the DNS servers.

        VA Web Console showing the URL to continue setup, and the network settings credentials.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Download the Virtual Appliance ova file.
      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Configure Virtual Machine

      Virtual Appliance should be able to work on any supported version of VM Workstation Pro, but it has been successfully tested on versions 12 and 15.

      1. Open VMWare Workstation Pro.

      2. Click Open a Virtual Machine.

        Open a Virtual Machine button as seen in the VMware Workstation Pro interface.

      3. Navigate to the .ova file you downloaded.

        File explorer view after navigating to the OVA file to upload.

      4. Click Open.

      5. Click Edit virtual machine settings.

        An arrow pointing to the Edit virtual machine settings option in the upper left of the VMware interface.

      6. Click Network Adapter.

        VM settings pop-up with the Hardware tab selected, and the Network Adapter option highlighted.

      7. Select Bridged: Connected directly to the physical network (if it is not already selected).

        An arrow pointing to the Bridged: Connected directly to the physical network option in the Network Adapter tab in the VM settings.

      8. Click Add.

        VM settings pop-up with an arrow pointing to the Add button in the lower middle.

      9. Select Hard Disk and click Next.

        Add Harware wizard pop-up with the Hard Disk option and selected and the Next button highlighted.

      10. Keep SCSI selected and click Next.

        Add Harware wizard with the SCSI option selected.

      11. Keep Create a new virtual disk selected and click Next.

        Add hardware wizard with the Create a new virtual disk setting checked.

      12. Adjust the disk size to the minimum recommended setting of 50 GB and click Next.

        PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

        Add harware wizard on the Specify Disk Capacity step where the maximum disk size is edited.

      13. Click Finish.

        Add hardware wizard final step with the path to the disk file and Finish button.

      14. Click OK.

      15. Click Power on this virtual machine.

        VMware VM main interface with the new VM selected, and the Power on this machine option highlighted in the upper left.

      16. When the virtual machine loads, you will see the following message.

        Web console view of the IP address to continue setup, and the network settings login credentials for the VM.

      17. The IP address will be specific to your PrinterLogic Virtual Appliance. You will want to note it for a following step.

      18. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings..

        Web console image with the IP address and network settings credentials highlighted.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Download the Virtual Appliance vmdk file.
      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Initial Configuration

      1. Log into Google Cloud Platform.

      2. Select Storage from the menu on the left.

        Google Cloud platform interface with an arrow pointing to the Storage option in the left-side menu.

      3. Either create a new storage bucket or select an existing storage bucket.

        Storage browser interface with an arrow pointing to the Create Bucket option at the top, and also showing exisiting storage buckets.

      4. After creating or selecting a storage bucket, select Upload Files.

        Bucket Details tab with an arrow pointing to the Upload files button in the middle.

      5. Upload the Virtual Machine Disk file (.vmdk) that was downloaded in the prerequisites.

        It is recommended that this step be done from a PC with an internet connection that supports high upload speeds due to the large file size.

      Convert the VMDK

      This process can take up to 40mn.

      1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        Google cloud platform home screen with an arrow pointing to the Compute Engine option on the left of the screen.

      2. From the new menu displayed on the left, select Images.

        Compute engine menu displayed with an arrow pointing to the Images option on the left .

      3. From the top menu, select Create Image.

        An arrow pointing to the Create Image button at the top of the screen after selecting the Images option.

      4. On the Create Image screen:
        1. Give it a name.
        2. Select Virtual disk (VMDK, VHD) as the source to be used.
        3. Select the Cloud Storage File
        4. In the Operating system on virtual disk section, Select Ubuntu 18.04 Bionic.
        5. Ensure that the Install guest packages box is checked.

        6. Click on Create.

          Create an image wizard with the name, source, cloud storage file path, Operating system on Virtual Disk option, and Install gues packages option highlighted.

      Configure the Image

      1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        Google cloud platform home screen with an arrow pointing to the Compute Engine option on the left of the screen.

      2. From the new menu displayed on the left, select Images.

        Compute engine menu displayed with an arrow pointing to the Images option on the left .

      3. Click on the newly created image name, then select Create Instance at the top.

        Images window with the new image selected in the middle of the screen and an arrow pointing to the Create Instance button in the upper right.

      4. Give the instance a name, select appropriate Region and Zone, and select the Machine Type that meets the recommended system requirements of:

        2. Four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.
        3. 16GB RAM for up to 15,000 users.
          • Add 2 CPUs / 8GB RAM for each additional 15,000 users.
          • Add a minimum of 2 CPUs and 4GB RAM if using the Internal Service Client.
          • Add 2 CPUs and 4GB RAM per 500 CPA/Simple Badge Release installations.
        4. 80GB free hard disk space for the host disk.
        5. There should be 50GB of free hard disk space on the persistent storage disk (add 4GB for every 100 printers).

        Create an Instance wizard with name, region, and machine type options highlighted.

        Port 8080, 8000, 3306 and 443 must be open to complete the setup phase.

      5. Scroll down to the Firewall section and select the appropriate settings to allow your workstation to communicate with the Virtual Appliance.

        Create an Instance wizard with an arrow pointing to the Firewal section, showing the Allow Http and Allow Https traffic options selected.

      6. Select Disks, and then scroll down and select the Add new disk button.

        Disks section with an arrow pointing to the Add New Disk button.

      7. Give the new disk a name and set a size (50 GB is recommended).

        New disk section of the Create an Instance wizard with an arrow pointing to the Size field near the bottom.

      8. Scroll down and select Done on the bottom left.

      9. Click Create on the bottom left.

        Create Wizard with arrows pointing to the Done and Create options at the bottom.

      10. Start the newly created VM instance.

      11. Locate the IP of the newly created virtual machine and copy it.

        VMware VM Instances screen with the newly created machine showing, and the area to copy its IP address highlighted.

        If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

    • Prerequisites

      1. Contact your PrinterLogic sales representative to provide you with access to the Virtual Appliance AMI.

        Only a PrinterLogic representative can provide the Virtual Appliance AMI. It is not available as a Public AMI.

      2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
      3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
      4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
      5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

      Setup

      AWS is a supported platform to run the PrinterLogic Virtual Appliance. Currently, a PrinterLogic sales representative will need to assist you with getting access to the AMI.

      Please be prepared to provide the PrinterLogic sales representative with your AWS Account number so they can share the most current AMI to your account. You can find your account number in your AWS console by clicking on the drop-down next to your login name.

      My Account option to find your AWS account number, as seen in the AWS console.

      Copy the AMI

      1. In your AWS EC2 Dashboard, in the Images drop-down, select AMIs.

        AMI option within the Images drop-down in the AWS EC2 Dashboard.

      2. Set your AWS region to the region provided by your PrinterLogic representative.

        US East (Ohio) option in the AWS region menu options.

      3. On the AMI list screen, select Private Images.

        Private images option displayed in the AWS images sort drop-down.

      4. Locate the AMI that was provided to you in the list.
      5. Right click the image and select Copy AMI.

      6. On the Copy AMI screen, select your Destination Region and click Copy AMI.

        The copy process can take several minutes to complete.

      7. Back on the AMI screen, select the region you copied the AMI to.

      8. Locate the AMI you just copied from the list.

        The copied AMI will display a different AMI ID now that it is in your region. However, the AMI name will stay the same.

      9. Rename or tag the AMI as needed for your use.

      Launch the AMI

      1. Right click on the AMI and select Launch Instance from AMI.
      2. Provide the Virtual Appliance instance a name.
      3. Scroll down and select the Instance type ensuring you are meeting the Web Stack Migration to Virtual Appliance.
      4. Scroll down and select the Key Pair (login) you want to use.
      5. Scroll down to the Network settings section and select the VPC you want the instance installed in.
      6. Select the Subnet you want the instance deployed to.

      The steps to launch the instance from AMI, selecting the key pair for logins, and setting the VPC and subnet for deployment.

      1. In the Firewall (security groups) section, select your Existing security group if you have configured a Virtual Appliance in the past. If this is your first deployment in AWS, it will be necessary to create a security group following the steps in the drop-down option below:

        1. In the Firewall (security group) section, select Create Security Group.
        2. Enter a Security Group Name.
        3. Enter a Description for the security group.

        4. Enter the following security group rules:

          Security Group Rules
          TypeProtocolPortSource

          MySQL/Aurora

          		TCP3306Anywhere
          HTTPTCP80Anywhere
          HTTPSTCP443Anywhere
          Custom TCPTCP8000Anywhere
          Custom TCPTCP8080Anywhere
          SMBTCP445Anywhere
          Custom ICMP - IPv4Echo Request 8Anywhere
      2. The Advance Network Configuration section is optional for the following scenario:
        1. If a Static IP address for the Virtual Appliance is desired:
          1. Create a Network Interface and assign it the desired IP address.
          2. Attach that network interface in these settings.
        2. If DHCP will be used, nothing needs to be done with these settings.

      3. Scroll down to the Configure Storage section and ensure there's a minimum of 80 GB. We also suggest that an SSD (gp3) gets used to offer the ability to specify IOPS for the volume.

        Do not add the additional data volume at this time. You will add that in a later step..

      4. Scroll down to the Advanced Details section and expand it.

      5. Scroll to the bottom and paste the following code into the User Data field.

        Set the DOCKER_NETWORK IP address to the desired private TCP/IP network with a /20 or lower.

        Copy Code
        #!/bin/bash -x
        DOCKER_NETWORK="172.16.0.0/16"
        echo "*** cloud-init script begin ***"
        # Wait for Docker to become available
        until systemctl is-active docker >/dev/null 2>&1
        do
          echo "Waiting for Docker to become available..."
          sleep 5
        done
        echo "Setting Docker network to $DOCKER_NETWORK..."
        set-network "$DOCKER_NETWORK"
        echo "*** cloud-init script end ***"
      6. Select Launch Instance.
      7. Select View All Instances.
      8. Wait for the Virtual Appliance instance to completely launch.

      Attach Data Volume

      1. Select Volumes under the Elastic Block Store section of the menu.

        Instances window with an arrow pointing to the Volumes option in the AWS Elastic Block Store left-side menu section.

      2. Click on Create Volume.
      3. Select the Volume Type. It is suggested that an SSD (gp3) be used to give the ability to specify IOPS for the volume.

      4. Select the Volume Size.

        PrinterLogic recommends a minimum of 50 GB of free persistent hard disk space (add 4 GB for every 100 additional printers).

      5. Select the Availability Zone, ensuring it is in the same zone as your Virtual Appliance instance.

        Create Volume window with the Availability zone drop-down highlighted in the middle.

      6. (Optional) Select the Encryption checkbox and your desired master key if you want drive encryption.

      7. Click on Click to add a Name tag, and give your volume a name.

        Create Volume window with an arrow pointing to the Click to add a Name Tag link in the lower middle.

      8. Click on Create Volume.
      9. The Volume Created Successfully message will display, click on Close to return to your list of volumes.

      10. Locate the newly created volume, right-click on it, and select Attach Volume.

        Created volume window in AWS, with the right-click menu expanded to display the Attach Volume option.

      11. In the instance field, select the Virtual Appliance you just created.

      12. In the Device field, enter /dev/sdp.

        Attach Volume pop-up with the Device field highlighted and showing the /dev/sdp value.

      13. Click on Attach.
      14. Return to your Virtual Appliance instance by clicking on Instances.
      15. Locate and select your Virtual Appliance instance.

      16. Copy the IP Address of your Virtual Appliance.

        Instance details tab with the Private IPV4 addresses highlighted in the upper right.

  7. If not already started, start the Virtual Appliance.
  8. For VM Workstation Pro, HyperV, and ESXi hypervisors ONLY. (For AWS and Google Cloud Platform skip to Step 9.)
    • Launch the remote VM console of your hypervisor and login to the Virtual Appliance Console with the network user credentials specified. Configure TCP/IP settings as applicable (use either manual settings or DHCP reservation).
    • The Virtual Appliance starts as a DHCP client. It’s possible to leave it that way and configure the TCP/IP settings via DHCP Reservation. Otherwise, use the steps below to configure a static IP and to optionally change the private IP range that the Virtual Appliance uses by default so that it doesn’t conflict with existing subnets in the environment.
      1. In the hypervisor where the Virtual Appliance runs, open the web console to access the Virtual Appliance Linux terminal interface.
      2. Login with the credentials supplied in the terminal banner for the network user.

        VA web console showing basic settings with the network settings credentials highlighted.

      3. Enter "Y" to change the network settings.
      4. Enter "Y" to change the network mode.

      5. Enter the TCP/IP settings.

        The image below is just an example. Ensure you use the settings specific to your network.

        VA web console, after logging in with network settings credentials, with the adjustable network settings all displayed and highlighted.

      6. If the existing address pool does not conflict with any subnets in the environment, enter “N”. Otherwise, enter “Y” to set a different address range.

        VA web console, Would you like to change the unassigned address pool for your network setting highlighted.

        If needing to adjust IP addresses, be sure to read and understand the network range options you are presented with. Any range used must have a netmask < 20.

        VA web console, with the network range IP requirements highlighted.

      7. If needing to adjust the IP address ranges, configure the address range.

        The image below is just an example. Ensure you use the settings specific to your network.

        VA web console, example highlighted of the unassigned CIDR range.

      8. Press any key to exit.

  9. Run the Virtual Appliance Configuration UI by navigating to http://VA_IP_Address:8080

    VA configuration wizard with the orange Lets do this button in the lower middle.

  10. Choose the Upgrade my Current Instance option.

    VA wizard interface with and arrow pointing to the Upgrade my Current Instance button.

  11. On the Configure Storage page, select VM-Attached Virtual Disk for the Storage Type and click Format Attached Storage.

    Configure Storage tab of wizard displaying the Storage Type drop-down and the Format Attached Storage button.

  12. On the Migrate Database page, enter the IP Address of the production Web Stack instance (printers.company.org) in the Host field.

    Migrate Database window showing the field for Host highlighted in the middle.

  13. Enter in your Username and Password.

    Migrate Database tab with the Username and Password fields highlighted.

  14. Enter the APP_KEY from your Web Stack instance.

    1. Browse to your Web Stack .ENV file.
      1. Default path is: C:\intetpub\wwwroot\.env

    2. Open the file with a text editor and locate the APP_KEY and copy it.

      .env file for reference with the App_Key highlighted.

    Migrate database tab with the field for the App Key highlighted.

    15. By default, the Web Stack MySQL instance is configured to only allow local connections. If the MySQL Connection Test fails on this step, this restriction can be lifted so that the Virtual Appliance Migration can access the production MySQL database.

    Run the following command at a MySQL Command Prompt on the production Web Stack server (the MySQL root password can be found inside the c:\inetpub\wwwroot\config\settings.php file on the production Web Stack instance):

    use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

    Copy Code 
    use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

    To revert this setting, run the following command at a MySQL Command Prompt on the production Web Stack server:

    use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

    Copy Code 
    use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

  15. On the General Settings page, enter the temporary FQDN of the Virtual Appliance (va.company.org example used in image) in the Domain Name field. Keep the suggested Shared Storage Password or set it to something else, and click Continue. Ensure you document the password!

    Ensure that the entire FQDN is used and not just the domain name in the Domain field.
    Ensure you document and save the Shared Storage Password so you can access the Data Drive later as needed.

    General Settings page of the wizard with the Domain Name and Shared Storage password fields highlighted at the top.

  16. Request that your PrinterLogic representative create a trial license that will match your production license capabilities, except use the temporary FQDN of the Virtual Appliance (va.company.org).

    General Settings tab with the License file field and Upload button highlighted.

  17. [Optional] If you created a temporary SSL certificate for the Virtual Appliance, upload the certificate and key here, and click Continue.

    General Settings tab with the SSL Certificate, SSL Key, and their related Upload buttons highlighted.

  18. Select Continue on the Setup Database page.

  19. Click the final Finish Upgrade button and wait for it to complete.

    VA Wizard, Let's Migrate your WebStack database tab with an arrow pointing to the Start Migration button.

    A large database could take a couple hours to complete.

  20. Perform any testing with one or more clients that have been updated to point to the temporary FQDN of the Virtual Appliance (va.company.org).
  21. Schedule cut-over to the Virtual Appliance in production.

  22. Cut-over steps:

    1. [Optional] Install the updated PrinterLogic Client on end-user workstations (this can be done automatically after cut-over in the Virtual Appliance Admin Console by configuring client automatic updates.
    2. Shutdown the Web Stack server.
    3. Copy the production license file to the /pi/storage folder on the Virtual Appliance appliance-storage share, overwriting the existing.
    4. [Optional] Copy the new production Virtual Appliance certificate files (referenced above in the requirements section) to the certs folder on the Virtual Appliance appliance-storage share, overwriting the existing files. The SSL certificate files need to be named ssl.crt and ssl.key.

    5. Edit the secrets.env file at the root of the Virtual Appliance appliance-storage share and change the PRINTERCLOUD_DOMAIN variable to the production FQDN (printers.company.org).

      When editing the secrets.env file, an editor like Notepad ++, Sublime Text, or Visual Studio Code must be used to ensure the file uses Unix line endings (LF only) and is saved in UTF-8 format with no byte-order mark.

    6. Modify the existing DNS A record for the production FQDN (printers.company.org) to point to the IP address of the Virtual Appliance.
    7. Create a DNS CNAME record for the wildcard underneath the production FQDN (*.printers.company.org) and point it to the production FQDN (printers.company.org).
    8. Reboot the Virtual Appliance. Once the Virtual Appliance is in a “Running” state, clients should be able to connect.

Features Impacting Migrations

Data Warehouse

If you are currently using the Data Warehouse feature, you will lose that capability until PrinterLogic releases the new reporting API.

Mobile Printing

The migration will create a Service Client object “Service Client Migrated” if Web Stack didn’t have one defined. It will place any Mobile Print settings on the SC, but they will not be functional because Mobile Print needs to run on an external SC. If you had a SC already on Web Stack, the settings will reside there. You will need to create an external SC and copy those settings over.

Control Panel Application

If you are using the CPA on any printers, it is recommended that you uninstall them prior to cut-over and then reinstall from the Virtual Appliance.

Simple Badge Release

If you are using Simple Badge Release, it is recommended that the configuration be undone prior to cut-over and then reconfigure with the new SBR interface.

External Service Client

Uninstall existing external Service Clients, and set them up again after cut-over.