Introduction and Purpose

The Primero application can run as a stand alone instance on a Windows PC without consistent internet connectivity. The Primero application runs using VirtualBox VM and the user can access the application using a browser just like the version that is connected to the Internet. The stand alone instance can be configured to sync to another server running Primero as part of a larger deployment.

This document is meant for IT staff who have administrator access to laptops and other Windows PCs so they can make system configuration changes and install the Primero application. This guide describes the minimum system requirements, the installation steps, how to run Primero once it’s installed locally, and some troubleshooting assistance.

Prerequisites and System Requirements

To be able to install the Primero application on a Windows PC, the PC must meet or exceed the following requirements:

  • Operating System: Windows 7 32/64-bit

  • VT-x processor extensions - BIOS Settings Enabled for this feature

  • 4GB RAM recommended (minimum 2GB)

  • Browsers:

    • Internet Explorer: IE 10.0 or higher

    • Google Chrome: v32 or higher

    • Mozilla Firefox: v26 or higher

Installation Instructions

Prior to running the Installation, you must be logged on to the PC with Administrator rights to make modifications. If you are not logged in with administrator rights, make sure you run the installer file as an administrator. To do this in Windows, right-click on the installer file, and select “Run as Administrator.” Once logged in:

  • Make sure that the computer is connected to the internet.

  • Make sure that the computer has VT-x enabled in the BIOS. If the computer does not have VT-x enabled, DO NOT ATTEMPT TO INSTALL PRIMERO until this is changed. (For instructions on how to enable VT-x, see the section labelled “How to Change the BIOS Setup.”)

  • Download the installer from deployment location: primero-installer.exe

To run the installation program:

  • Double click on the installer file once it has been downloaded.

  • Click on RUN and YES to give permissions to Primero to make changes on the system when the following modal appears:

  • When the Primero Setup Wizard starts up, as shown below. Click NEXT.

  • Select the destination location. By default it will be “C:\Program Files\Primero” and then click NEXT.

  • Select the type of installation. On first install it will be “Full Installation” and click NEXT.

  • Select the Start Menu folder. By default it will be “Primero” then click NEXT.

  • A configuration summary similar to the one shown below will appear. Review the information; if it is correct, click INSTALL. To change the information, use the BACK button to correct whatever is necessary and click INSTALL once ready.

  • A second confirmation window will appear as shown below. Click INSTALL to proceed with the installation process.

  • A terminal window for VirtualBox VM will pop up. Wait for the installation to finish.

  • If a new Windows security box appears, click ALLOW.

  • Occasionally, you may encounter a BIOS error. If this occurs, see the instructions for How to Change the BIOS Setup below to ensure the Virtualization is enabled in the BIOS settings..

  • Once the installation finishes successfully, a new box is shown notifying the user that the installation finished successfully. Click “OK”

  • Close the installation wizard by clicking on “Finish”. The terminal window for VirtualBox VM will remain open and the VirtualBox VM will still be running.

How to Run Primero

Starting the VirtualBox VM and Primero

If the VirtualBox VM is still running, you can access the Primero application through the browser using the URL https://localhost:11443/login. If the VirtualBox VM is currently stopped, go to the Windows Start Menu and use the following options to restart it:

All Programs > Primero > Start Primero

  • A command window will pop up with the message “VM started. Press any key to continue...”. Press any key to close this window. The VirtualBox VM window will open and the VirtualBox VM will start running.

  • Wait for the Virtual Box to finish starting. If this is the first time, this step may take a few minutes. When primero is ready it shows the following login message:

    Ubuntu 14.04 LTS ubuntu-i386 tty1

    ubuntu-i386 login:

    You do not need to enter anything here. Do not close this window - it must remain open for the application to run properly.

  • Open your preferred browser, Google Chrome or IE 10 for example, and type: https://localhost:11443 in your navigation bar. Make sure “https://” is included.

  • The browser will redirect the page to https://localhost:11443/login. If you get a 404 or 400 error, wait a few seconds and refresh the page.

  • A certificate error similar to what is shown below will appear - each browser handles this somewhat differently. This is expected behavior. Click on “Advanced” and “Proceed”.

  • The browser will redirect to the login page https://localhost:11443/login and the login for the Primero application will appear as shown below. All functionality is identical to the version that is connected to the internet.

