diff --git a/docs/server/source/cloud-deployment-starter-templates/index.rst b/docs/server/source/cloud-deployment-starter-templates/index.rst deleted file mode 100644 index bb71561e..00000000 --- a/docs/server/source/cloud-deployment-starter-templates/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -Cloud Deployment Starter Templates -================================== - -We have some "starter templates" to deploy a basic, working, but bare-bones BigchainDB node on various cloud providers. They should *not* be used as-is to deploy a node for production. They can be used as a starting point. A full production node should meet the requirements outlined in the section on :doc:`production node assumptions, components and requirements <../nodes/index>`. - -You don't have to use the tools we use in the starter templates (e.g. Terraform and Ansible). You can use whatever tools you prefer. - -If you find the cloud deployment starter templates for nodes helpful, then you may also be interested in our scripts for :doc:`deploying a testing cluster on AWS <../clusters-feds/aws-testing-cluster>` (documented in the Clusters & Federations section). - -.. toctree:: - :maxdepth: 1 - - template-terraform-aws - template-ansible - azure-quickstart-template diff --git a/docs/server/source/cloud-deployment-starter-templates/azure-quickstart-template.md b/docs/server/source/cloud-deployment-templates/azure-quickstart-template.md similarity index 94% rename from docs/server/source/cloud-deployment-starter-templates/azure-quickstart-template.md rename to docs/server/source/cloud-deployment-templates/azure-quickstart-template.md index 7603319f..1bf35a31 100644 --- a/docs/server/source/cloud-deployment-starter-templates/azure-quickstart-template.md +++ b/docs/server/source/cloud-deployment-templates/azure-quickstart-template.md @@ -1,6 +1,6 @@ # Azure Quickstart Template -If you didn't read the introduction to the [cloud deployment starter templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point. +If you didn't read the introduction to the [cloud deployment templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point. Note: There was an Azure quickstart template in the `blockchain` directory of Microsoft's `Azure/azure-quickstart-templates` repository on GitHub. It's gone now; it was replaced by the one described here. diff --git a/docs/server/source/cloud-deployment-templates/index.rst b/docs/server/source/cloud-deployment-templates/index.rst new file mode 100644 index 00000000..67a2ace4 --- /dev/null +++ b/docs/server/source/cloud-deployment-templates/index.rst @@ -0,0 +1,18 @@ +Cloud Deployment Templates +========================== + +We have some "templates" to deploy a basic, working, but bare-bones BigchainDB node on various cloud providers. They should *not* be used as-is to deploy a node for production. They can be used as a starting point. + +You don't have to use the tools we use in the templates. You can use whatever tools you prefer. + +If you find the cloud deployment templates for nodes helpful, then you may also be interested in our scripts for :doc:`deploying a testing cluster on AWS <../clusters-feds/aws-testing-cluster>` (documented in the Clusters & Federations section). + +.. toctree:: + :maxdepth: 1 + + template-terraform-aws + template-ansible + azure-quickstart-template + template-kubernetes-azure + node-on-kubernetes + \ No newline at end of file diff --git a/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst b/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst new file mode 100644 index 00000000..03ffb2fe --- /dev/null +++ b/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst @@ -0,0 +1,46 @@ +Run a BigchainDB Node in a Kubernetes Cluster +============================================= + +Assuming you already have a `Kubernetes `_ +cluster up and running, this page describes how to run a +BigchainDB node in it. + + +Step 1: Install kubectl +----------------------- + +kubectl is the Kubernetes CLI. +If you don't already have it installed, +then see the `Kubernetes docs to install it +`_. + + +Step 2: Configure kubectl +------------------------- + +The default location of the kubectl configuration file is ``~/.kube/config``. +If you don't have that file, then you need to get it. + +If you deployed your Kubernetes cluster on Azure +using the Azure CLI 2.0 (as per :doc:`our template `), +then you can get the ``~/.kube/config`` file using: + +.. code:: bash + + $ az acs kubernetes get-credentials \ + --resource-group \ + --name + + +Step 3: Run a MongoDB Container +------------------------------- + +To start a MongoDB Docker container in a pod on one of the cluster nodes: + +.. code:: bash + + $ kubectl ????? + + +Note: The BigchainDB Dashboard can be deployed +as a Docker container, like everything else. diff --git a/docs/server/source/cloud-deployment-starter-templates/template-ansible.md b/docs/server/source/cloud-deployment-templates/template-ansible.md similarity index 96% rename from docs/server/source/cloud-deployment-starter-templates/template-ansible.md rename to docs/server/source/cloud-deployment-templates/template-ansible.md index e71d4cc1..666ad790 100644 --- a/docs/server/source/cloud-deployment-starter-templates/template-ansible.md +++ b/docs/server/source/cloud-deployment-templates/template-ansible.md @@ -1,6 +1,6 @@ # Template: Ansible Playbook to Run a BigchainDB Node on an Ubuntu Machine -If you didn't read the introduction to the [cloud deployment starter templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point. +If you didn't read the introduction to the [cloud deployment templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point. This page explains how to use [Ansible](https://www.ansible.com/) to install, configure and run all the software needed to run a one-machine BigchainDB node on a server running Ubuntu 16.04. diff --git a/docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst b/docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst new file mode 100644 index 00000000..ad4a8b04 --- /dev/null +++ b/docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst @@ -0,0 +1,103 @@ +Template: Deploy a Kubernetes Cluster on Azure +============================================== + +A BigchainDB node can be run inside a `Kubernetes `_ +cluster. +This page describes one way to deploy a Kubernetes cluster on Azure. + + +Step 1: Get a Pay-As-You-Go Azure Subscription +---------------------------------------------- + +Microsoft Azure has a Free Trial subscription (at the time of writing), +but it's too limited to run an advanced BigchainDB node. +Sign up for a Pay-As-You-Go Azure subscription +via `the Azure website `_. + +You may find that you have to sign up for a Free Trial subscription first. +That's okay: you can have many subscriptions. + + +Step 2: Deploy an Azure Container Service (ACS) +----------------------------------------------- + +It's *possible* to deploy an Azure Container Service (ACS) +from the `Azure Portal `_ +(i.e. online in your web browser) +but it's actually easier to do it using the Azure +Command-Line Interface (CLI). +(The Azure Portal will ask you for a public SSH key +and a "service principal," and you'll have to create those +first if they don't exist. The CLI will create them +for you if necessary.) + +Microsoft has `instructions to install the Azure CLI 2.0 +on most common operating systems +`_. +Do that. + +Next, login to your account using: + +.. code:: bash + + $ az login + +It will tell you to open a web page and to copy a code to that page. + +If the login is a success, you will see some information +about all your subscriptions, including the one that is currently +enabled (``"state": "Enabled"``). If the wrong one is enabled, +you can switch to the right one using: + +.. code:: bash + + $ az account set --subscription + +Next, you will have to pick the Azure data center location +where you'd like to deploy your cluster. +You can get a list of all available locations using: + +.. code:: bash + + $ az account list-locations + +Next, create an Azure "resource group" to contain all the +resources (virtual machines, subnets, etc.) associated +with your soon-to-be-deployed cluster. You can name it +whatever you like but avoid fancy characters because they may +confuse some software. + +.. code:: bash + + $ az group create --name --location + +Example location names are ``koreacentral`` and ``westeurope``. + +Finally, you can deploy an ACS using something like: + +.. code:: bash + + $ az acs create --name \ + --resource-group \ + --agent-count 3 \ + --agent-vm-size Standard_D2_v2 \ + --dns-prefix \ + --generate-ssh-keys \ + --location \ + --orchestrator-type kubernetes + +There are more options. For help understanding all the options, use the built-in help: + +.. code:: bash + + $ az acs create --help + +It takes a few minutes for all the resources to deploy. +You can watch the progress in the `Azure Portal +`_: +go to **Resource groups** (with the blue cube icon) +and click on the one you created +to see all the resources in it. + +Next, you can :doc:`run a BigchainDB node on your new +Kubernetes cluster `. \ No newline at end of file diff --git a/docs/server/source/cloud-deployment-starter-templates/template-terraform-aws.md b/docs/server/source/cloud-deployment-templates/template-terraform-aws.md similarity index 95% rename from docs/server/source/cloud-deployment-starter-templates/template-terraform-aws.md rename to docs/server/source/cloud-deployment-templates/template-terraform-aws.md index 85e4cf9d..d4a22e83 100644 --- a/docs/server/source/cloud-deployment-starter-templates/template-terraform-aws.md +++ b/docs/server/source/cloud-deployment-templates/template-terraform-aws.md @@ -1,6 +1,6 @@ # Template: Using Terraform to Provision an Ubuntu Machine on AWS -If you didn't read the introduction to the [cloud deployment starter templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point. +If you didn't read the introduction to the [cloud deployment templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point. This page explains a way to use [Terraform](https://www.terraform.io/) to provision an Ubuntu machine (i.e. an EC2 instance with Ubuntu 16.04) and other resources on [AWS](https://aws.amazon.com/). That machine can then be used to host a one-machine BigchainDB node. diff --git a/docs/server/source/index.rst b/docs/server/source/index.rst index 932f1951..7f85a228 100644 --- a/docs/server/source/index.rst +++ b/docs/server/source/index.rst @@ -7,7 +7,7 @@ BigchainDB Server Documentation ← Back to All BigchainDB Docs introduction quickstart - cloud-deployment-starter-templates/index + cloud-deployment-templates/index nodes/index dev-and-test/index server-reference/index diff --git a/docs/server/source/introduction.md b/docs/server/source/introduction.md index 2b02d964..b9e6bf0a 100644 --- a/docs/server/source/introduction.md +++ b/docs/server/source/introduction.md @@ -8,7 +8,7 @@ Note that there are a few kinds of nodes: - A **dev/test node** is a node created by a developer working on BigchainDB Server, e.g. for testing new or changed code. A dev/test node is typically run on the developer's local machine. -- A **bare-bones node** is a node deployed in the cloud, either as part of a testing cluster or as a starting point before upgrading the node to be production-ready. Our cloud deployment starter templates deploy a bare-bones node, as do our scripts for deploying a testing cluster on AWS. +- A **bare-bones node** is a node deployed in the cloud, either as part of a testing cluster or as a starting point before upgrading the node to be production-ready. Our cloud deployment templates deploy a bare-bones node, as do our scripts for deploying a testing cluster on AWS. - A **production node** is a node that is part of a federation's BigchainDB cluster. A production node has the most components and requirements. @@ -16,7 +16,7 @@ Note that there are a few kinds of nodes: ## Setup Instructions for Various Cases * [Set up a local stand-alone BigchainDB node for learning and experimenting: Quickstart](quickstart.html) -* [Set up and run a bare-bones node in the cloud](cloud-deployment-starter-templates/index.html) +* [Set up and run a bare-bones node in the cloud](cloud-deployment-templates/index.html) * [Set up and run a local dev/test node for developing and testing BigchainDB Server](dev-and-test/setup-run-node.html) * [Deploy a testing cluster on AWS](clusters-feds/aws-testing-cluster.html) * [Set up and run a federation (including production nodes)](clusters-feds/set-up-a-federation.html) diff --git a/docs/server/source/nodes/node-assumptions.md b/docs/server/source/nodes/node-assumptions.md index 46d45ca7..f7e8379f 100644 --- a/docs/server/source/nodes/node-assumptions.md +++ b/docs/server/source/nodes/node-assumptions.md @@ -8,6 +8,6 @@ We make some assumptions about production nodes: 2. Each production node in a federation's cluster is managed by a different person or team. -Because of the first assumption, we don't provide a detailed cookbook explaining how to secure a server, or other things that a sysadmin should know. (We do provide some [starter templates](../cloud-deployment-starter-templates/index.html), but those are just a starting point.) +Because of the first assumption, we don't provide a detailed cookbook explaining how to secure a server, or other things that a sysadmin should know. (We do provide some [templates](../cloud-deployment-templates/index.html), but those are just a starting point.)