This teaches you how to run a Gaia hub on Amazon EC2. Amazon EC2 is an affordable and convenient cloud computing provider. This example uses Amazon EC2 instance together with an [EBS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html) disk for file storage.
<p>This documentation is appropriate for advanced power users who are familiar with command line tools, <code>ssh</code>, and basic editing configuration files.</p>
<p>If you are planning on running an <em>open-membership hub</em> or an <em>application-specific hub</em>, see <ahref="hub-operation.html">the section on Hub Operation</a>.</p>
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 <ahref="https://aws.amazon.com/free/"target="\_blank">Amazon AWS free
tier</a>, personal account, or corporate account. These instructions assume you
are using a free tier account.
These instructions assume you have already created a free <a
href="https://www.freenom.com" target="\_blank">domain through the freenom
service</a>. 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.
```
$ which watch
/usr/local/bin/watch
```
If `watch` is not located, install it on your workstation.
## Task 1: Launch an EC2 instance
1. Visit the <ahref="https://aws.amazon.com/free/"target="\_blank">AWS Free Tier page</a> and choose **Sign in to the Console**.
2. Make sure your region is set to one close to you.
3. Under **Build a solution** choose **Launch a virtual machine**.
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.
<p>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 <codeclass="highlighter-rouge">Subnet</code> value is set to a subnet reachable by a public IP.
</p>
<divclass="uk-alert-warning uk-alert"uk-alert=""><b>Important:</b> 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, <strong>press allocate new address</strong> and follow the
instructions to <ahref="https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html#using-instance-addressing-eips-associating"target="_blank">attach the EIP</a> to your new EC2 instance.
</div>
</li>
<li>
<p>Set <strong>Protect against accidental termination</strong>.</p>
<p>If you terminate a Gaia instance, you lose all the data associated with it. Protection adds an extra step to terminating your Gaia instance.</p>
</li>
<li>
<p>Open the <strong>Advanced Details</strong>.</p>
<p>At this point, you are going to configure environment variables for your instance.</p>
</li>
<li>
<p>Paste the following into the <strong>Advanced Details</strong>.</p>
<td>A phrase to pass when using the hub admin. For example, <code>hubba</code> is a fun key phrase.</td>
</tr>
<tr>
<td><code><NAME_OF_DOMAIN></code></td>
<td>Your hub's domain name. For example, <code>maryhub.ml</code> is the domain name in this example.</td>
</tr>
<tr>
<td><code><STAGING_VALUE></code></td>
<td>
<p>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.</p>
<p>For this tutorial, use production (`0`).</p>
</td>
</tr>
</tbody>
</table>
</li>
<li>
<p>Check your <strong>Advanced Details</strong> they should look similar to the following:</p>
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.
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.
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.
<li>Check that your domain's DNS configuration matches the public IP address of your instance.</li>
<li>Update the DNS site's configuration.</li>
<li>Restart your EC2 instance as per the <ahref="#restart-services-and-reload-certificates">Restart and reload certificates</a> procedure on this page.</li>
10. Extend the IP with the `PUBLIC_IP/hub_info` tag like so.
You should see a response from your Gaia hub!
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 <ahref="https://www.freenom.com"target="\_blank">domain through the freenom service</a>. 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.
7. After your changes propagate, visit your new domain at the `hub_info` page.
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.
9. Check the SSL certificate for your hub.
Each browser has its own check procedure, for example, Chrome:
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.
<td>This service runs every 12 hours so you may not see it in the output. The service runs Let's Encrypt <code>certbot</code> 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. </td>
<td>Runs 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 <code>readURL</code> to make requests. Changes to a hub's <code>readURL</code> must be reflected in the <code>nginx</code> service configuration in <code>/gaia/nginx/conf.d/default.conf</code></td>
<td>A simple administrative service that allows you to administer the Gaia hub. Use REST calls with this service to get and set hub configuration values.</td>
<td>A 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.</td>
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.
