mirror of https://github.com/lukechilds/docs.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
103 lines
4.0 KiB
103 lines
4.0 KiB
6 years ago
|
---
|
||
|
|
layout: storage
|
||
|
|
permalink: /:collection/:path.html
|
||
|
|
---
|
||
|
|
# Understand hub operation
|
||
|
|
{:.no_toc}
|
||
|
|
|
||
|
|
This page describes the considerations hub operators must take into account when creating and operating a Gaia storage hub.
|
||
|
|
|
||
|
|
* TOC
|
||
|
|
{:toc}
|
||
|
|
|
||
|
|
|
||
|
|
## Configuration files
|
||
|
|
|
||
|
|
You should store a JSON configuration file either in the top-level directory of
|
||
|
|
the hub server. Alternatively, you can specify a file location using the
|
||
|
|
`CONFIG_PATH` environment variable. The following is an example configuration file for Amazon S3:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"servername": "localhost",
|
||
|
|
"port": 4000,
|
||
|
|
"driver": "aws",
|
||
|
|
"readURL": "https://YOUR_BUCKET_NAME.s3.amazonaws.com/",
|
||
|
|
"pageSize": 20,
|
||
|
|
"bucket": "YOUR_BUCKET_NAME",
|
||
|
|
"awsCredentials": {
|
||
|
|
"accessKeyID": "YOUR_ACCESS_KEY",
|
||
|
|
"secretAccessKey": "YOUR_SECRET_KEY"
|
||
|
|
},
|
||
|
|
"argsTransport": {
|
||
|
|
"level": "debug",
|
||
|
|
"handleExceptions": true,
|
||
|
|
"stringify": true,
|
||
|
|
"timestamp": true,
|
||
|
|
"colorize": false,
|
||
|
|
"json": true
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
You can specify the logging level, the backend driver, the credentials
|
||
|
|
for that backend driver, and the `readURL` of the hub. Typically, this is the URL for the compute resource on the cloud computing provider — where the hub service is running.
|
||
|
|
|
||
|
|
### Require the correct hub URL
|
||
|
|
|
||
|
|
If you enable 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. Use this option 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" ]
|
||
|
|
....
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### The readURL parameter
|
||
|
|
|
||
|
|
By default, hub drivers return read URLs that point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. If you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the hub that files can be read from a given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`.
|
||
|
|
|
||
|
|
Unset the `readURL` parameter if you do not intend to deploy any caching.
|
||
|
|
|
||
|
|
### The proofsRequired parameter (Deprecated)
|
||
|
|
|
||
|
|
Past users could configure this setting as a crude spam-control mechanism.
|
||
|
|
However, for the smoothest operation of your Gaia hub, set the
|
||
|
|
`proofsConfig.proofsRequired` value to `0`.
|
||
|
|
|
||
|
|
|
||
|
|
## Open or private hubs
|
||
|
|
|
||
|
|
You can configure an open-membership storage hub or a private storage hub. An open-membership hub, as it sounds, allows any user to use the hub service. A private hub limits the use of the service. In this section, you learn about configuring each type.
|
||
|
|
|
||
|
|
### Open-membership hub
|
||
|
|
|
||
|
|
An open-membership storage hub permits writes for _any_ address top-level
|
||
|
|
directory. Every request is validated such that write requests must provide
|
||
|
|
valid authentication tokens for that address. Operating in this mode is
|
||
|
|
recommended for service and identity providers who wish to support many
|
||
|
|
different users.
|
||
|
|
|
||
|
|
### Private-user hub
|
||
|
|
|
||
|
|
A private-user hub receives requests for a single user. Requests are controlled
|
||
|
|
via _whitelisting_ the addresses allowed to write files. Recall that each application uses a different app- and user-specific address. It follows, to
|
||
|
|
support application storage, your configuration must add to the whitelist each application you wish to use.
|
||
|
|
|
||
|
|
Alternatively, the user's client can use the authentication scheme and generate
|
||
|
|
an association token for each app. The user should whitelist her address, and
|
||
|
|
use her associated private key to sign each app's association token. This
|
||
|
|
removes the need to whitelist each application, but with the caveat that the
|
||
|
|
user needs to take care that her association tokens do not get misused.
|