This is the Installation Guide that is distributed with Grindstone Sync Server. It was last updated on April 29, 2019.

Download

The ZIP archive from which this Installation Guide file originated contains the following files:

Requirements

Hardware

  Minimum Recommended
Processor Register Width 32 bits (x86) 64 bits (AMD64)
Processor Base Frequency 1.6 GHz 2.6 GHz
Threads or Virtual Processors 1 4
Random Access Memory 1 GB 4 GB
Service Host Disk Space 10 MB
Database Disk Space 50 MB 250 MB

Software

  Minimum Recommended
Microsoft Windows Version NT 6.2 (Windows 8 / Windows Server 2012) NT 10.0 (Windows 10 / Windows Server 2016)
Microsoft Windows Edition Professional Standard Server
Microsoft .NET Framework 4.6.2 Latest
Microsoft SQL Server Version 2008 2017
Microsoft SQL Server Edition Express Standard

Latest Tested Versions

  Version
Processor Register Width 64 bits (AMD64)
Microsoft Windows Version NT 10.0 (Windows 10 / Windows Server 2016)
Microsoft .NET Framework 4.7.2
Microsoft SQL Server Version 2017

Installing and Configuring Grindstone Sync Server

Setup Service Files

  1. create a directory from which Grindstone Sync Server will run
  2. copy the contents of the ZIP archive you downloaded into the directory

Configure Grindstone Sync Server Web Services

  1. run GSS.exe on the desktop of the host machine (note: this requires administrative privileges, so Windows may present a UAC prompt)
  2. on the Configuration tab, scroll down to Web Service
  3. if Grindstone Sync should only be accessible via a specific local IP address (as opposed to any local IP address), replace the + in the IP Address setting with the specific local IP Address
  4. if Grindstone Sync should be accessible via a different port than the standard port (6457), change the Port setting to the appropriate port number
  5. if Grindstone Sync should only be accessible via a secured HTTP connection, check the Use SSL setting (Note: this will only work if you have a generally trusted SSL server certificate installed, including the private key, in the local machine store)
  6. if you changed any settings, click the Save Configuration button
  7. close the Grindstone Sync Server desktop app

Configure Windows

  1. if the machine is joined to a domain, create a service account for Grindstone Sync Server to run as
  2. open the Run Installation Assistant short-cut in the directory (note: this requires administative privileges, so Windows may present a UAC prompt)
  3. if the machine is not joined to a domain, type 1, press return, and take note of the name of the service account the assistant created (you will need it when configuring SQL Server)
  4. if the machine is joined to a domain, type 1 and press return; otherwise, type 2 and press return
  5. If you want to give Grindstone Sync Server's service a custom name, type 2, press return, enter the name, and press return; othirwise type 1 and press return (note: a custom name is only necessary if you will be running multiple Grindstone Sync Servers on the same machine)
  6. type 1 and press return
  7. if you checked the Use SSL setting earlier, type 2, press return, type the number corresponding to the appropriate certificate, and press return
  8. type 7 and press return

Configure SQL Server

  1. run GSS.exe on the desktop of the host machine (note: this requires administrative privileges, so Windows may present a UAC prompt)
  2. on the Configuration tab, scroll down to Backing Store
  3. if SQL Server instance you will be using is not on the same machine, enter its hostname or IP address in the Hostname or IP Address setting
  4. if you want to give Grindstone Sync Server's database a name other than GrindstoneSync, enter it in the Database setting (note: this should only be necessary if the SQL Server is hosting multiple Grindstone Sync Server databases)
  5. create a database in SQL Server with the name specified by the Database setting
  6. is the machine on which Grindstone Sync Server is running is joined to a domain or it is the same machine the SQL Server instance is running?
    • if so…
      • in the Security section of SQL Server, create a New Login using Windows authentication for the service account under which Grindstone Sync Server will run
    • if not…
      • in the Security section of SQL Server, create a New Login using SQL Server authentication using any Login name and Password that you like, ensuring that the password policy is not enforced
      • on the Grindstone Sync Server Configuration tab, under Backing Store, click the Login and Password radio button, and enter the Login and Password using the login name and password you chose for the SQL login
  7. ensure that the SQL login you created in step 6 is mapped as a user to the database you created in step 5 and a member of the db_owner database role for it
  8. close the Grindstone Sync Server desktop app

Test the Windows Service

