mirror of https://github.com/lukechilds/docs.git
Moxiegirl
6 years ago
committed by
GitHub
GitHub
6 changed files with 451 additions and 1369 deletions
|
After Width: | Height: | Size: 22 KiB |
@ -1,802 +0,0 @@ |
|||||
--- |
|
||||
layout: learn |
|
||||
permalink: /:collection/:path.html |
|
||||
image: /assets/img/zero-to-dapp.png |
|
||||
--- |
|
||||
# 3. Build an Animal Kingdom DApp |
|
||||
{:.no_toc} |
|
||||
|
|
||||
**Zero to DAPP 3 of 4** |
|
||||
|
|
||||
In this part, you follow a tutorial which builds, runs, and modifies a DAPP |
|
||||
called Animal Kingdom. Through this exercise, you'll learn about the |
|
||||
interactions between a Blockstack identity and a DApp. You'll also learn about |
|
||||
the Blockstack Javascript calls in a typical DApp. |
|
||||
|
|
||||
* TOC |
|
||||
{:toc} |
|
||||
|
|
||||
### Skills you need to build Animal Kingdom |
|
||||
|
|
||||
This tutorial is designed for a wide audience. Anyone with access to a Windows, |
|
||||
Mac, or Linux computer and some familiarity with a command line can build the |
|
||||
Animal Kingdom DApp. |
|
||||
|
|
||||
If you are good at following directions, chances are you can complete this |
|
||||
tutorial even if you have no programming experience. Knowledgeable developers |
|
||||
should easily be able to complete the tutorial within an hour by following |
|
||||
along. |
|
||||
|
|
||||
If you are a developer superhero, you may want to skip ahead or move |
|
||||
quickly and that's fine too. |
|
||||
|
|
||||
## Get prerequisites and set up your environment |
|
||||
|
|
||||
To follow this tutorial, you need the following: |
|
||||
|
|
||||
* A Blockstack ID (identity) to test your Animal Kingdom. |
|
||||
* Access to the Mac terminal window and some familiarity with the command line it provides. |
|
||||
* An installation of the XCode command-line tools to support Node Package Manager (`npm`) |
|
||||
* The Node Package Manager package manager. |
|
||||
|
|
||||
Follow the procedures in this section to install these components. |
|
||||
|
|
||||
### Confirm or get a Blockstack ID |
|
||||
{:.no_toc} |
|
||||
|
|
||||
Confirm you have a Blockstack ID also known as an identity; `joe.id.blockstack` |
|
||||
is an example of an identity. |
|
||||
|
|
||||
* If you have an existing ID, log into the <a href="https://browser.blockstack.org/" target="\_blank">Blockstack Browser</a> in your browser. |
|
||||
|
|
||||
The Blockstack Browser is itself a DApp. Logging in confirms you have a valid |
|
||||
ID with the required _secret recovery key_ or _magic recovery code_. The |
|
||||
secret recovery key is a 12 or 24 word phrase you recorded when you created |
|
||||
the ID. The magic recovery code is a string of characters Blockstack emailed |
|
||||
to you when you created your identity. You can confirm your identity with either. |
|
||||
|
|
||||
* If you do not yet have a Blockstack ID, <a href="https://browser.blockstack.org/" target="\_blank">create one through the Blockstack Browser</a> . |
|
||||
|
|
||||
Instructions for creating an ID are <a href="{{ site.baseurl }}/browser/ids-introduction.html#create-an-initial-blockstack-id" target="\_blank">available in this documentation</a>. |
|
||||
|
|
||||
|
|
||||
### Ensure command-line access |
|
||||
{:.no_toc} |
|
||||
|
|
||||
If you are using a Mac, you can find the **terminal** in the **Application > |
|
||||
Launchpad > Other** folder. |
|
||||
|
|
||||
<img src="images/terminal.png" alt=""> |
|
||||
|
|
||||
If you don't often use the command line, take a moment to test some common commands. |
|
||||
|
|
||||
<table class="uk-table uk-table-small uk-table-divider"> |
|
||||
<tr> |
|
||||
<th>Command</th> |
|
||||
<th>What it does</th> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>ls</code></td> |
|
||||
<td>Lists the files and directories in the current directory.</td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>cd</code></td> |
|
||||
<td>Change directory to navigate to locations in your file system.</td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>pwd</code></td> |
|
||||
<td>Print the working directory, the location you are working in.</td> |
|
||||
</tr> |
|
||||
</table> |
|
||||
|
|
||||
### Install XCode Command Line tools |
|
||||
{:.no_toc} |
|
||||
|
|
||||
The Command Line Tool package gives Mac terminal users many commonly used tools, |
|
||||
utilities, and compilers. Some of the contents installed by NPM require XCode. |
|
||||
|
|
||||
1. Open a terminal window on your system. |
|
||||
2. Enter the `xcode-select` command string: |
|
||||
|
|
||||
```bash |
|
||||
$ xcode-select --install |
|
||||
``` |
|
||||
|
|
||||
<img src="images/install-command-line-tools-os-x.jpg" alt=""> |
|
||||
|
|
||||
A software update dialog displays: |
|
||||
|
|
||||
<img src="images/confirm-install-command-line-tools-mac-os-x.jpg" alt=""> |
|
||||
|
|
||||
3. Click **Install** to confirm. |
|
||||
|
|
||||
You are prompted to agree to the terms of service. |
|
||||
|
|
||||
4. Agree to the terms of services. |
|
||||
|
|
||||
The tools are installed. This is fairly quick depending on your connection speed. |
|
||||
|
|
||||
|
|
||||
### Install Node Package Manager (NPM) |
|
||||
{:.no_toc} |
|
||||
|
|
||||
Open source developers from every continent use NPM to share software components |
|
||||
called packages. The Animal Kingdom uses React, Babel, and many other |
|
||||
components. You'll use the `npm` command to install these packaged components. |
|
||||
|
|
||||
|
|
||||
1. Verify you have installed `npm` using the `which` command. |
|
||||
|
|
||||
<img src="images/command-line.png" alt=""> |
|
||||
|
|
||||
If `npm` is installed, `which` returns the command's location in your environment. |
|
||||
|
|
||||
3. If the `npm` command is not in your system, <a href="https://www.npmjs.com/get-npm" target="\_blank">install it</a>. |
|
||||
|
|
||||
Installing the NPM tool can take several minutes depending on your connection speed. |
|
||||
|
|
||||
|
|
||||
## Overview of the Animal Kingdom DApp |
|
||||
|
|
||||
You are going to build a DApp called AnimalKingdom. Animal Kingdom is a DApp for |
|
||||
the web. Users log into it and create an animal persona that rules over a |
|
||||
specific territory. The combination of persona and territory is a kingdom. Once |
|
||||
you create a kingdom, you can add subjects from other kingdoms. |
|
||||
|
|
||||
The Animal Kingdom interacts with two Blockstack services, the Blockstack |
|
||||
Browser (https://browser.blockstack.org) and the Gaia data storage hub |
|
||||
(https://hub.blockstack.org/). The Blockstack Browser is itself |
|
||||
a DApp. The storage hub is purely a service without user-facing functionality. |
|
||||
|
|
||||
The following table describes the key interactions and screens in the DApp. |
|
||||
|
|
||||
<table class="uk-table uk-table-striped"> |
|
||||
<tr> |
|
||||
<th>Click to enlarge</th> |
|
||||
<th> Description</th> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><div uk-lightbox="animation: slide"> |
|
||||
<a class="uk-inline" href="images/kingdom-enter.png" data-caption="Users must login with a Blockstack identity."> |
|
||||
<img src="images/kingdom-enter.png" alt=""> |
|
||||
</a> |
|
||||
</div> |
|
||||
</td> |
|
||||
<td><p>Users log in (authenticate) with a Blockstack identity. By authenticating, the user gives the application the ability to get and put data in the user's Gaia storage hub.</p></td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><div uk-lightbox="animation: slide"> |
|
||||
<a class="uk-inline" href="images/kingdom-signin.png" data-caption="Blockstack login dialogs."> |
|
||||
<img src="images/kingdom-signin.png" alt=""> |
|
||||
</a> |
|
||||
</div> |
|
||||
</td> |
|
||||
<td><p>The Blockstack login dialogs are part of the Blockstack Browser which is itself |
|
||||
a DApp. Once a user authenticates, the DApp code automatically |
|
||||
returns them to the Kingdom they were attempting to enter.</p></td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><div uk-lightbox="animation: slide"> |
|
||||
<a class="uk-inline" href="images/kingdom-new.png" data-caption="Choose a persona and territory."> |
|
||||
<img src="images/kingdom-new.png" alt=""> |
|
||||
</a> |
|
||||
</div></td> |
|
||||
<td><p>First-time visitors to a kingdom are prompted to create an animal persona and |
|
||||
a territory to rule. Once they make a selection, users click <strong>Done</strong> to create a |
|
||||
kingdom to rule. Behind the scenes, the data about the user's selection is stored in the user's GAIA hub. |
|
||||
</p> |
|
||||
</td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td> <div uk-lightbox="animation: slide"> |
|
||||
<a class="uk-inline" href="images/kingdom-choices.gif" data-caption="Choose a persona and territory."> |
|
||||
<img src="images/kingdom-choices.gif" alt=""> |
|
||||
</a> |
|
||||
</div></td> |
|
||||
<td><p>Each kingdom has animals and territories. Users can edit their original persona/animal combination. You'll learn how to modify the Animal Kingdom code to add new animals and territories.</p></td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><div uk-lightbox="animation: slide"> |
|
||||
<a class="uk-inline" href="images/kingdom-subjects.gif" data-caption="Adding subjects"> |
|
||||
<img src="images/kingdom-subjects.gif" alt=""> |
|
||||
</a> |
|
||||
</div></td> |
|
||||
<td> |
|
||||
<p>Users can add subjects from territories in their own Animal Kingdom. The DApp updates the user's GAI hub each time the user adds a subject. Users can also visit other Animal Kingdom installations and add subjects from these as well. You'll learn how to modify the <b>Other Kingdoms</b> available in your installation. |
|
||||
</p> |
|
||||
</td> |
|
||||
</tr> |
|
||||
</table> |
|
||||
|
|
||||
|
|
||||
## Get the Animal Kingdom code |
|
||||
|
|
||||
In this section, you copy the code for Animal Kingdom to your workstation. |
|
||||
|
|
||||
1. In your browser (Chrome, Safari, etc), <a href="https://github.com/blockstack/animal-kingdom" target="\_blank">open the Animal Kingdom code repository</a>. |
|
||||
|
|
||||
The AnimalKingdom code is kept in a public GitHub repository. |
|
||||
|
|
||||
2. Click the **Clone or download** button. |
|
||||
|
|
||||
If you have a GitHub account you can choose to clone the original repository |
|
||||
or fork it and then clone it. These instructions assume you are downloading |
|
||||
the code. |
|
||||
|
|
||||
3. Choose the **Download ZIP** for Animal Kingdom. |
|
||||
|
|
||||
<img src="images/kingdom-copy.png" alt=""> |
|
||||
|
|
||||
3. Check your download directory for the `animal-kingdom-master.zip` file. |
|
||||
4. Copy the download zip file to a directory where you keep code projects. |
|
||||
4. Unzip the file. |
|
||||
|
|
||||
<img src="images/kingdom-download.png" alt=""> |
|
||||
|
|
||||
After unzipping the file you should have an `animal-kingdom-master` directory. |
|
||||
|
|
||||
5. In your terminal change directory into the top of the directory by entering: |
|
||||
|
|
||||
```bash |
|
||||
$ cd animal-kingdom-master |
|
||||
``` |
|
||||
|
|
||||
Use the `pwd` command to confirm which directory you are in. |
|
||||
|
|
||||
```bash |
|
||||
$ pwd |
|
||||
/Users/manthony/animal-kingdom-master |
|
||||
``` |
|
||||
|
|
||||
6. Take a minute review the files and subdirectories in your Animal Kingdom project. |
|
||||
|
|
||||
Use the `ls` command to list directory contents. |
|
||||
|
|
||||
<table class="uk-table uk-table-striped"> |
|
||||
<tr> |
|
||||
<th><b>Name</b> </th> |
|
||||
<th><b>Description</b></th> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>README.md</code></td> |
|
||||
<td>Contains a quick reference for building and running Animal Kingdom. </td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>package.json</code></td> |
|
||||
<td>An NPM project file.</td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>config</code></td> |
|
||||
<td>Environment configuration files written in Javascript.</td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>public</code></td> |
|
||||
<td>Files that are copied into the root of the site you are building.</td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>scripts</code></td> |
|
||||
<td>NPM scripts used to do common tasks in the project.</td> |
|
||||
</tr> |
|
||||
<tr> |
|
||||
<td><code>src</code></td> |
|
||||
<td>Vue.js code source code for the site. This contains configuration files.</td> |
|
||||
</tr> |
|
||||
</table> |
|
||||
|
|
||||
## Build and run the sample in development mode |
|
||||
|
|
||||
You can build and run the Animal Kingdom on your local workstation. Before you |
|
||||
can run the program you use NPM to get all the dependent packages. |
|
||||
|
|
||||
1. Make sure you are in the root directory of the project. |
|
||||
|
|
||||
```bash |
|
||||
cd ~/animal-kingdom-master |
|
||||
pwd |
|
||||
/Users/manthony/animal-kingdom-master |
|
||||
``` |
|
||||
|
|
||||
2. Enter `npm install` to get the software components Animal Kingdom needs. |
|
||||
|
|
||||
```bash |
|
||||
$ npm install |
|
||||
|
|
||||
> fsevents@1.2.4 install /Users/manthony/animal-kingdom-master/node_modules/fsevents |
|
||||
> node install |
|
||||
|
|
||||
node-pre-gyp WARN Tried to download(404): https://fsevents-binaries.s3-us-west-2.amazonaws.com/v1.2.4/fse-v1.2.4-node-v67-darwin-x64.tar.gz |
|
||||
node-pre-gyp WARN Pre-built binaries not found for fsevents@1.2.4 and node@11.1.0 (node-v67 ABI, unknown) (falling back to source compile with node-gyp) |
|
||||
SOLINK_MODULE(target) Release/.node |
|
||||
CXX(target) Release/obj.target/fse/fsevents.o |
|
||||
In file included from ../fsevents.cc:6: |
|
||||
|
|
||||
... |
|
||||
|
|
||||
added 1390 packages from 766 contributors and audited 15238 packages in 16.11s |
|
||||
found 1 high severity vulnerability |
|
||||
run `npm audit fix` to fix them, or `npm audit` for details |
|
||||
$ |
|
||||
``` |
|
||||
|
|
||||
This command creates a `node_modules` subdirectory to your project code and |
|
||||
installs all the code libraries you need for your Animal Kingdom project. |
|
||||
|
|
||||
3. Enter the `ls` command to list the contents of your project directory to verify `npm` installed correctly. |
|
||||
|
|
||||
``` |
|
||||
$ ls |
|
||||
``` |
|
||||
|
|
||||
The `node_modules`directory contains many core libraries used by Animal |
|
||||
Kingdom. For example, the Blockstack Javascript library is in the |
|
||||
`nodule_modules/blockstack/lib` subdirectory. |
|
||||
|
|
||||
4. Start the Animal Kingdom DApp running on your workstation by entering: |
|
||||
|
|
||||
```bash |
|
||||
npm start |
|
||||
``` |
|
||||
|
|
||||
The `npm` program compiles the Animal Kingdom code. Once the code compiles, |
|
||||
the DApp opens Animal Kingdom running at the `http://localhost:3000` URL in |
|
||||
your browser. |
|
||||
|
|
||||
4. From the initial Animal Kingdom screen, choose an animal person and a territory. |
|
||||
5. Press **Done** at the bottom of the page. |
|
||||
|
|
||||
The Animal Kingdom makes a call to the Gaia hub to store your selection. |
|
||||
After a brief pause, the DApp returns you to the **Your Kingdom** page. If |
|
||||
you have problems, refresh the page and click **Your Kingdom** in the |
|
||||
menu. |
|
||||
|
|
||||
<img src="images/kingdom-ruler.png" alt=""> |
|
||||
|
|
||||
6. Spend a little time exploring the application. |
|
||||
|
|
||||
For example, you could edit your animal or visit the other pages such as **Animals** or **Territories**. |
|
||||
|
|
||||
7. Go back to your terminal where you started you application is running. |
|
||||
8. Press `CTRL-C` to stop the application. |
|
||||
|
|
||||
<img src="images/kingdom-stop.png" alt=""> |
|
||||
|
|
||||
You can start it again with `npm start` as you will later in this tutorial. |
|
||||
|
|
||||
|
|
||||
## Understand the application code |
|
||||
|
|
||||
The application has two major components, React and Blockstack. React is used to |
|
||||
build all the web components and interactions. You could replace React with any |
|
||||
framework that you like; Blockstack is web framework agnostic. This section does |
|
||||
not explain the React in any detail; The discussion focuses on the Blockstack |
|
||||
Javascript library the DApp instead. |
|
||||
|
|
||||
The <a href="https://blockstack.github.io/blockstack.js/" |
|
||||
target="\_blank">Blockstack Javascript library is all a developer needs to |
|
||||
create a DApp. It grants</a> the application the ability to authenticate a |
|
||||
Blockstack identity and to read and write to the user's data stored in a Gaia |
|
||||
hub. |
|
||||
|
|
||||
### Authenticating user identity |
|
||||
{:.no_toc} |
|
||||
|
|
||||
The `src/App.js` file creates a Blockstack `UserSession` and uses that session's |
|
||||
`isUserSignedIn()` method to determine if the user is signed in or out of the |
|
||||
application. Depending on the result of this method. The application redirects |
|
||||
to the `src/SignedIn` page or to the `src/Landing.js` page. |
|
||||
|
|
||||
```js |
|
||||
import React, { Component } from 'react' |
|
||||
import './App.css' |
|
||||
import { UserSession } from 'blockstack' |
|
||||
|
|
||||
import Landing from './Landing' |
|
||||
import SignedIn from './SignedIn' |
|
||||
|
|
||||
class App extends Component { |
|
||||
|
|
||||
constructor() { |
|
||||
super() |
|
||||
this.userSession = new UserSession() |
|
||||
} |
|
||||
|
|
||||
componentWillMount() { |
|
||||
const session = this.userSession |
|
||||
if(!session.isUserSignedIn() && session.isSignInPending()) { |
|
||||
session.handlePendingSignIn() |
|
||||
.then((userData) => { |
|
||||
if(!userData.username) { |
|
||||
throw new Error('This app requires a username.') |
|
||||
} |
|
||||
window.location = `/kingdom/${userData.username}` |
|
||||
}) |
|
||||
} |
|
||||
} |
|
||||
|
|
||||
render() { |
|
||||
return ( |
|
||||
<main role="main"> |
|
||||
{this.userSession.isUserSignedIn() ? |
|
||||
<SignedIn /> |
|
||||
: |
|
||||
<Landing /> |
|
||||
} |
|
||||
</main> |
|
||||
); |
|
||||
} |
|
||||
} |
|
||||
|
|
||||
export default App |
|
||||
``` |
|
||||
|
|
||||
The first time you start the application, this code determines if the user has |
|
||||
signed into the DApp previously. If not, it opens the `Landing.js` page. This |
|
||||
page offers the user an opportunity to **Sign in to Blockstack**. |
|
||||
|
|
||||
Clicking the button ends up calling the `redirectToSignIn()` method which generates an |
|
||||
authentication request and redirects the user to the Blockstack browser to |
|
||||
approve the sign in request. The actual Blockstack sign-in dialog depends on |
|
||||
whether the user already has an existing session in the Blockstack Browser. |
|
||||
|
|
||||
<img src="images/kingdom_notin.png" alt=""> |
|
||||
|
|
||||
Signing in with an identity is the means by which the user grants the DApp |
|
||||
access. Access means the DApp can read the user profile and read/write user data |
|
||||
for the DApp. Data is encrypted at a unique URL on a GAI storage hub. |
|
||||
|
|
||||
### Get and put user data to a GAIA Hub |
|
||||
{:.no_toc} |
|
||||
|
|
||||
GAI is the Blockstack data storage hub (https://hub.blockstack.org). Once a user |
|
||||
authenticates, the application can get and put application data in the user's |
|
||||
storage. After a user signs in, the `SignedIn.js` code checks the user's GAI |
|
||||
profile by running the `loadMe()` method. |
|
||||
|
|
||||
```js |
|
||||
loadMe() { |
|
||||
const options = { decrypt: false } |
|
||||
this.userSession.getFile(ME_FILENAME, options) |
|
||||
.then((content) => { |
|
||||
if(content) { |
|
||||
const me = JSON.parse(content) |
|
||||
this.setState({me, redirectToMe: false}) |
|
||||
} else { |
|
||||
const me = null |
|
||||
|
|
||||
this.setState({me, redirectToMe: true}) |
|
||||
} |
|
||||
}) |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
The `loadMe()` code uses the Blockstack's `getFile()` method to get the |
|
||||
specified file from the applications data store. If the users' data store on |
|
||||
GAIA does not have the data, which is the case for a new users, the Gaia hub |
|
||||
responds with HTTP `404` code and the `getFile` promise resolves to null. If you |
|
||||
are using a Chrome Developer Tools with the DApp, you'll see these errors in a |
|
||||
browser's developer **Console**. |
|
||||
|
|
||||
<img src="images/kingdom-errors.png" alt=""> |
|
||||
|
|
||||
After a user choses an animal persona and a territory, the user presses **Done** |
|
||||
and the application stores the user data on GAIA. |
|
||||
|
|
||||
```js |
|
||||
saveMe(me) { |
|
||||
this.setState({me, savingMe: true}) |
|
||||
const options = { encrypt: false } |
|
||||
this.userSession.putFile(ME_FILENAME, JSON.stringify(me), options) |
|
||||
.finally(() => { |
|
||||
this.setState({savingMe: false}) |
|
||||
}) |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
The Blockstack <a href="https://blockstack.github.io/blockstack.js/#putfile" |
|
||||
target="\_blank"><code>putFile()</code></a> stores the data provided in the |
|
||||
user's DApp data store. You can view the URL for the data store from a user's |
|
||||
profile. If you tested your Animal Kingdom, you can see this on your profile. |
|
||||
To see your profile, go to the Blockstack explorer and search for your ID: |
|
||||
|
|
||||
<img src="images/explorer.png" alt=""> |
|
||||
|
|
||||
In the next section, you extend your Kingdom's configuration. |
|
||||
|
|
||||
## Expand your kingdom |
|
||||
|
|
||||
Your DApp contains three pages **Animals**, **Territories**, and **Other |
|
||||
Kingdoms** that are derived from three code elements: |
|
||||
|
|
||||
* The `src/constants.js` file defines the application's data profile. |
|
||||
* The `public/animals` directory which contains images. |
|
||||
* The `public/territories` directory which contains images. |
|
||||
|
|
||||
In this section, you learn how to add another kingdom to the available **Other |
|
||||
Kingdoms** and how to add another territory. |
|
||||
|
|
||||
### Add a territory |
|
||||
{:.no_toc} |
|
||||
|
|
||||
If your application is still running in localhost stop it with a `CTRL-C` from |
|
||||
your keyboard. |
|
||||
|
|
||||
1. Decide what kind of territory to add &emdash; desert, ocean, or city! |
|
||||
|
|
||||
This example adds Westeros, a fictional territory. |
|
||||
|
|
||||
2. Search for an image to represent your new territory. |
|
||||
|
|
||||
Google images is a good place to find <a href="images/westeros.jpg" target="\_blank">a JPEG image of Westeros</a>. |
|
||||
|
|
||||
3. Save the image to the `public/territories` folder in your Animal Kingdom project code. |
|
||||
|
|
||||
{% include warning.html content="The territory filename must be all lower case and have a <code>.jpg</code> extension. |
|
||||
For this example, the territory image is saved in the <code>westeros.jpg</code> file." %} |
|
||||
|
|
||||
4. Use the `ls` command to confirm your file appears in `territories` directory and has the correct name. |
|
||||
|
|
||||
```bash |
|
||||
ls public/territories/ |
|
||||
forest.jpg tundra.jpg westeros.jpg |
|
||||
``` |
|
||||
|
|
||||
4. Open the `src/constant.js` file in your favorite editor. |
|
||||
5. Scroll down to the section that defines the **Territories**. |
|
||||
|
|
||||
```js |
|
||||
export const TERRITORIES = [ |
|
||||
{ |
|
||||
id: 'forest', |
|
||||
name: 'Forest', |
|
||||
superpower: 'Trees!' |
|
||||
}, |
|
||||
{ |
|
||||
id: 'tundra', |
|
||||
name: 'Tundra', |
|
||||
superpower: 'Let it snow!' |
|
||||
} |
|
||||
] |
|
||||
``` |
|
||||
|
|
||||
6. Add your new territory. |
|
||||
|
|
||||
```js |
|
||||
export const TERRITORIES = [ |
|
||||
{ |
|
||||
id: 'forest', |
|
||||
name: 'Forest', |
|
||||
superpower: 'Trees!' |
|
||||
}, |
|
||||
{ |
|
||||
id: 'tundra', |
|
||||
name: 'Tundra', |
|
||||
superpower: 'Let it snow!' |
|
||||
}, |
|
||||
{ |
|
||||
id: 'westeros', |
|
||||
name: 'Westeros', |
|
||||
superpower: 'The Iron Throne!' |
|
||||
} |
|
||||
] |
|
||||
``` |
|
||||
7. Save and close the `contstant.js` file. |
|
||||
8. Back in a terminal window, restart your application. |
|
||||
|
|
||||
```bash |
|
||||
$ npm start |
|
||||
``` |
|
||||
9. After the application starts, navigate to the **Territories** page and look for your `Westeros` territory. |
|
||||
|
|
||||
<img src="images/kingdom-throne.png" alt=""> |
|
||||
|
|
||||
### Add the Blockstack kingdom |
|
||||
{:.no_toc} |
|
||||
|
|
||||
Your Animal Kingdom has only recognizes two **Other Kingdoms**. In this section, |
|
||||
you add a third, the Blockstack kingdom (`https://animalkingdoms.netlify.com`). |
|
||||
|
|
||||
1. Open the `src/constant.js` file in your favorite editor. |
|
||||
|
|
||||
On Mac you can use TextEdit or Vim. |
|
||||
|
|
||||
2. Scroll down to the section that defines the **Other Kingdoms** |
|
||||
|
|
||||
```js |
|
||||
export const OTHER_KINGDOMS = [ |
|
||||
{ |
|
||||
app: 'https://animal-kingdom-1.firebaseapp.com', |
|
||||
ruler: 'larry.id' |
|
||||
}, |
|
||||
{ |
|
||||
app: 'http://localhost:3001', |
|
||||
ruler: 'larz.id' |
|
||||
} |
|
||||
] |
|
||||
``` |
|
||||
|
|
||||
To add a kingdom, you need its URL and the ID of its owner. |
|
||||
|
|
||||
3. Edit the file and add the `https://animalkingdoms.netlify.com` which is owned by `moxiegirl.id.blockstack`. |
|
||||
|
|
||||
When you are done the file will look like this. |
|
||||
|
|
||||
|
|
||||
```js |
|
||||
export const OTHER_KINGDOMS = [ |
|
||||
{ |
|
||||
app: 'https://animal-kingdom-1.firebaseapp.com', |
|
||||
ruler: 'larry.id' |
|
||||
}, |
|
||||
{ |
|
||||
app: 'http://localhost:3001', |
|
||||
ruler: 'larz.id' |
|
||||
}, |
|
||||
{ |
|
||||
app: 'https://animalkingdoms.netlify.com', |
|
||||
ruler: 'moxiegirl.id.blockstack' |
|
||||
} |
|
||||
] |
|
||||
``` |
|
||||
|
|
||||
4. Save and close the `constants.js` file. |
|
||||
5. Back in your browser, navigate to the **Other Kingdoms** page. |
|
||||
|
|
||||
<img src="images/kingdom-moxiegirl.png" alt=""> |
|
||||
|
|
||||
7. Got to the `moxiegirl` kingdom by clicking on her kingdom. |
|
||||
8. Try adding a subject from Moxiegirl's kingdom to yours. |
|
||||
|
|
||||
|
|
||||
## Go live on the Internet |
|
||||
|
|
||||
In this section you use a free Netlify account and a free GitHub account to take |
|
||||
your kingdom live on the internet. Netlify provides hosting and serverless |
|
||||
backend services for static websites. GitHub is a code hosting site. |
|
||||
|
|
||||
### Run your Kingdom on the internet |
|
||||
{:.no_toc} |
|
||||
|
|
||||
So far, you've been running the application locally. This means you are the only |
|
||||
person that can use it to create a kingdom. You can make your application |
|
||||
available to others by hosting it out on the internet. You can do this for free |
|
||||
with a Netlify account. |
|
||||
|
|
||||
Before you begin, you need to build a site that is ready to deploy. |
|
||||
|
|
||||
1. In your terminal, press `CTRL-C` on your keyboard to stop your `npm start` build. |
|
||||
2. Build a website from your code by entering the `npm run build` command: |
|
||||
|
|
||||
```bash |
|
||||
npm run build |
|
||||
``` |
|
||||
|
|
||||
<img src="images/run-build.png" alt=""> |
|
||||
|
|
||||
When the command completes, you should have a new `build` subdirectory in your project. |
|
||||
|
|
||||
3. Open your project in the Finder. |
|
||||
4. Locate the newly created `build` subfolder. |
|
||||
|
|
||||
<img src="images/finder-build.png" alt=""> |
|
||||
|
|
||||
5. <a href="https://app.netlify.com/signup" target="\_blank">Sign up for a free Netlify account</a> |
|
||||
|
|
||||
<img src="images/netlify-account.gif" alt=""> |
|
||||
|
|
||||
6. In your email inbox, find Netlify's welcome email and verify your account. |
|
||||
|
|
||||
<img src="images/netlify-verify.png" alt=""> |
|
||||
|
|
||||
7. Log into Netlify and go to the **Overview** page in your browser. |
|
||||
8. Drag your `build` subdirectory from the Finder into the drop zone in Netlify. |
|
||||
|
|
||||
<img src="images/netlify-deploy.gif" alt=""> |
|
||||
|
|
||||
After a moment, Netlify builds your code and displays the location of your new webiste. |
|
||||
|
|
||||
<img src="images/kingdom-build.png" alt=""> |
|
||||
|
|
||||
9. Click on your website name to display the website. |
|
||||
|
|
||||
You are prompted to sign into this new site with your Blockstack ID. |
|
||||
|
|
||||
10. Click **Sign in with Blockstack**. |
|
||||
|
|
||||
After you sign in, your website presents you with this message: |
|
||||
|
|
||||
<img src="images/kingdom-failed.png" alt=""> |
|
||||
|
|
||||
You get this message because, when you authenticates, your DApp at one URL |
|
||||
requested a resource (an identity) from another DApp, the Blockstack |
|
||||
Browser. A request for a resource outside of the origin (your new website) |
|
||||
is called as a _cross-origin request_(CORs). Getting data in this manner can |
|
||||
be risky, so you must configure your website security to allow interactions |
|
||||
across origins. |
|
||||
|
|
||||
<div class="uk-inline"> |
|
||||
<button class="uk-button uk-button-primary" enter="button">Read a bit more, fun, explanation of CORS</button> |
|
||||
<div uk-dropdown> |
|
||||
You can think of CORS interactions as an apartment building with Security. |
|
||||
For example, if you need to borrow a ladder, you could ask a neighbor in |
|
||||
your building who has one. Security would likely not have a problem with |
|
||||
this request (i.e., same-origin, your building). If you needed a particular |
|
||||
tool, however, and you ordered it delivered from an online hardware store |
|
||||
(i.e., cross-origin, another site), Security may request identificatin |
|
||||
before allowing the delivery man into the apartment building. |
|
||||
<br> |
|
||||
Credit: <a href="https://www.codecademy.com/articles/what-is-cors" target="\_blank">Codecademy</a> |
|
||||
</div> |
|
||||
</div> |
|
||||
|
|
||||
The way you configure CORs depends on which company is serving your website. |
|
||||
You are using Netlify for this example. |
|
||||
|
|
||||
11. Locate the `cors/_headers` and `cors/_redirects` in your project. |
|
||||
|
|
||||
You can use the Finder or the `ls` command. |
|
||||
|
|
||||
|
|
||||
12. Copy them into your `public` directory. |
|
||||
|
|
||||
To copy them with the `ls` command, enter the following in the root of the `animal-kingdom-master` project. |
|
||||
|
|
||||
```bash |
|
||||
cp cors/_headers public |
|
||||
cp cors/_redirects public |
|
||||
``` |
|
||||
|
|
||||
The name of each file, with the underscore, is essential. |
|
||||
|
|
||||
13. Make sure you are in the `animal-kingdom-master` directory, run the `npm run build` command again. |
|
||||
15. Drag the `build` file back into the Netlify drop zone. |
|
||||
|
|
||||
After a moment, Netlify publishes your site. Check the published location, it may have changed. |
|
||||
|
|
||||
16. Click on the link and log into your Animal Kingdom. |
|
||||
17. Recreate your animal person and territory. |
|
||||
|
|
||||
The Animal Kingdom is identified by its location on the Internet, remember? |
|
||||
So, the animal kingdom you created on your local workstation is different |
|
||||
than the one you create on Netlify. |
|
||||
|
|
||||
### Add your Kingdom to our Clan |
|
||||
{:.no_toc} |
|
||||
|
|
||||
At this point, your kingdom is isolated. If you know another kingdom, you can |
|
||||
add subjects from that kingdom but other kingdoms can access your subjects. In |
|
||||
this section, you use a free GitHub account to add your kingdom to the |
|
||||
Blockstack kingdom. |
|
||||
|
|
||||
1. If you have a GitHub account, go to step 2 otherwise go to GitHub <a href="https://github.com/" target="\_blank">site and create a new account</a>. |
|
||||
2. Go to the <a href="https://github.com/blockstack/animal-kingdom/issues" target="\_blank">https://github.com/blockstack/animal-kingdom/issues</a> repository on Github. |
|
||||
2. Click **New Issue**. |
|
||||
|
|
||||
The new issue dialog appears. |
|
||||
|
|
||||
3. Fill out the issue with the URL from Netlify and your Blockstack id. |
|
||||
|
|
||||
When you are done, your issue will look like the following: |
|
||||
|
|
||||
<img src="images/kingdom-issue.png" alt=""> |
|
||||
|
|
||||
4. Press **Submit new issue**. |
|
||||
|
|
||||
The Blockstack team will add your Netlify kingdom to ours. When we do that, we will notify you on the issue and you'll also get an email. |
|
||||
|
|
||||
5. When you receive the email, login into the Blockstack Animal kingdom to see your kingdom under **Other Kingdoms**. |
|
||||
|
|
||||
|
|
||||
## Next Steps |
|
||||
{:.no_toc} |
|
||||
|
|
||||
Well, you have produced your very first DApp. Congratulations! If you have a |
|
||||
twitter account, why not tell some folks? |
|
||||
|
|
||||
<a href="https://twitter.com/share?ref_src=twsrc%5Etfw" |
|
||||
class="twitter-share-button" data-size="large" data-text="I just built a DApp |
|
||||
using @blockstacks's Zero to DApp tutorial! " data-hashtags="blockstack, |
|
||||
blockchain, blockchainnopain, blockchainnopainblockstack" |
|
||||
data-show-count="false">Tweet your work!</a><script async |
|
||||
src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> | |
|
||||
|
|
||||
In the next section, you submit your [DApp to our listings on App.co](#). |
|
||||
Loading…
Reference in new issue