Virtual machine install on Mac OS X

This section will install the Boundless Server virtual machine on a Mac OS X host.

Installation

These instructions provide a virtual machine which has been already configured with Boundless Server, eliminating the need to install Boundless Server directly on your machine.

All interaction with Boundless Server will still be done through your host’s standard browser or a terminal connection. There is no need to interact directly with the virtual machine console once it is running.

These instructions should only be used with VirtualBox. This machine has VirtualBox Guest Additions installed, which is required for functionality such as shared folders.

Note

Prerequisites:

  • Please disable any programs on your system that use ports 2020, 5432, 8080, or 8433.
  • Make sure you have administrative / super-user privileges on your system.
  • You must be able to run a 64-bit virtual machine. 32-bit machines are not supported.
  • You must have at least 2GB of memory and 4GB of free disk space (plus extra space for any loaded data).
  1. Install VirtualBox. You may keep all defaults during the install.

    ../../_images/vbox_welcome_mac.png

    Installing VirtualBox

  2. After installation, run VirtualBox. Navigate to File ‣ Import Appliance.

    ../../_images/vbox_importlink_mac.png

    Import Appliance link

  3. Select the Boundless Server virtual machine file.

  4. Details about the virtual machine will be displayed. Click Import.

    ../../_images/vbox_importmenu_mac.png

    Import Appliance menu

  5. The Boundless Server license agreement will display. Click Agree to accept.

    ../../_images/vbox_license_mac.png

    Boundless Server license

  6. You will now see the Boundless Server entry in the list of virtual machines in VirtualBox.

    ../../_images/vbox_manager.png

    VirtualBox Manager showing Boundless Server virtual machine

  7. Click to select the virtual machine and then click Shared Folders.

    ../../_images/vbox_sharedfolderlink.png

    Accessing the shared folder menu

  8. In order to facilitate copying files from your host system to the virtual machine, we recommend creating a shared folder such that any files copied to that folder will be accessible inside the virtual machine. Right-click the blank area of the dialog and select Add shared folder (or press Insert).

    ../../_images/vbox_sharedfoldermenu_mac.png

    Link to add a new shared folder

  9. Fill out the form:

    • For Folder Path, select a directory on the host machine that will serve as the shared folder. One good option for this directory would be the Desktop.
    • For Folder Name, enter share.
    • Check Auto-mount.
    ../../_images/vbox_sharedfolder_mac.png

    Setting a shared folder

  10. When finished, click OK, then click OK again to close the Settings page.

Post-installation

A few more steps are required before you are ready to proceed.

Start the virtual machine

It is important to test that the virtual machine installed in the previous exercise is running correctly.

  1. Start the virtual machine by clicking the Start toolbar button.

    Note

    Normal Start will spawn a console window, while Headless Start will not. We recommend using Headless Start and interacting with the server via a local SSH connection.

    ../../_images/vbox_headless.png

    Headless Start

    Note

    Occasionally, the virtual machine can not be started. In many cases, this can be solved by going into your machine’s BIOS and enabling hardware virtualization. Please check with your hardware manufacturer for information on how to enable this.

  2. It may take a few minutes for the virtual machine to load. You will know that the virtual machine is ready when you see the Preview pane in the VirtualBox Manager pause and ask for a login:

    ../../_images/vbox_preview.png

    Login screen on the Preview pane in VirtualBox

    Note

    If you chose Normal Start, a console window will be opened. This window captures keyboard and mouse input, which can be a hindrance to working with the virtual machine.

    • If you just see a blank screen, click in the window and press Enter.
    • If you ever lose your mouse or are unable to type, press the Cmd + Tab keys to reclaim focus back from the virtual machine.
  3. Once you see the above screen, open a browser and navigate to http://localhost:8080/dashboard. You should see the Boundless Server Dashboard.

    ../../_images/dashboard.png

    Boundless Server Dashboard

    Note

    If you are using a different hypervisor such as VMware, you may need to replace localhost with the IP address of your VM. Execute ifconfig inside the console of the VM to find the IP address.

Terminal setup

Most interaction with Boundless Server will be done through a browser, but occasionally we will want to run commands directly on the virtual machine. To do this, we will use a terminal client.

Note

Use Headless Start to prevent the virtual machine console from even being shown.

We will use the following connection parameters to connect to the virtual machine via the terminal:

  • Host name: localhost
  • Port: 2020
  • User: root
  • Password: boundless123

