GroundWork Monitor 8 utilizes Docker containers and a Continuous Integration/Continuous Deployment methodology. This means less waiting for feature development, security patches and bug fixes. You no longer need to do a complete application upgrade to obtain fixes and features. You get faster turnaround on bugs, feature enhancements, and security fixes, with little effort on your part to maintain your on-prem monitoring system. 

Select the tab below for the installation type you wish to perform. New Install is used for a fresh GroundWork Monitor installation; Update Install will update a previously installed version of GroundWork Monitor 8; Migrate Install is considered a fresh GroundWork Monitor installation plus a migration of your Monarch configuration from a previous version of GroundWork Monitor 7.x.; and Uninstall is used to remove GroundWork Monitor 8.

After installation, please review related articles.

New Install

This section steps through an initial installation for GroundWork Monitor 8.0.0. The New Install uses the Install from Installer is an offline method, it does not require internet access, and uses a distributed GroundWork Installer file to install. You will need to prepare your system, get the installer file, and run the installer. The installer will initially create a gw8 sub-directory and will drop the configuration files into this subdirectory. The entire installation will take approximately 25 minutes to complete.

If your installation is an Update and not a New Install, please refer to Update Install.


  1. First, prepare your system as described in System Requirements, including installing Docker CE and Docker Compose.
  2. Review the Release Notes which contain details of issues fixed, new features, and items of interest to those users who have customized or significantly enhanced a previous version of GroundWork Monitor.

    If you are updating please see the Update Install from the tab above. It is recommended that you perform a backup before updating your installation.

  3. Make sure you can access Docker by running the following commands:

  4. Next, obtain the GroundWork Monitor 8.0.0 installer file from the Downloads page.


After completing thePrepare steps above, you can proceed by running the installer.

Do not run the installer as the root user. There is no need to, as long as the user has access to the file system and Docker, and the Docker daemon is running.

  1. Mark the file as executable:

    chmod +x
  2. Run the installer:

  3. Follow the prompts to confirm you want to install, that the resource check is ok, and later for the timezone for cron jobs and networking settings:
    • For Timezone, set this to the timezone that will be used for cron. It should be the timezone most users will access the system from. This can be different from the server timezone, but ideally is not. 
    • The networking settings are designed to avoid conflicts in your networking setup. If you use the subnet anywhere internally, make sure that the subnet chosen by the installer does not conflict with your use of it elsewhere or you may not be able to use the system until you correct it.
    • To adjust these settings later see Configuration files.
  4. When the process completes, open a browser to the name or address of the host system to log in to GroundWork Monitor 8.0.0, the default Administrator login is admin/admin. Note that it may take a few minutes for the availability calculations to complete and display, so you may see warnings about this on the relevant dashboards.

Update Install

This section steps through an update installation for GroundWork Monitor 8.0.0. The Update from Installer is an offline method, does not require internet access, and uses a distributed GroundWork Installer file to install.

Prepare and Run

  1. First, check your system is prepared as described in System Requirements, including installing Docker CE and Docker Compose.
  2. Review the Release Notes for the version you are upgrading to, which contain details of issues fixed, new features, and items of interest to those users who have customized or significantly enhanced a previous version of GroundWork Monitor. 
  3. The Installer method of installation supports updates, and  running the Installer will update an existing GroundWork Monitor installation.

    It is recommended you perform a backup before updating your installation. 

  4. Open a command line to the directory where you installed GroundWork Monitor 8. This is the directory above the gw8 directory. Check with an ls command to be sure. You should see the gw8 directory listed. 
  5. Next, go to the Downloads page and select the Installer file for the new version and place it in this directory.
  6. Change the installer mode and run it as you did when performing a New Install. The installer will shut down GroundWork, extract all the new containers, update the system and restart it.

Migrate Install

Migrating Monarch to GroundWork Monitor 8

This section steps through the migration process for GroundWork Monitor 8. Refer to the New Install tab above to perform a new installation. After installation you can refer to the migration tasks on this page.

Regarding "localhost" and added hosts

The migration to GroundWork Monitor 8 is not quite exact, since the way we do self-monitoring in GroundWork Monitor changes significantly. Therefore you can expect that the "localhost" host in GroundWork Monitor 7.x configurations will vanish in GroundWork Monitor 8 after migration. If you have any particular custom services assigned to localhost that you wish to preserve, we suggest you move them to another host first. 

Also, you will see several added hosts in GroundWork Monitor 8 for the containers that run the system. Nagios™ ping checks of the containers will be automatically added after migration, and will show in the default Status Summary. These hosts and services are necessary, and any license will be increased to include them at no charge. They have names like "gw8-dockergw8_elasticsearch_1", and have several services from the Docker Cloud Hub connector as well. 

GroundWork Monitor 7.x

The following steps can be used to capture your existing GroundWork Monitor 7.x Nagios configuration database from your latest backup.

  1. Access the command line on your Groundwork 7.x server, for example via SSH. We assume you are using a user that is not root, but has sudo access. If you use root, then you can omit the sudo part. 
  2. Copy and paste the following command and run it:

    sudo tar -C /usr/local/groundwork/core/monarch/backup \
        -czf /tmp/$(ls /usr/local/groundwork/core/monarch/backup | tail -1).tar.gz \
        $(ls /usr/local/groundwork/core/monarch/backup | tail -1)

    This will produce a file such as /tmp/2018-12-26_16-44-47.tar.gz. This is the backup to be transferred. Note the date portion of the filename as the timestamp for the next steps, e.g., "2018-12-26_16-44-47" in this example. 

GroundWork Monitor 8

  1. Transfer the backup you made above to the GroundWork 8 server. Place it in the gw8 directory. Use any secure method of transferring files you like, e.g., SCP. 
  2. From the command line on the GroundWork 8 server, change to the gw8 directory:

    cd gw8
  3. Substitute the appropriate timestamp from your captured filename and set it as the timestamp variable. For example (you will need to use your own timestamp):

  4. Copy and paste the following two commands to set the TAG variable and load the configuration:

    TAG=$(grep '^TAG=' .env | sed 's/^TAG=//')
    docker run --rm \
        -v ${PWD}/$timestamp.tar.gz:/$timestamp.tar.gz \
        -v dockergw8_monarch-backup:/usr/local/groundwork/monarch/backup \
        --name gw8 groundworkdevelopment/gw8:${TAG} \
        /src/ loadMonarchBackup $timestamp.tar.gz
  5. In GroundWork Monitor 8, go to Configuration > Nagios Monitoring > Control > Back up and restore and proceed to restore the GroundWork Monitor 7.x backup with the noted timestamp.


This uninstall process completely removes GroundWork Monitor 8, removing volumes and containers and the docker directory. It does not remove other docker containers and volumes that may exist on the same host. 

Removing GroundWork Monitor 8

  1. Go to the Docker directory you created when you installed GroundWork Monitor 8.
  2. Go to the gw8 directory:

    cd gw8
  3. Shut down the existing containers:

    docker-compose down
  4. Remove GroundWork Monitor 8 volumes and containers:

    docker volume ls | grep "$(grep COMPOSE_PROJECT_NAME .env | sed -e 's/^[^=]*=//')_" | \
        awk '{print $2}' | xargs docker volume rm
    docker images -a | grep "groundworkdevelopment/" | \
        awk '{print $3}' | xargs docker rmi
  5. Remove the docker directory:

    cd ..
    rm -rf gw8

Related articles