From d7c976e6cfe4766cea4fb0d962797d34fbb35f01 Mon Sep 17 00:00:00 2001 From: Patrick Gray Date: Tue, 4 May 2021 16:07:10 -0400 Subject: [PATCH] Updated doc on Gaia --- .../cloudformation-launch-stack-button.png | Bin 0 -> 2296 bytes src/pages/storage-hubs/amazon-ec2-deploy.md | 564 +----------------- src/pages/storage-hubs/overview.md | 88 ++- 3 files changed, 46 insertions(+), 606 deletions(-) create mode 100644 public/images/cloudformation-launch-stack-button.png diff --git a/public/images/cloudformation-launch-stack-button.png b/public/images/cloudformation-launch-stack-button.png new file mode 100644 index 0000000000000000000000000000000000000000..175c2f7b2fbde151fe4ccd20f05e5a5597fc5b75 GIT binary patch literal 2296 zcmVfFDZ*Bk+2_Yi@000VfMObu0Z*X~XX=iA30IUzpIsgCw4s=CWbVG7w zVRUJ4ZXk4NZDjy8_YVmG000SeMObuGZ)S9NVRB^vU2y+80000BbVXQnL}_zlY+-3_ zWpV(wz_gD5000PdMObuKVRCM1Zf5|%8|H@q000McMObuGZ*_8GWdQa6gX;hQ00?wN zSad^gZEa<4bO83umcIZ100wkLSaeirbZlh+sP57y000NWNkl+h$ zNLEe25;PSRgCZC*KB!2AqN0n7+UitS&|PiU$2!xlj&7|}$KAT_cGYUts&%bem+A`E zS6dKUl#zB_AGEGfaH9bq7+!)Y1T`QK46=U&Xas^yxxwn(&kTR$oO^!X-?{nD`JH?2 zkZ0=Z>go^?aS;-L+`Iy|e!Pp^yn@G_kH}MiMjc4Zl!<86fi{EfPB=j9lt~O5I^=QZ zCh`<;IqM2rckJS$O>1y#Xb{aMA`}{RASIH6R@%iDenzgTAy@Eczy;$<6zmb<;=&)bp=|nJtX)`Vg73zuQdU^_a6DZUZ zc+vlHXVa7%&K$XdiDwC#7)E=gCz!z+aI_+=U%di=jazn*epZW{n;Q=vJa8&@+LpIC zkPVtC8~Ecd1xZ&>uAWLHUI#;F{2UE-of8KV$wbZUb~ISK?!g+&C6~+S-rd{j@imoZ z?%XwVuf_$*{p?6()y#Rsyp_QJ9(O8jK=2jJ5%%U$d zF(4$E0EM)^vjU@`luA0$%}>(jc`8iyfBbzFNSmc{jq}=Tm^}iC2k{xshq4 z2;f0AcMQ20I(y@%l+|k&W4NKGsJtWIfzLBEps9WZM#EL~d7x4U)Q@XPx_}~cE!f=? zp=lR`H8ofNets@c`G$3G?Bl=otJ^*q5wq5?C{hZX;h)Ptvz3U1#Y_NB?q0<%9XuDc zkS((Y!l}Kyy*CT5zW#J9ypFLU*5_yW{dB!{C&G1U*Iu(Iv*_ z3GHAoN9JnSlL?0hnz1t(J-iPJpz_>)Rwn20o%R%qBBPv&RCc=~G4tMJn7f`&wxyC? znN8*eh#qSqWzVO4U3i}^eZ!eD{ssDR69b(d4xkKW{@h^PFYo8WrKK#Co^m7@Df%v%c@nRk8LdF$a~|ffNW!Ze7z2x5%|SGVwc1+8UR%j)haSJ#gSQTrOUvnES)vD zS$P){ml^DaA+J?)z4Pu`^70E~anyjhrAb;J*o@}s(YzctQplw& zE1)1ODiYVNT{c|y6xr9W4~rMR?r`O*uCAuK+Cp`;MG!qx%25)pRnX;y*VvV?lS6Nh z;yFPg+tUGw1fY~+K_2aT5HV{hA8%X3JF#lKYDzhM^xxhD zY@KaOT~mIWJcAyi_6B!b9G%PAf2Ck`&*wyrv&tg~4NgXTu7tF>budChH_9-{BbXhn za(W*6BfI$4qNHa}72Z;J-0eHNdf*A%HR(9IF9luK?#xiv*d82e?qSNy{&Sc+d7P#U0(5MhXhRTpoh5mRV`%ab-5ai>evXs%U z&t-Cd8JMneEGd!rq;#@wSN*h!+{@>iq(tJjZe(rzMQ*wK@bZjb69fVG9Crlw}#xr$wb#*Z_=W!@uXPW{!de`_UgnbuTf7aD_X4Dkh8Il<} zJ}sPGIVWYrP*Q`3Pj3`$31l&mUsO)5qq8WB3DbQA3cC*5gG}pZSGF@QcbA=SJ&FcT z305LQf(JWouz>#k1b)#iL+RJr?UbVMRkgAKc1B7`t5QD}sRCcWRx*+*ni*K8R6Wu( zQbliC3)@}@X0YiouP{C46`{h3JS9AldoYnF2hm_6E=4q$h)WR-CgM^=gNe8lH-K*5 z3h{R-L This documentation is appropriate for advanced power users who are familiar with command line tools, `ssh`, and basic editing configuration files. +| Template name | Description | Launch | +| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------- | +| Gaia Hub EC2 (us-west-2) | Deploys a Gaia hub service on EC2 with an S3 storage provider | [![](/images/cloudformation-launch-stack-button.png)][ec2-us-west-2] | --> If you are planning on running an _open-membership hub_ or an _application-specific hub_, see [the Hub Overview](/storage-hubs/overview). - -## Prerequisites you need - -This procedure uses Amazon AWS to choose and configure an Amazon Machine Image -(AMI) running a Gaia service. For this reason, you should have an AWS account -on the [Amazon AWS free tier](https://aws.amazon.com/free/), personal account, -or corporate account. These instructions assume you are using a free tier account. - -These instructions assume you have already created a free [domain through the freenom service](https://www.freenom.com). -If you have another domain, you can use that instead. - -Finally, setting up the SSL certificates on your EC2 instance requires you to use the terminal -command line on your workstation. Make sure you have the `watch` command installed using the `which` command. - -```bash -which watch -``` - -```bash -/usr/local/bin/watch -``` - -If `watch` is not located, install it on your workstation. - -## Task 1: Launch an EC2 instance - -1. Visit the [AWS Free Tier page](https://aws.amazon.com/free/) and choose **Sign in to the Console**. - - ![](/images/aws-console.png) - -2. Make sure your region is set to one close to you. - - ![](/images/us-west-2.png) - -3. Under **Build a solution** choose **Launch a virtual machine**. - - The system opens the EC2 dashboard. - -4. Enter `blockstack-gaia` in the search bar. - - The system finds AMIs in the Marketplace and the Community. - -5. Choose **Community AMIs**. - - The system displays the available Gaia hub images. - - ![](/images/gaia-community.png) - - Each image name has this format: - - `blockstack-gaia_hub-STORAGETYPE-VERSION-hvm - ami-BUILDTAG` - - You can choose an image that uses **ephemeral** or **EBS** storage. The ephemeral - storage is very small but free. Only choose this if you plan to test or use - a personal hub. Otherwise, choose the AMI for elastic block storage (EBS) which provides a persistent data store on - a separate disk backed by [EBS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html). - - So, the `blockstack-gaia_hub-ephemeral-2.5.3-hvm - ami-0c8fc48c10a42737e` image uses ephemeral storage, is at - version `2.5.3` and has the `0c8fc48c10a42737e` tag. - -6. Select the most recent version image with the storage you want. The images are not sorted; The most recent images - is not necessarily at the top of the list. - - After you select an image, the system displays **Step 2: Choose an Instance Type** page. - - ![](/images/tier-2-image.png) - -7. Select **t2.micro** and choose **Next: Configure Instance Details**. - - To configure instance details, do the following: - -
-
    -
  1. -

    Select a VPC.

    -

    A default VPC is created with a free tier account. You can use this - default VPC. Or you can choose another VPC. If you choose another VPC, - ensure the Subnet value is set to a subnet reachable by a public IP. -

    -
    Important: If you're using a private subnet, you - should attach an elastic IP (EIP) to the VM. This EIP allows you to - reboot the instance without worrying whether the address will reset. To - attach an IP, press allocate new address and follow the - instructions to attach the EIP to your new EC2 instance. -
    -
    2. -
  2. -

    Set Protect against accidental termination.

    -

    If you terminate a Gaia instance, you lose all the data associated with it. Protection adds an extra step to terminating your Gaia instance.

    -
    3. -
  3. -

    Open the Advanced Details.

    -

    At this point, you are going to configure environment variables for your instance.

    -
    4. -
  4. -

    Paste the following into the Advanced Details.

    - - 
    
-          {
-             "ignition": { "version": "2.2.0" },
-             "storage": {
-                "files": [{
-                "filesystem": "root",
-                "path": "/etc/environment",
-                "mode": 420,
-                "contents": {
-                   "source": "data:application/octet-stream,API_KEY%3DKEYPHRASE%0ADOMAIN%3DNAME_OF_DOMAIN%0ASTAGING%3DSTAGING_VALUE"
-                }
-                }]
-             }
-          }
-
    - -
    5. -
  5. -

    Replace the following values in the JSON.

    - - - - - - - - - - - - - - - - - - - -
    ValueDescription
    <KEYPHRASE>A phrase to pass when using the hub admin. For example, hubba is a fun key phrase.
    <NAME_OF_DOMAIN>Your hub's domain name. For example, maryhub.ml is the domain name in this example.
    <STAGING_VALUE> -

    Indicates what type of SSL to create, testing (`1`) or production (`0`). Set testing if you want to test without worrying about rate limiting. A testing cerificate is not secure.

    -

    For this tutorial, use production (`0`).

    -
    -
    6. -
  6. -

    Check your Advanced Details they should look similar to the following:

    - - 
      {
-             "ignition": { "version": "2.2.0" },
-             "storage": {
-                "files": [{
-                "filesystem": "root",
-                "path": "/etc/environment",
-                "mode": 420,
-                "contents": {
-                   "source": "data:application/octet-stream,API_KEY%3Dhubba%0ADOMAIN%3Dmaryhub.ml%0ASTAGING%3D0"
-                }
-                }]
-             }
-          }
-
    - -
    7. -
-
- - At this point, you have configured your instance details. - -8. Choose **Next: Add Storage**. - - ![](/images/add-storage.png) - - The storage is set according to the AMI you selected. - -9. Choose **Next: Add tags**. -10. Optionally, add the following tags: - - The tags are not required, they just apply searchable labels to an instance on an EC2 console. - - - **Key** of `Purpose` with the **Value** `gaia` - - **Key** of `Name` with the **Value** `gaia-hub` - - **Key** of `Version` with the **Value** `2.5.3` (This value is an example, your version may be different.) - - ![](/images/tag-add.png) - -11) Choose **Next: Configure Security Group**. -12) Create a security group with the following three types: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeProtocolPort RangeSourceDescription
SSHTCP22My IPoptional
HTTPTCP80Anywhereoptional
HTTPSTCP443Anywhereoptional
- -13) Choose **Review and Launch**. - - The system may warn you that the selection is not free tier eligible. You can ignore this for now. - -14) Press **Launch**. - - The system prompts you for a key pair. - -15) Select **Create a new keypair** or **Choose an existing key pair**. -16) Select **Launch Instances**. - - The system launches your instance. - - ![](/images/aws-launch-status.png) - -During the launch process the machine starts and runs some initial setup processes. These processes take a few minutes depending on the network, typically launching does not take more than 10 minutes. While this is happening the instance **Status Checks** reflect the **Initializing** status. - -![](/images/instance-initialize.png) - -## Task 2: Connect your Gaia server to your domain - -Now, you are ready to test your Gaia server. This procedure ensures the Gaia services started correctly and they are configured to the domain name you provided in **Advanced Details** above. - -1. Visit the AWS Free Tier page and choose **Sign in to the Console**. - - ![](/images/aws-console.png) - -2. Choose **All services > EC2**. - - The system displays the **EC2 Dashboard**. - - ![](/images/ec2-dashboard.png) - -3. Select **Running Instances**. - - The system displays your running instances. - -4. Locate your recently launched Gaia server. - - Make sure the instance shows as running and **Status Checks** are complete. - Completed status checks ensures the Gaia processes and service were started. - -5. Select the **Description** tab. - - ![](/images/ec2-instance.png) - -6. Locate the **IPv4 Public IP** value. - - The public IP must match the DNS configured for the domain you entered in **Advanced Details** in the previous procedure. - -7. Copy the IP and paste it in your browser. - - - - - - - - - - - - - - -
If the response isDo this...
You should see a message that your connection is not private. -Everything is fine, continue to the next step, step 8.
-
    -
  1. Check that your domain's DNS configuration matches the public IP address of your instance.
    2. -
  2. Update the DNS site's configuration.
    3. -
  3. Restart your EC2 instance as per the Restart and reload certificates procedure on this page.
    4. -
  4. Continue with next step, step 8.
    5. -