How to Stop the VirtualBox VM and Primero

To stop the VirtualBox VM:

  • Open the VirtualBox VM window.

  • Select the Machine option from the menu or click on the X at the top-right of the window.

  • Select Send the shutdown signal option and click OK.

  • A few commands will appear and the command window for the VirtualBox VM will close.

Once you have stopped the VirtualBox VM, the Primero application will no longer be available in the browser window. It is necessary to restart the VirtualBox VM using the Start Primero command from the Windows menu.

How to Reset the VirtualBox VM

Before resetting, make sure all the data within the Primero application running in your browser window has been saved. To reset the VirtualBox VM:

  • Open the VirtualBox VM window.

  • Select the Machine option from the menu.

  • Select Reset option.

  • When the confirmation appears, click the RESET button.

How to Uninstall Primero

Primero can be removed from the computer in two steps: uninstalling Primero and uninstalling VirtualBox VM.

To uninstall Primero:

  • Go to the Windows Control Panel by clicking on Start menu button and click on Control Panel.

  • On the Program section, select Uninstall a Program

  • Select ‘Primero’ from the list. Right click on it and click on Uninstall.

  • When the message appears asking to confirm that you want to delete Primero and all of its components, click YES.

  • When the message appears that Primero is successfully removed from the computer, click OK.

The second step is to uninstall the VirtualBox VM. To do this:

  • Go to Windows Control Panel as in the instructions to uninstall Primero

  • On the Program section, select Uninstall a Program

  • Select ‘Oracle VM VirtualBox’ from the list. Right click on it and click on Uninstall.

  • When the message appears asking to confirm that you want to delete Oracle VM VirtualBox and all of its components, click YES.

  • If a new message saying ‘Do you want to allow the following program to update software on this computer?’ is shown click on YES.

  • It is necessary to delete two directories on the computer to fully remove the VirtualBox VM. These can be found in the C:\Users\ folder. Delete the directories ‘VirtualBox VMs’ and ‘.VirtualBox’.

How to Change the BIOS Setup

Before installing Primero, the user must enable Virtualization Technology in the system BIOS settings. Note that the BIOS startup and BIOS interfaces vary based on computer manufacturer and model. There will be different steps for enabling virtualization. A common set of key combinations for entering system BIOS settings can be found here:

http://pcsupport.about.com/od/fixtheproblem/a/biosaccess_pc.htm

Follow the steps below to enable Virtualization Technology VT-x for recent versions of Lenovo ThinkPad notebooks which are common machines for Primero users:

  1. Shutdown the system, reboot, and enter into BIOS setting by pressing ENTER during startup.

  1. Press <F1> to enter the Setup Utility.

  1. Navigate to the “Security” tab and select “Virtualization” and press ENTER.

  1. Enable both virtualization options if disabled.

  1. Press <F10> to Save and Exit. The machine will again restart, now with virtualization enabled. You may proceed with installation.

Using Virtual Machine Files Directly

In addition to using the Primero Windows Installer, a user may run Primero on their computer by running a virtual machine file in VirtualBox directly. This option is a good one for those who are comfortable using virtual machines and want more control over the way Primero is run on their computer. This option also allows a user to run Primero on a Mac rather than a PC. Using VM files directly is the preferred method of use for those who will be maintaining and testing configuration bundles for Primero.

On the other hand, if you are planning on maintaining important data on your Primero instance which you are afraid of losing, you should stick with using the Windows Installer. The reason for this is that the Windows Installer allows you to upgrade to new versions of Primero without losing your data. To be clear, if you are worried about losing data stored on your local instance of Primero, DO NOT use the virtual machine file directly; use the Windows installer instead.

