diff --git a/_data/navigation_learn.yml b/_data/navigation_learn.yml index ba3f9e28..31c77aba 100644 --- a/_data/navigation_learn.yml +++ b/_data/navigation_learn.yml @@ -10,6 +10,7 @@ - develop/storage - develop/profiles - develop/collections + - develop/deploy-tips - develop/betatesting - title: Try it! Zero to DApp diff --git a/_develop/deploy-tips.md b/_develop/deploy-tips.md new file mode 100644 index 00000000..dd7193fd --- /dev/null +++ b/_develop/deploy-tips.md @@ -0,0 +1,69 @@ +--- +layout: learn +description: Blockstack app mining documentation +permalink: /:collection/:path.html +--- +# How to deploy a Blockstack dApp +{:.no_toc} + +Blockstack applications are a type of web application that uses Blockstack's technology to authenticate users. As such, Blockstack apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. + + * TOC + {:toc} + +## Where to deploy your application + +Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: + +* Configure or customize the files in the `public` directory. +* Build your application site for deployment. +* Copy your generated application files to your production server. + +If you first populated your application with the Blockstack application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
File or DirectoryDescription
node_modules/react-scriptsA set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself.
package.jsonContains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment.
public/favicon.icoAn example shortcut icon.
public/index.htmlAn entry page for an application.
public/manifest.jsonA JSON file that describes your web application to the browser.  
corsContains example deployment files for cross-origin request configuration.
+ +If you use the generator to build Javascript or Vue scaffolding, your project configuration files will be different. + +Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Blockstack cannot give you specific instructions on how to do this. The steps you take are specific to your application. + +## Blockstack Authentication and deployment + +When your application authenticates users with Blockstack, your DApp at one URL requests 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. + +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 identification before allowing the delivery man into the apartment building. (Credit: Codecademy) + +The way you configure CORs depends on which company you use to host your web application. The application generator adds a `cors` directory to your application scaffolding. This directory contains files for Netlify (`_headers` and `_redirects`) as well as one for Firebase (`firebase.json`). Consult the documentation for your hosting service to learn how to configure CORS on that service. + +## Deployment and Radiks + +If you are deploying a Blockstack application that uses Radiks, your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as Heroku or Digital Ocean if your app uses Radiks.