Linux and OS X systems have a built-in terminal utility with the ability to run SSH commands.

  1. Enter the following command on a terminal:

    ssh -p 2020 root@localhost
    
  2. The first time connecting to the virtual machine will fail (as the “ECDSA key fingerprint” used for a secure connection is not trusted). Enter yes to add localhost:2020 to the listed of known hosts.

  3. When asked for a user name, enter root and press Enter.

  4. When asked for a password, enter boundless123 and press Enter.

  5. Check the shared directory to confirm that files can be shared between the host and the virtual machine:

    cd /media/sf_share
    ls -l
    

    You should see the contents of your shared directory.

Note

If you named your shared directory something other than “share”, the shared folder will be named /media/sf_<name>.

Using the shared folder

We recommend using the shared folder as a way of transferring files between your host and your virtual machine, but not as a permanent storage location.

To load a file on your host system into GeoServer:

  1. Copy the file to your shared folder on your host system.

  2. Open a terminal to the virtual machine.

  3. Verify that the file is there on your virtual machine:

    cd /media/sf_share
    ls -l
    

    Note

    If you don’t see this directory, check that your shared folder settings are correct and that you copied the file to the correct location.

  4. Copy or move the file out of the shared folder to a location on your virtual machine.

    cp /media/sf_share/data.zip /opt/data/data.zip
    
  5. Make sure that the Tomcat service user (tomcat8) has access to the file:

    chown tomcat8:tomcat8 /opt/data/data.zip
    
  6. Now launch the GeoServer Layer Importer by logging in to the GeoServer admin interface and clicking Import Data.

  7. Click Browse to select the file.

    ../../_images/vbox_importshared.png

    Importing a file into GeoServer

  8. Select the file and continue with the import.

Create a snapshot

While not required, it can be useful to create a snapshot of the virtual machine now and at various other times (say, before a major configuration change). This can help reduce downtime if there is a server issue. We’ll start by taking an initial snapshot.

  1. Shut down the virtual machine.

    sudo poweroff
    
  2. In the VirtualBox Manager, select the virtual machine, and click the Snapshots button on the top right of the console.

    ../../_images/vbox_snapshotmenu.png

    Snapshot menu

  3. Click the Take Snapshot button (the camera icon above the Current State).

  4. Enter a snapshot name. For the first snapshot, a good name might be Initial installation.

    ../../_images/vbox_newsnapshot.png

    Creating a new snapshot

  5. Click OK.

  6. Restart the virtual machine.

Restore a previous snapshot

Should you ever encounter a system error that you are unable to recover from, you can always revert the virtual machine to a recent snapshot and restart the course from that position. This should only be done if all other troubleshooting options have been exhausted.

To restore a previous snapshot:

  1. Shut down the virtual machine.

  2. Click the Snapshots button on the top right of the console.

  3. Click to select the snapshot in the list, then right-click and select Restore Snapshot button.

    ../../_images/vbox_snapshotmenurestore.png

    Restoring a snapshot

  4. The snapshot will be restored.

  5. Restart the virtual machine.

Extensions

All Boundless Server extensions are downloaded as part of the virtual machine.

To install an extension:

  1. Open a terminal (as described above).

  2. Run the following command:

    apt-get install <package>
    

    where <package> is the name of the package.

    Note

    See Package list for a list of package names.

    Warning

    You may receive a warning that packages cannot be authenticated. This is expected, and you may safely proceed.

  3. Depending on the extension, you may need to restart the server.

Virtual Machine reference

When connected to your virtual machine, the following commands may be useful:

  • Start GeoServer:

    $ sudo service tomcat8 start
    
  • Stop GeoServer:

    $ sudo service tomcat8 stop
    
  • Start PostgreSQL/PostGIS:

    $ sudo service postgresql start
    
  • Stop PostgreSQL/PostGIS:

    $ sudo service postgresql stop
    
  • Shut down the virtual machine:

    $ sudo poweroff
    

The following paths will be referenced on multiple occasions:

  • GeoServer data directory

    /var/opt/boundless/server/geoserver/data/
    
  • GeoServer application directory

    /opt/boundless/server/geoserver/
    
  • Shared VM directory (default)

    /media/sf_share/
    

    Note

    If you named your shared directory something other than share, the shared folder will be named /media/sf_<name>.

The virtual machine is running Ubuntu, so please read more about Administration on Ubuntu for more information.