# Grindstone Sync Server Installation Guide

- [Grindstone Sync Server Installation Guide](#grindstone-sync-server-installation-guide)
- [Download](#download)
- [Requirements](#requirements)
  - [Hardware](#hardware)
  - [Software](#software)
  - [Latest Tested Versions](#latest-tested-versions)
- [Installing and Configuring Grindstone Sync Server](#installing-and-configuring-grindstone-sync-server)
  - [Setup Service Files](#setup-service-files)
  - [Configure Grindstone Sync Server Web Services](#configure-grindstone-sync-server-web-services)
  - [Configure Windows](#configure-windows)
  - [Configure SQL Server](#configure-sql-server)
  - [Test the Windows Service](#test-the-windows-service)
  - [Register Your Grindstone Sync Server Installation](#register-your-grindstone-sync-server-installation)
  - [Purchase a Grindstone Sync Server License](#purchase-a-grindstone-sync-server-license)
  - [Create the first Grindstone Sync Administrator](#create-the-first-grindstone-sync-administrator)
- [Reference](#reference)
  - [Installation Assistant](#installation-assistant)
  - [Settings](#settings)
    - [Auditing](#auditing)
      - [Logging Level](#logging-level)
    - [Backing Store](#backing-store)
      - [Provider](#provider)
      - [Hostname or IP address](#hostname-or-ip-address)
      - [Database](#database)
      - [Authentication](#authentication)
      - [Use SQL Azure execution strategy](#use-sql-azure-execution-strategy)
    - [Processing](#processing)
      - [Mode](#mode)
      - [Await committing paired client last sync](#await-committing-paired-client-last-sync)
      - [Await committing paired client pending change set](#await-committing-paired-client-pending-change-set)
    - [Resources](#resources)
      - [Idle team memory time to live](#idle-team-memory-time-to-live)
    - [Security](#security)
      - [Client request access threshold](#client-request-access-threshold)
      - [Client request access window](#client-request-access-window)
      - [HTTP include error detail policy](#http-include-error-detail-policy)
    - [Support](#support)
      - [Automatically report errors to Epiforge](#automatically-report-errors-to-epiforge)
    - [Web Service](#web-service)
      - [IP address](#ip-address)
      - [Port](#port)
      - [Use SSL](#use-ssl)
      - [Management API token](#management-api-token)
  - [Licenses](#licenses)

# Download
The ZIP archive from which this Installation Guide file originated contains the following files:
- **GSS.exe**: executible binary for Grindstone Sync Server
- **GSS.exe.config**: application-level .NET Framework configuration file for Grindstone Sync Server
- **GSS.pdb**: program debug database for Grindstone Sync Server, enhancing the detail of error reporting
- **Installation Assistant.ps1**: PowerShell script that helps you install Grindstone Sync Server as a Windows Service and configure Windows to allow it to work
- **Installation Guide&period;md**: the markdown version of this document
- **Installation Guide&period;html**: the HTML version of this document
- **Run Installation Assistant.lnk**: starts the Installation Assistant with appropriate admin privileges and execution policy

# Requirements

## Hardware
&nbsp;                        | 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
&nbsp;                       | 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][1]                        | [Standard Server][2]
Microsoft .NET Framework     | [4.6.2][3]                               | [Latest][4]
Microsoft SQL Server Version | [2008][5]                                | [2017][6]
Microsoft SQL Server Edition | [Express][7]                             | [Standard][7]

[1]: https://www.microsoft.com/en-us/p/windows-10-pro/df77x4d43rkt/48DN
[2]: https://www.microsoft.com/en-us/cloud-platform/windows-server-pricing
[3]: https://www.microsoft.com/en-us/download/details.aspx?id=53345
[4]: https://dotnet.microsoft.com/download
[5]: https://www.microsoft.com/en-us/sql-server/sql-server-2008
[6]: https://www.microsoft.com/en-us/sql-server/sql-server-2017
[7]: https://www.microsoft.com/en-us/sql-server/sql-server-2017-editions

## Latest Tested Versions
&nbsp; | Version
-|-
Processor Register Width | 64 bits (AMD64)
Microsoft Windows Version | NT 10.0 (Windows 10 / Windows Server 2016)
Microsoft .NET Framework | [4.7.2][8]
Microsoft SQL Server Version | 2017

[8]: http://go.microsoft.com/fwlink/?LinkId=863262

# 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](https://www.epiforge.com/support/speakWithASpecialist) 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](https://www.epiforge.com/support/manuals/grindstone4ForWindows#connecting-to-grindstone-sync)).
Much [like a baby velociraptor](https://youtu.be/JhpmzQ2lgkM), 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](https://www.epiforge.com/support/manuals/grindstone4ForWindows#managing-people)).

# Reference

## Installation Assistant
Open the **Run Installation Assistant** short-cut in order to easily complete the following tasks:
- create or remove the service account
- install or uninstall the Windows service
- register or unregister the URL with Windows
- add or remove an SSL server certificate

## 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:
- **Quiet**: nothing will be logged except acknowledgement of service control messages (e.g. start and stop)
- **Minimal**: errors will be logged in addition to all entries logged by **Quiet**
- **Normal**: typically useful warnings and informative messages will be logged in addition to all entries logged by **Minimal**
- **Detailed**: all warnings and informative messages will be logged in addition to all entries logged by **Normal**
- **Diagnostic**: technical details regarding internal service state, web service requests, and database queries will be logged in addition to all entries logged by **Detailed**

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:
- **Trusted Connection**: the credentials of the service account under which the Grindstone Sync Server process is running will be used
- **Login and Password**: credentials specified by you in the **Login** and **Password** textboxes will be used

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:
- **SQL Azure execution strategy max retry count**: how many times to retry a database query when it fails due to maintenance
- **SQL Azure execution strategy max delay**: how long to delay between retries of database queries when a query fails due to maintenance

### Processing

#### Mode
This setting determines the operating mode of Grindstone Sync Server:
- **Server**: this server is being used by an organization to privately host their own team of individuals using Grindstone Sync
- **Cloud**: this server is a node supporting Epiforge's Grindstone Sync Cloud offering

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:
- **Default**: same as **LocalOnly**
- **LocalOnly**: error details will be provided so long as the client's request originated from the same machine on which Grindstone Sync Server is running
- **Always**: error details will always be provided
- **Never** error details will never be provided

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](https://www.epiforge.com/support/speakWithASpecialist) 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](https://www.epiforge.com/support/speakWithASpecialist) 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:
- your server's Epiforge device signature, which is a non-reversible hash based on certain characteristics of the hardware and operating system that change very rarely, if ever
- the IP address upon which your installation of Grindstone Sync Server listens for incoming connections
- the port upon which your installation of Grindstone Sync Server listens for incoming connections
- the mode under which your Grindstone Sync Server is running
- the number of people simultaneously connected to your Grindstone Sync Server that the license permits
- the date on which your license takes effect
- the date on which your license expires

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.