<commit_before>The rest of this will probably be refactored

# Running the Gaia Hub

To get started running a gaia hub, execute the following:

```bash
$ git clone https://github.com/blockstack/gaia.git
$ cd gaia/hub/
$ npm install
$ npm run build
$ cp ./config.sample.json ./config.json
# Edit the config file and add in your azure or aws credentials
$ npm run start
```

## Note on SSL

We *strongly* recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. 

Configuration options are available to run the hub with an `https` Node.js server. 
Otherwise, a reverse proxy web server such as nginx or Apache can be used. 

## Configuring the hub

### Driver Selection

The Gaia hub currently supports the following drivers:

```
'aws' == Amazon S3
'azure' == Azure Blob Storage
'disk' == Local disk (you must set up static web-hosting to point at this driver)
'google-cloud' === Google Cloud Storage
```

Set the driver you wish to use in your `config.json` file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to.

These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`).

*Note:* The disk driver requires a *nix like filesystem interface, and will not work correctly when trying to run in a Windows environment.

### Require Correct Hub URL

If you turn on the `requireCorrectHubUrl` option in your `config.json`
file, your Gaia hub will require that authentication requests
correctly include the `hubURL` they are trying to connect with. This
is used to prevent a malicious gaia hub from using an authentication
token for itself on other Gaia hubs.

By default, the Gaia hub will validate that the supplied URL matches
`https://${config.serverName}`, but if there are multiple valid URLs
for clients to reach the hub at, you can include a list in your `config.json`:

```javascript
{
  ....
  serverName: "normalserver.com"
  validHubUrls: [ "https://specialserver.com/",
                  "https://legacyurl.info" ]
  ....
}
```<commit_msg>add CORS config section to hub readme<commit_after>The rest of this will probably be refactored

# Running the Gaia Hub

To get started running a gaia hub, execute the following:

```bash
$ git clone https://github.com/blockstack/gaia.git
$ cd gaia/hub/
$ npm install
$ npm run build
$ cp ./config.sample.json ./config.json
# Edit the config file and add in your azure or aws credentials
$ npm run start
```

## Note on SSL

We *strongly* recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. 

Configuration options are available to run the hub with an `https` Node.js server. 
Otherwise, a reverse proxy web server such as nginx or Apache can be used. 

## Configuring the hub

### Driver Selection

The Gaia hub currently supports the following drivers:

```
'aws' == Amazon S3
'azure' == Azure Blob Storage
'disk' == Local disk (you must set up static web-hosting to point at this driver)
'google-cloud' === Google Cloud Storage
```

Set the driver you wish to use in your `config.json` file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to.

These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`).

*Note:* The disk driver requires a *nix like filesystem interface, and will not work correctly when trying to run in a Windows environment.

### CORS Configuration

In order for a Gaia hub to operate properly CORS must be configured.

For the **write endpoint**, you must configure your server to include the following headers:
- `Access-Control-Allow-Origin: *`
- `Access-Control-Allow-Methods: GET, POST, OPTIONS, DELETE`
- `Access-Control-Allow-Headers: Authorization, If-Match`


For the **read endpoint**, you must configure your storage driver to include the following headers:
- `Access-Control-Allow-Methods: GET`
- `Access-Control-Allow-Origin: *`
- `Access-Control-Expose-Headers: ETag`

Here's an example of a storage driver (S3) configuration:

```xml
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <CORSRule>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedOrigin>*</AllowedOrigin>
    <ExposeHeader>ETag</ExposeHeader>
    <MaxAgeSeconds>0</MaxAgeSeconds>
  </CORSRule>
</CORSConfiguration>
```

### Require Correct Hub URL

If you turn on the `requireCorrectHubUrl` option in your `config.json`
file, your Gaia hub will require that authentication requests
correctly include the `hubURL` they are trying to connect with. This
is used to prevent a malicious gaia hub from using an authentication
token for itself on other Gaia hubs.

By default, the Gaia hub will validate that the supplied URL matches
`https://${config.serverName}`, but if there are multiple valid URLs
for clients to reach the hub at, you can include a list in your `config.json`:

```javascript
{
  ....
  serverName: "normalserver.com"
  validHubUrls: [ "https://specialserver.com/",
                  "https://legacyurl.info" ]
  ....
}
```
{'fraction_non_alphanumeric': 0.08154435014145449, 'fraction_numerical': 0.002163421534365119, 'mean_word_length': 4.181034482758621, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1011910', 'n_tokens_mistral': 1646, 'n_tokens_neox': 1587, 'n_words': 820}