The requirements for running the VM directly are the same as those listed above for the Windows Installer, except that it must run OS X. To create a VM instance on your computer, you will first need to download VirtualBox. Please see the VirtualBox site (https://www.virtualbox.org/) to download the application and for installation instructions. Once you have VirtualBox installed, you will need to download a Primero VM file, usually one with a file extension of “.ova”. To open it, right-click on the file, click “Open with . . .” and then select VirtualBox.

At this point, VirtualBox will ask you if you want to import the virtual machine. Click “Import,” and VirtualBox will begin to create a machine using the .ova file.

Once the import is complete, you can double-click on the machine to start it up. (The new machine will be highlighted in blue in the machine list on the left-hand side of the VirtualBox window once the import has finished.) At this point, you will use the VirtualBox application itself to start, stop, and re-configure your machine.

One advantage to using virtual machine file directly through VirtualBox is that VirtualBox allows you to create clones and snapshots of your machine. These allow you, if you make a mistake, to “rewind” your machine back to what it looked like before you made said mistake. For more information on clones and snapshots in VirtualBox, please see the VirtualBox documentation: http://www.virtualbox.org/manual/ .

Making Your Machine a Library Instance

To have the VM you have created on your computer function as a Library Instance, you must make the Primero instance running on that VM broadcast to an IP address which is accessible across the local network. Using the steps below, you will do just that, allowing anyone connected to your office’s network to use the Primero instance running on your VM.

Check office network’s security measures

If you hope to make your Primero instance accessible on the local network, you will need to make sure that your network’s firewall is not blocking ports 6984, 80, and 443. These ports are absolutely essential for Primero to function properly. Depending on your organization, you may need to have your office’s IT team do this.

Disable original adapter

You will now need to adjust the VM’s network settings. First, shut off the machine by clicking on the “X” mark in the top of the machine window, selecting “Power off the machine,” and then clicking “OK.”

Now, in the main VirtualBox window, click on your machine, and, in the options at the top of the window, click the gear icon to navigate to your machine’s settings. Then select the “Network” bar to see your network settings.

In the network settings, you should see a series of tabs, labelled for adapters 1 through 4. By default, your machine will only have the first of these enabled, and the “Attached to” setting will be set to “NAT.” NAT is the simplest type of network adapter your VM can have configured, allowing it to have basic access to the internet. For more information on the different types of adapters available in VirtualBox, please see the VirtualBox documentation on Networking. While we want to leave this adapter in place, we do want to disable it to prevent it from overriding the address on which we will be broadcasting Primero. To do this, uncheck the tickbox labelled “Enable Network Adapter.”

Please note that, while disabling this adapter will allow us to broadcast Primero through a network-accessible IP address, it will also keep us from accessing Primero via the “https://localhost:11443” address we had used before. The IP address to which Primero broadcasts will now be the only way to access the application.

Enable second adapter, choose adapter type

Once that is done, we will want to create a new adapter to help broadcast Primero. First, click on the “Adapter 2” tab. Enable this second adapter by checking the “Enable Network Adapter” tickbox. Next, we want to change the “Attached to” option to reflect the kind of network adapter we want. Here, we want to use a “Bridged Adapter,” a type of adapter that allows a server running inside your VM to directly access your computer’s network hardware and thus broadcast to an IP address. Once again, for more information on the various types of network adapters, please see the VirtualBox documentation on Networking.

Choose which adapter card we’re using

Next, we need to select the name of the particular adapter card we want to use. The selection we choose will depend on how users are going to be accessing the network, and through it, Primero. Specifically, we want to know whether they will be connecting to the office network using a wired (ethernet) or wireless (wi-fi) connection. Since these two types of connections tend to operate on different parts of the network, there is the possibility that machines using different modes of connection will not be able to talk with each other. Because of this, a good rule of thumb is to make sure that the machine hosting the Primero instance and the machines which are accessing it are using the same mode of connection. Your users are connecting via ethernet? Connect the host computer to the network with an ethernet cable and select the ethernet adapter when configuring your machine. Users are using wi-fi? Connect the host machine using wi-fi and select the wi-fi adapter in your VM configuration. In the example below, we are using the wi-fi option.

The names of the different adapters will change depending on the type of computer you are using. In our example, the wi-fi adapter happens to be a Broadcom adapter. The important part, when selecting the right adapter, is to use the one that corresponds to your connection type. Wi-fi cards are usually easier to identify than ethernet cards, since they generally have the words “wi-fi” or “wireless” in the name. Ethernet adapter names are a bit more ambiguous. In a situation like the one in the picture above, we can just use process of elimination to determine that the ethernet card is the one which does not have “Wi-Fi” in the name.

Finding the right adapters on a Mac is a bit easier, since the names for these adapters are fairly consistent, with ethernet adapters generally being labelled as the “Thunderbolt” adapter and wi-fi adapters being named “AirPort.”

Configure advanced settings

Once you have selected the proper network adapter, click on the word “Advanced” to reveal the advanced settings. Here, the default settings should be suitable for Primero’s needs, but just to be sure, check that “Promiscuous Mode” is set to “deny.” Then click “OK” to finalize your settings. Now that the network settings for your machine have been saved, it is time to start up your machine, login, and find the IP address on which Primero is broadcasting.

Restart your machine

Go ahead and double click your machine to restart it. A window will open with your machine’s terminal in it. You will see the machine starting up, with lots of output displaying in the terminal. Ignore all of this until you see a line telling you to login. You may also see a few translucent notifications at the top of your terminal window. These explain that the virtual machine you are using will all capture keystrokes and mouse clicks. Please note that if you do click within the VM window, you will be unable to move your mouse outside of it, since your mouse movements are now being entirely captured by the VM. To go back to using your mouse normally, hold down the control key and click your mouse. For more information on how VirtualBox captures key and mouse actions, visit their guide on the subject. Since these warnings can get in the way of you seeing what’s happening on your machine, hit the “x” on each to remove them.

For your login, type “ubuntu,” and then press Enter. The machine will ask you for a password. Type “primero,” and press Enter.

Get IP address

You will now see a command line prompt. Type “ifconfig” and press Enter. You will see something like the output below.

The command we just typed, “ifconfig,” tells you all of the IP addresses in use on your system. We will always want the first IP address under the “eth0” section. This line containing this address will start with the term “inet.” In the example above, the address we want to use is “10.1.10.52.”

To test and see if your machine is broadcasting to the network properly, connect another computer to the network the same way your host computer is connected (ethernet or wi-fi), open a browser, and go to that IP address, prefixed by “https://”. So, in the case above, we would go to “https://10.1.10.52”. If you get to the Primero application, your broadcast has worked. Note that you may also receive a screen telling you that the connection is not secure, in which case, you should proceed to the page anyway. For more information on how to bypass this security screen, please consult the Primero Installer for Windows Administrator and Installation Guide.

Virtual Machine Network Configuration Troubleshooting

Reset the MAC address

If you cannot reach the IP address you found in the steps above over the local network, you may want to try resetting the MAC address for the new adapter you configured. A MAC (media access control) address is an address given to your computer’s adapter card by the network when it connects. Refreshing this address will force a number of processes to run over again when you restart your machine, and, in the process, potentially fix any problems that may have occurred when Primero attempted to broadcast to an IP address.

To refresh your MAC address, shut down your machine, and go back into the machine settings, clicking on the Network section. Click on the tab for Adapter 2. If you click on the word “Advanced,” you should see a field towards the bottom labelled “MAC Address.” To the right of the field, there should be an icon with two green arrows circling each other. Click this, and a new MAC address will show up in the field. Click “OK” to save the new address.

Now that you have a new MAC address, it is time to restart your machine, get Primero’s IP address, and attempt to navigate to it, repeating steps 6-8 above.

Troubleshooting

Here are some common errors that may be encountered when running the locally installed version of Primero:

  • A 404 error on accessing the Primero application after starting or restarting the VirtualBox VM: The VirtualBox VM needs a brief period to start up before accessing Primero through the browser. Wait 30 seconds and refresh the browser page after the 404 error.
  • Can’t access the Primero application after computer hibernates: The VirtualBox VM must be properly shut down before the PC goes into hibernation. If the laptop hibernates while the VirtualBox VM is running, the application must be reset using the instructions above before accessing the application in the browser again. Previously saved data will not be lost.
  • Replication sync does not work: Make sure that the computer is connected to the internet before attempting to sync. If the sync still fails, reset the VirtualBox VM using the reset instructions above, and attempt the sync again.
  • Other, non-Primero applications are running slowly: This may occasionally happen on weaker laptops when Primero is performing an intensive task like report generation or synchronization. Wait for the task to finish or close the affected applications.
  • Primero seems stuck: If Primero seems to be stalled for some reason, a reset via VirtualBox VM using the instructions above will typically resolve these issues.