Open the Services management console and attempt to start the Grindstone Sync Server service. If the service fails to start, there should be entries in the Windows Event Log that detail why it could not start. If reading such Windows Event Log entries does not lead you to determine that you made a mistake while configuring Grindstone Sync Server or it is not clear what actions you should take to resolve the matter, please contact Epiforge Support so that we may help you diagnose the problem.

Register Your Grindstone Sync Server Installation

  1. run GSS.exe on the desktop of the host machine (note: this requires administrative privileges, so Windows may present a UAC prompt)
  2. select the Licenses tab
  3. once the Epiforge device signature is available, click the copy to clipboard hyperlink
  4. close the Grindstone Sync Server desktop app
  5. open the Grindstone Sync Server section of your Epiforge account by visiting: https://epiforge.com/account/grindstoneSyncServer
  6. click Add New Installation
  7. paste your Epiforge device signature into the Device Signature text box
  8. change the IP Address or Port values on the form as appropriate to match your current settings (if you did not alter these settings for your installation, the form has already entered their default values)
  9. click Add Installation

Purchase a Grindstone Sync Server License

  1. open the Grindstone Sync Server section of your Epiforge account by visiting: https://epiforge.com/account/grindstoneSyncServer
  2. at the bottom of the section for the Grindstone Sync Server installation for which you are purchasing a license, click Purchase New License
  3. if you do not currently have any validated cards on file, you will be asked to add one at this time
  4. enter a number of seats and adjust the Start and End dates to your preference
  5. check the box at the bottom of the form if you agree to the Grindstone Sync Terms of Use (https://epiforge.com/legal/grindstoneSyncTermsOfUse)
  6. click Purchase New License
  7. read the description of the license you are about to purchase, and then click Charge Card on File to confirm that you wish to purchase the license with a card you have on file
  8. once your purchase is complete and the details of your license are being displayed, click Copy Details to Clipboard
  9. run GSS.exe on the desktop of the host machine (note: this requires administrative privileges, so Windows may present a UAC prompt)
  10. select the Licenses tab
  11. click Add License
  12. click Paste License Details
  13. click OK
  14. close the Grindstone Sync Server desktop app

Create the first Grindstone Sync Administrator

Once you have a valid, active license, your Grindstone Sync Server will allow you to connect to it with Grindstone 4 (see: Grindstone 4 Manual: Connecting to Grindstone Sync). Much like a baby velociraptor, Grindstone Sync Server implicitly trusts the first person with whom it comes into contact. This first person to connect via Grindstone will cause your Grindstone Sync Server to lay the foundation for your team's data, creating a person record in the team data for that person. Their login and password will be set to whatever they supplied when connecting from Grindstone. Finally, they will be promoted to an administrator for the team, since there must always be at least one.

Epiforge recommends that the person reading and implementing these instructions (you) be that first person. Afterward, you may create as many additional people in Grindstone with administrator privileges as is appropriate (see: Grindstone 4 Manual: Managing People).

Reference

Installation Assistant

Open the Run Installation Assistant short-cut in order to easily complete the following tasks:

Settings

Grindstone Sync Server's settings can be altered by modifying the ConnectionStrings.config and Quantum.Server.config files, or by simply running GSS.exe from the host machine's desktop and adjusting controls available on the Settings tab. The latter is much easier, and is therefore the recommended approach.

Note: Changes made on the Settings tab will not take effect until you click the Save Configuration button on the bottom of the tab. Doing so will cause the changes to take effect immediately, even if that installation of Grindstone Sync Server is currently running as a service. This means that it is not necessary to shutdown or restart the service when making settings changes.

Auditing

Logging Level

There are five logging levels:

The default for this setting is Normal.

Backing Store

Provider

This setting determines the database provider that will be used for the backing store. There is only one option, Microsoft SQL Server / SQL Azure, and it is the default.

Hostname or IP address

This setting is the hostname or IP address of the database server that will host the backing store. The default is ., which refers to the Microsoft SQL Server instance running on the local machine. If the Microsoft SQL Server instance you will be using is located on another machine, enter its hostname or IP address as the value of this setting. Epiforge encourages you to use hostnames over IP addresses for this setting when possible.

Database

This setting is the name of the database hosted by the database server, which will contain the data of the backing store. The default is GrindstoneSync, but may be called whatever you prefer. If you have multiple Grindstone Sync Server installations using the same Microsoft SQL Server instance as their backing stores, each installation must each have its own database.

If the database does not exist when Grindstone Sync Server first connects, it will attempt to create it if it has permission to do so. Since it is generally not desired that an application's access to Microsoft SQL Server includes a server role with permission to create a database, you may choose to create a database with the appropriate name and grant Grindstone Sync Server's service account access to this database prior to starting Grindstone Sync Server as a service. In any case, Grindstone Sync Server should be connecting with the db_owner database role for its own database so that it can manage its schema.

Authentication

This setting determines how Grindstone Sync Server will authenticate with Microsoft SQL Server. The options are:

The default is Trusted Connection. Login and Password is not advised, as it will result in a Microsoft SQL Server login and password being stored in plain text within Grindstone Sync Server's configuration files.

Use SQL Azure execution strategy

This setting is only applicable if your database is, in fact, a SQL Azure database hosted in the Microsoft Azure cloud. If it is a SQL Azure database, enable this setting. If it is not, disable this setting. The default is disabled.

When the setting is enabled, two additional settings are available which govern how Grindstone Sync Server will react when Azure's background maintenance makes your SQL Azure database temporarily unavailable:

Processing

Mode

This setting determines the operating mode of Grindstone Sync Server:

The default is Server. Use of the Cloud mode by non-Epiforge entities is not supported.

Await committing paired client last sync

This setting determines whether Grindstone Sync Server will wait for the database to acknowledge that it has committed the time a client last synchronized before allowing the client and changes from other clients to proceed. This default is enabled. Disabling this setting is not supported.

Await committing paired client pending change set

This setting determines whether Grindstone Sync Server will wait for the database to acknowledge that it has committed each client's pending change set before allowing further changes to proceed. The default is enabled. Disabling this setting is not supported.

Resources

Idle team memory time to live

This setting determines how long Grindstone Sync Server will keep your team's data loaded into memory before unloading it after your team has been idle to conserve memory. However, keeping your team's data loaded for longer will make it less likely that the data will have to be reloaded from the database when your team resumes working, which will make Grindstone Sync more responsive. The default value is 00:15:00 (fifteen minutes). If you wish the setting to be greater than or equal to twenty-four hours, you must prefix the number of days with a period—for example, a day and a half would be: 1.12:00.00.

Security

Client request access threshold

This setting determines the maximum amount of times a client attempting to pair with your Grindstone Sync Server may offer invalid credentials before it will be permitted no further attempts within the window defined by the setting below. The default is 5.

Client request access window

This setting determines the size of the window described by the setting above. The default is 01:00:00 (one hour).

HTTP include error detail policy

This setting specifies how Grindstone Sync Server determines whether it will provide details concerning errors that arise as a result of a request to the client that made it:

The default is LocalOnly.

Support

Automatically report errors to Epiforge

This setting determines whether Grindstone Sync Server will automatically report unexpected errors it encounters to Epiforge. The default is disabled. Epiforge encourages you to enable this setting to help us make improvements to Grindstone Sync Server. Error reports are not intended to include any identifying or proprietary information, but it is possible since Microsoft and .NET base class libraries may include it on rare occassions and Epiforge makes no attempt to scrub it.

Web Service

IP address

This setting determines the IP address upon which Grindstone Sync Server will listen for client requests. The default is + (which means all local IP addresses). If you want Grindstone Sync Server to use only one network interface, specify its IP address using this setting.

Note: Licenses incorporate this setting. Changing it will cause your current licenses to be invalidated. Epiforge Support can re-issue licenses to you in the event that you need to change this setting.

Port

This setting determines the port upon which Grindstone Sync Server will listen for client requests. The default is 6457. You may choose any valid port you like that is not already in use on your machine, but keep in mind that the port to which all Epiforge apps and forms will default is 6457.

Note: Licenses incorporate this setting. Changing it will cause your current licenses to be invalidated. Epiforge Support can re-issue licenses to you in the event that you need to change this setting.

Use SSL

This setting tells Grindstone Sync Server whether it should expect that you've associated an SSL server certificate to the port upon which it is listening. The default is disabled. Enable this setting if you have associated an SSL server certificate to the port upon which Grindstone Sync Server is listening.

Management API token

This setting is only used by Grindstone Sync Server installations operating in the Cloud mode. It will have no effect for your Grindstone Sync Server installation.

Licenses

Grindstone Sync Server operates using licenses available for purchase via the Epiforge website. Licenses incorporate the following details:

Grindstone Sync Server automatically applies any changes you make on the License tab immediately, so you do not need to shutdown or restart its Windows Service when managing your licenses.