-
- -8) Press **Advanced**. -9) Choose to proceed. -10) Extend the IP with the `PUBLIC_IP/hub_info` tag like so. - - You should see a response from your Gaia hub. - - ![Hub test](/images/aws-hub.png) - - At this point, you should see a **Not secure** message in the browser. - That's because you haven't yet enabled SSL certification. While `HTTPS` is - not required simple to run the hub services, Blockstack will only connect to - a hub and write to its storage over a valid `HTTPS` connection. - -## Task 3: Configure a domain name - -At this point, you can point a domain to your Gaia hub. Although it's not required, it is highly recommended. If you use a domain, you can migrate your instance to a different server (or even provider such as Azure or Dropbox) at any time, and still access it through the domain URL. Just point your domain at the IP address for your EC2 instance. Use an `A Record` DNS type. - -These instructions assume you have already created a free domain through the freenom service. To point this freenom domain to your Gaia hub, do the following: - -1. Log into your freenom account. -2. Choose the **Manage Freenom Domain** tab. -3. Add an **A** record leave the **Name** field blank. - - This points your entire domain to the hub IP. - -4. Save your changes. - -5. Create a CNAME record. - - For example, you can use the prefix `www` with your domain name. When you are done, your - -6. Save your changes. - - At this point, your DNS management should look similar to the following except that with your domain rather than the `maryhub.ga` domain. - - ![DNS fields](/images/aws-dns-fields.png) - -7. After your changes propagate, visit your new domain at the `hub_info` page. - - ![Domain test](/images/domain-test.png) - - If you receive another **Your connection is not private** dialogs, take the option to proceed to your domain. The _Not secure_ message should no longer appear in the browser bar. If the message does appear, try waiting a few minutes for your recent changes to propagate across the net domain servers. Then, refresh the page. - -8. Check the SSL certificate for your hub. - - Each browser has its own check procedure, for example, Chrome: - - ![](/images/cert-check.png) - -At this point, you have the following. An EC2 instance running Gaia and a DNS -record pointing your domain to this instance. - -## AWS hub tips and tricks - -Once your Gaia storage hub is up and running on AWS, you may occassionally need to troubleshoot. This section contains some useful information for interacting with your EC2 instance. - -### SSH into the Host - -To SSH to the EC2 host directly: - -```bash -ssh -t -i core@ -``` - -### Displaying the docker services - -Your EC2 instance is running several `docker` services that support the Gaia hub. You can list these services using the `docker ps` command. - -```bash -docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.Names}}" -``` - -```bash -CONTAINER ID IMAGE COMMAND NAMES -6b170ce9b0d6 nginx:alpine "nginx -g 'daemon of…" nginx -91c5ff651586 quay.io/blockstack/gaia-hub:v2.5.3 "docker-entrypoint.s…" gaia-hub -16b229a20320 quay.io/blockstack/gaia-reader:v2.5.3 "node lib/index.js" gaia-reader -89739e338573 quay.io/blockstack/gaia-admin:v2.5.3 "docker-entrypoint.s…" gaia-admin -``` - -Each service plays a particular role in running your Gaia hub. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ServiceDescription
certbotThis service runs every 12 hours so you may not see it in the output. The service runs Let's Encrypt certbot client to support SSL. Certbot renews your certificates and reloads Nginx to pick up the changes. This service will run 2x per day checking if the certificate needs to be renewed.
nginxRuns an Nginx proxy in front of the Gaia Hub. This service does things like rate-limiting, SSL termination, and redirects to HTTPS. Your nginx service relies on your hub's readURL to make requests. Changes to a hub's readURL must be reflected in the nginx service configuration in /gaia/nginx/conf.d/default.conf
gaia-adminA simple administrative service that allows you to administer the Gaia hub. Use REST calls with this service to get and set hub configuration values.
gaia-readerThe Gaia read side-car services get file requests on URLs that start with - your Gaia hub's readURL. You can determine your Gaia hub's read URL by either - looking for the readURL key in your Gaia hub's config file. This value is or by looking for - the read_url_prefix field in the data returned by a HUB_URL/hub_info page on your - Gaia hub.
gaia-hubThe Gaia hub service.
- -### Locations of key files - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
File or DirectoryDescription
/etc/systemd/systemContains systemd unit-files for managing your Gaia hub.
/etc/environmentContains the DOMAIN and STAGING variables you entered when creating your EC2 instance. -
/gaia/gaia.envContains the environment variables used by the Gaia systemd unit-files. -
/etc/systemd/system/reset-ssl-certs.serviceA service that removes all existing certificates and restarts all the Gaia hub services. Use this sparingly, since the Lets Encrypt service will throttle too many requests for certificates.
/gaia/hub-configConfiguration for the Gaia Hub service.
/gaia/admin-configConfiguration for the Gaia Hub admin service.
/gaia/reader-configConfiguration for the Gaia Hub reader service.
/gaia/nginx/conf.dConfiguration files for the Nginx service.
/gaia/nginx/certbot/confLets Encrypt SSL certificates/configs.
/gaia/scriptsScripts run by the systemd services on startup.
- -You can `cat` the various services to see what settings they are using. - -```bash -cat /etc/systemd/system/reset-ssl-certs.service -``` - -```yaml -# reset-ssl-certs.service -[Unit] -Description=Reset Gaia to first boot -ConditionFileIsExecutable=/gaia/scripts/reset-certs.sh - -[Service] -Type=oneshot -RemainAfterExit=no -EnvironmentFile=/gaia/gaia.env -EnvironmentFile=/etc/environment -ExecStart=/bin/bash /gaia/scripts/reset-certs.sh - -[Install] -WantedBy=multi-user.target -``` - -### Restart services and reload certificates - -This procedures requires you to interact from a workstation command line with your running EC2 instance. - -1. Open a terminal on your local workstation. -2. Confirm the hub DNS is set correctly with the following command: - - ```bash - watch -n 2 -t -g -x host - ``` - - Substitute your domain name for the `` variable. For example: - - ```bash - watch -n 2 -t -g -x host maryhub.ga - maryhub.ml has address 34.219.71.143 - ``` - - If the command returns the correct IP, the same as appears on your EC2 dashboard, stop the process with a`CTRL-C` on your keyboard. - -3. Change the permissions on your downloaded `.pem` file. - - For example, this - - ``` - chmod 400 - ``` - -4. SSH from your workstation and restart Gaia Hub: - - This process requires that you know the location of the `.pem` file you downloaded when you created the keypair. - - ``` - ssh -t -i -A core@ "sudo systemctl restart gaia.service" - ``` - - For example: - - ``` - ssh -t -i /Users/manthony/gaia.pem -A core@34.219.71.143 "sudo systemctl restart gaia.service" - Connection to 34.219.71.143 closed. - ``` - - This will restart all services required for running a Gaia Hub (nginx, hub, reader, admin, certbot) - -5. SSH from your workstation to reset back to first boot: - - \*\* This process will stop Gaia Hub, Nginx and remove any existing SSL certificates. It will then start the process of retrieving certificates and setting up the services again. This will not affect any existing data stored on the server. - - This process requires that you know the location of the `.pem` file you downloaded when you created the keypair. - - ``` - ssh -t -i -A core@ "sudo systemctl restart reset-ssl-certs.service" - ``` - - For example: - - ``` - ssh -t -i /Users/manthony/gaia.pem -A core@34.219.71.143 "sudo systemctl restart reset-ssl-certs.service" - Connection to 34.219.71.143 closed. - ``` - - After a few minutes, all Gaia Hub services will restart automatically and will retrieve a new SSL certificate. +[ec2-us-west-2]: https://console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/new?stackName=Gaia&templateURL=https://cf-templates-18jq0t04gve7c-us-west-2.s3-us-west-2.amazonaws.com/2021124ByT-cf.yaml diff --git a/src/pages/storage-hubs/overview.md b/src/pages/storage-hubs/overview.md index b563152a..dce0235c 100644 --- a/src/pages/storage-hubs/overview.md +++ b/src/pages/storage-hubs/overview.md @@ -2,9 +2,23 @@ title: Storage hubs overview --- -## Configuration files +## Introduction -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: +The Gaia storage system allows you to store private application data off the blockchain and still access it securely +with Stacks applications. Where possible, applications should only store critical transactional metadata directly to +the Stacks blockchain, while keeping application and user data in the Gaia storage system. For more information about +the Gaia storage system, see the [Gaia protocol reference](/build-apps/references/gaia). + +A [Gaia hub](/build-apps/references/gaia#user-control-or-how-is-gaia-decentralized) consists of a service and a storage +resource, generally hosted on the same cloud compute provider. The hub service requires an authentication token from a +storage requestor, and writes key-value pairs to the associated storage resource. Storage requestors can choose a Gaia +hub provider. This documentation provides an overview of how to set up and operate a Gaia hub. + +## Creating a configuration file + +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 { @@ -29,62 +43,34 @@ You should store a JSON configuration file either in the top-level directory of } ``` -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. +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 +### Requiring 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. +Enabling the `requireCorrectHubUrl` option in your `config.json` file, requires that authentication requests correctly +include the `hubURL` for the hub the request is 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`: +By default, the Gaia hub validates 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`: -```jsx +```json { - .... - servername: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... + ... + "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 +### Configuring read URLs -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. +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 to read files from a given URL. For example, the configuration of the +`hub.blockstack.org` Gaia Hub results in a read URL that looks like `https://gaia.blockstack.org/hub/`. -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. +Unset the `readURL` parameter if you don't intend to deploy any caching.