add deployment guide for azure postgres and container instances (close #584) (#928)

docs/graphql/manual/getting-started/first-graphql-query.rst

@@ -1,3 +1,5 @@
+.. _first_graphql_query:
+
 Making your first GraphQL query
 ===============================
 

docs/graphql/manual/guides/deployment/azure-container-instances-postgres.rst

@@ -0,0 +1,224 @@
+.. _deploy_azure_ci_pg:
+
+Hasura GraphQL Engine on Azure with Container Instances and Postgres
+====================================================================
+
+This guide talks about how to deploy Hasura GraphQL Engine on `Azure
+<https://azure.microsoft.com>`__ using `Container Instances
+<https://azure.microsoft.com/en-us/services/container-instances/>`__ with `Azure
+Database for PostgreSQL server <https://azure.microsoft.com/en-us/services/postgresql/>`__.
+
+One-click deploy using ARM Template
+-----------------------------------
+
+All resources mentioned in this guide can be deployed using the one-click button below.
+
+.. image:: http://azuredeploy.net/deploybutton.png
+  :width: 200px
+  :alt: azure_deploy_button
+  :class: no-shadow
+  :target: https://portal.azure.com/#create/Microsoft.Template/uri/https%3a%2f%2fraw.githubusercontent.com%2fhasura%2fgraphql-engine%2fmaster%2finstall-manifests%2fazure-resource-manager%2fazuredeploy.json
+
+(This button takes you to the Azure Portal, you might want to :kbd:`Ctrl+Click` to
+open it in a new tab. Read more about this Resource Manager Template `here <https://github.com/hasura/graphql-engine/tree/master/install-manifests/azure-resource-manager>`__.)
+
+Pre-requisites
+--------------
+
+- Valid Azure Subscription with billing enabled or credits. (`click
+  here <https://azure.microsoft.com/en-us/free/>`__ for a free trial)
+- `Azure CLI <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>`_.
+
+The actions mentioned below can be executed using Azure Portal and Azure CLI. But,
+for the sake of simplicity in documentation, we are going to use Azure CLI, so
+that commands can be easily copy pasted and executed.
+
+Once the CLI is installed, login to your Azure account:
+
+.. code-block:: bash
+
+   az login
+
+Create a new Resource Group
+---------------------------
+
+As the name suggestes, Resource Groups are used to group together various
+resources on Azure. We'll create a resource group called ``hasura`` at the
+``westus`` location.
+
+.. code-block:: bash
+
+   az group create --name hasura --location westus
+
+Provision a PostgreSQL server
+-----------------------------
+
+.. note::
+
+   If you already have a database setup, you can skip these steps and jump
+   directly to :ref:`azure_allow_access`.
+
+Once the resource group is created, we create a Postgres server instance:
+
+.. code-block:: bash
+
+   az postgres server create --resource-group hasura \
+      --name "<server_name>" \
+      --location westus \
+      --admin-user hasura \
+      --admin-password "<server_admin_password>" \
+      --sku-name GP_Gen5_2 \
+      --version 10
+
+.. note::
+
+   Choose a unique name for ``<server_name>``. Also choose a strong password for
+   ``<server_admin_password>``, including uppercase, lowercase and numeric characters.
+   This will be required later to connect to the database.
+   (Make sure you escape the special characters depending on your shell.)
+
+Note down the hostname. It will be shown as below in the output:
+
+.. code-block:: bash
+
+     ...
+     "fullyQualifiedDomainName": "<server_name>.postgres.database.azure.com",
+     ...
+
+``<server_name>.postgres.database.azure.com`` is the hostname here.
+
+.. note::
+
+   If you get an error saying ``Specified server name is already used``, change
+   the value of ``--name`` (``<server_name>``) to something else.
+
+Create a new database
+---------------------
+
+Create a new database on the server:
+
+.. code-block:: bash
+
+   az postgres db create --resource-group hasura \
+      --server-name "<server_name>" \
+      --name hasura
+
+.. _azure_allow_access:
+
+Allow access to Azure Services
+------------------------------
+
+Create a firewall rule allowing acess from Azure internal services:
+
+.. code-block:: bash
+
+   az postgres server firewall-rule create --resource-group hasura \
+      --server-name "<server_name>" \
+      --name "allow-azure-internal" \
+      --start-ip-address 0.0.0.0 \
+      --end-ip-address 0.0.0.0
+
+Create a Container Instance
+---------------------------
+
+Launch Hasura using a container instance:
+
+.. code-block:: bash
+
+   az container create --resource-group hasura \
+      --name hasura-graphql-engine \
+      --image hasura/graphql-engine \
+      --dns-name-label "<dns-name-label>" \
+      --ports 8080 \
+      --secure-environment-variables "HASURA_GRAPHQL_DATABASE_URL=<database-url>"
+
+``<database-url>`` should be replaced by the following format:
+
+.. code-block:: bash
+
+   postgres://hasura%40<server_name>:<server_admin_password>@<hostname>:5432/hasura
+
+.. note::
+
+   ``%40`` is used in the username because Azure creates usernames as
+   ``admin-user@server-name`` and since the database url uses ``@`` to separate
+   username-password from hostname, we need to url-escape it in the username.
+   Any other special character should be url-encoded.
+
+If the ``<dns-name-label>`` is not available, choose another unique name and
+execute the command again.
+
+Open the Hasura Console
+-----------------------
+
+That's it! Once the deployment is complete, navigate to the container instance's
+IP or hostname to open Hasura console:
+
+.. code-block:: bash
+
+   az container show --resource-group hasura \
+      --name hasura-graphql-engine \
+      --query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" \
+      --out table
+
+Output will contain the FQDN in the format
+``<dns-name-label>.westus.azurecontainer.io``.
+
+Visit the following URL for the Hasura Console:
+
+.. code:: 
+
+   http://<dns-name-label>.westus.azurecontainer.io:8080/console
+
+Replace ``<dns-name-label>`` with the label given earlier.
+
+.. image:: https://storage.googleapis.com/graphql-engine-cdn.hasura.io/main-repo/img/azure_arm_aci_console_graphiql.png
+   :class: no-shadow
+   :alt: Hasura console
+
+You can create tables and test your GraphQL queries here. Checkout :ref:`Making
+your first GraphQL Query <first_graphql_query>` for a detailed guide.
+
+Troubleshooting
+---------------
+
+If your password contains special characters, check if they were URL encoded
+and given as environment variables. Also check for proper escaping of
+these characters based on your shell.
+
+You can check the logs to see if the database credentials are proper and if
+Hasura is able to connect to the database.
+
+If you're using an existing/external database, make sure the firewall rules for
+the database allow connection for Azure services.
+
+Checking logs
+^^^^^^^^^^^^^
+
+If the console is not loading, you might want to check logs and see if something
+is wrong:
+
+.. code-block:: bash
+
+   az container logs --resource-group hasura \
+      --name hasura-graphql-engine \
+      --container-name hasura-graphql-engine
+   # use --follow flag to stream logs
+
+Tearing down
+------------
+
+To clean-up, just delete the resource group:
+
+.. code-block:: bash
+
+   az group delete --resource-group hasura
+
+References
+----------
+
+- `Installing Azure CLI <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>`_
+- `Creating a Azure Postgres Server
+  <https://docs.microsoft.com/en-us/azure/postgresql/quickstart-create-server-database-azure-cli>`_
+- `Using Azure Container Instances
+  <https://docs.microsoft.com/en-us/azure/container-instances/container-instances-quickstart>`_

docs/graphql/manual/guides/deployment/index.rst

@@ -3,6 +3,7 @@ Guides: Deployment
 
 - :doc:`Deploy on Digital Ocean using Docker <digital-ocean>`
 - :doc:`Digital Ocean One-click App <digital-ocean-one-click>`
+- :doc:`Azure Container Instances with Postgres <azure-container-instances-postgres>`
 - `Blog: Instant GraphQL on AWS RDS <https://blog.hasura.io/instant-graphql-on-aws-rds-1edfb85b5985>`__
 
 .. note::
@@ -17,3 +18,4 @@ Guides: Deployment
 
    On Digital Ocean using Docker <digital-ocean>
    DigitalOcean One-click App <digital-ocean-one-click>
+   Azure Container Instances with Postgres <azure-container-instances-postgres>

docs/graphql/manual/guides/index.rst

@@ -6,6 +6,7 @@ Deployment guides
 
 - :doc:`Deploy on Digital Ocean using Docker <deployment/digital-ocean>`
 - :doc:`Digital Ocean One-click App <deployment/digital-ocean-one-click>`
+- :doc:`Azure Container Instances with Postgres <deployment/azure-container-instances-postgres>`
 - `Blog: Instant GraphQL on AWS RDS <https://blog.hasura.io/instant-graphql-on-aws-rds-1edfb85b5985>`__
 
 .. note::

install-manifests/azure-resource-manager/README.md

@@ -0,0 +1,85 @@
+# Hasura GraphQL Engine on Azure
+
+Click the button below to create a Hasura GraphQL Engine container on
+[Azure Container
+Instances](https://azure.microsoft.com/en-us/services/container-instances/)
+backed by an [Azure Database for
+PostgreSQL](https://azure.microsoft.com/en-us/services/postgresql/) Server.
+For a more detailed step-by-step guide on deplopying individual
+resources to Azure using the CLI, refer to the 
+[documentation](https://docs.hasura.io/1.0/graphql/manual/guides/deployment/azure-container-instances-postgres.html).
+
+[![Deploy to Azure Button](https://azuredeploy.net/deploybutton.png)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3a%2f%2fraw.githubusercontent.com%2fhasura%2fgraphql-engine%2fmaster%2finstall-manifests%2fazure-resource-manager%2fazuredeploy.json)
+
+(The button opens Azure Portal, you might want to do a <kbd>Ctrl+Click</kbd>, to get it on a new tab)
+
+## Pre-requisites
+
+- A valid Azure Subscription ([click
+  here](https://azure.microsoft.com/en-us/free/) for a free trial).
+  
+## Instructions
+
+Once you click the button, it will take you to the Azure Portal, where you might be
+prompted to login first.
+
+A custom deployment screen will show up - enter the following information, as shown in
+the screenshot that follows:
+
+- **Subscription**: choose an Azure subscription.
+- **Resource Group**: choose an existing one or create a new one.
+- **Location**: choose a location for the resource group (note: Azure Container
+  Instances and Database for PostgreSQL may not be available in all locations.
+  [Click
+  here](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=postgresql,container-instances&regions=all)
+  to check availability.)
+- **Name**: enter a unique name for the deployment, this name is used for
+  provisioning a DNS label for the container, so it needs to be globally unique.
+- **Postgres Version**: choose a version.
+- **Database SKU Tier**: choose the SKU tier for the PostgreSQL service.
+- **Database SKU Capacity**: choose the number of cores for the database.
+- **Database SKU Size in MB**: choose the storage size for database (in MB).
+- **Administrator Login Password**: enter a password for the database - minimum 8
+  characters, must include lowercase, uppercase and numbers.
+- **URL Encoded Admin Password**: if the admin password contains special
+  characters (like `#`, `%`, `$` etc.), URL encode them (like `%40` for `@`) and
+  enter here. If there are no special characters, just re-type the password.
+
+![Azure Portal screenshot](https://storage.googleapis.com/graphql-engine-cdn.hasura.io/main-repo/img/azure_arm_aci_template.png)
+
+Once all entries are filled, agree to the terms and click the `Purchase` button.
+
+The deployment will start now.
+
+Click on the Notification Bell icon on the header bar and then click on
+Deployment in Progress link.
+
+On this screen, you can see progress for various steps in the deployment.
+
+![Azure Portal deployment screen
+screenshot](https://storage.googleapis.com/graphql-engine-cdn.hasura.io/main-repo/img/azure_arm_aci_deployment_screen.png)
+
+Once all steps are completed, click on the `Outputs` link on the sidebar.
+
+![Azure Portal deployment output
+screenshot](https://storage.googleapis.com/graphql-engine-cdn.hasura.io/main-repo/img/azure_arm_aci_deployment_output.png)
+
+The FQDN and IP address are shown in this screen. Copy the FQDN and paste it into
+a browser. It will open up the Hasura GraphQL Engine console.
+
+```
+http://hasura-graphql-engine.centralindia.azurecontainer.io
+```
+
+![Console](https://storage.googleapis.com/graphql-engine-cdn.hasura.io/main-repo/img/azure_arm_aci_console_graphiql.png)
+
+## Next steps
+
+- [Building your schema](https://docs.hasura.io/1.0/graphql/manual/schema/index.html)
+- [GraphQL Queries](https://docs.hasura.io/1.0/graphql/manual/queries/index.html)
+- [GraphQL Mutations](https://docs.hasura.io/1.0/graphql/manual/mutations/index.html)
+- [GraphQL Subscriptions](https://docs.hasura.io/1.0/graphql/manual/subscriptions/index.html)
+- [Event Triggers](https://docs.hasura.io/1.0/graphql/manual/event-triggers/index.html)
+- [Authentication/Access control](https://docs.hasura.io/1.0/graphql/manual/event-triggers/index.html)
+- [Database Migrations](https://docs.hasura.io/1.0/graphql/manual/migrations/index.html)
+- [Guides/Tutorials/Resources](https://docs.hasura.io/1.0/graphql/manual/guides/index.html)

install-manifests/azure-resource-manager/azuredeploy.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "name": {
+      "defaultValue": null,
+      "type": "string",
+      "minLength": 5,
+      "maxLength": 63,
+      "metadata": {
+        "description": "Unique name for the deployment, used as the DNS label also."
+      }
+    },
+    "postgresVersion": {
+      "type": "string",
+      "defaultValue": "10",
+      "allowedValues": [
+        "10",
+        "9.6",
+        "9.5"
+      ],
+      "metadata": {
+        "description": "Version of PostgreSQL Server to be provisioned."
+      }
+    },
+    "databaseSKUTier": {
+      "type": "string",
+      "allowedValues": [
+        "Basic",
+        "GeneralPurpose",
+        "MemoryOptimized"
+      ],
+      "defaultValue": "GeneralPurpose",
+      "metadata": {
+        "description": "Azure database for PostgreSQL pricing SKU tier."
+      }
+    },
+    "databaseSKUCapacity": {
+      "type": "int",
+      "allowedValues": [
+        2,
+        4,
+        8,
+        16,
+        32
+      ],
+      "defaultValue": 2,
+      "metadata": {
+        "description": "Azure database for PostgreSQL SKU capacity - number of cores."
+      }
+    },
+    "databaseSKUSizeInMB": {
+      "type": "int",
+      "minValue": 5210,
+      "maxValue": 4096000,
+      "defaultValue": 10240,
+      "metadata": {
+        "description": "Azure database for PostgreSQL SKU storage size."
+      }
+    },
+    "administratorLoginPassword": {
+      "type": "securestring",
+      "defaultValue": null,
+      "minLength": 8,
+      "maxLength": 128,
+      "metadata": {
+        "description": "Administrator password for Postgres. Must be at least 8 characters in length, must contain characters from three of the following categories – English uppercase letters, English lowercase letters, numbers (0-9), and non-alphanumeric characters (!, $, #, %, etc.)."
+      }
+    },
+    "urlEncodedAdminPassword": {
+      "type": "securestring",
+      "defaultValue": null,
+      "minLength": 8,
+      "maxLength": 128,
+      "metadata": {
+        "description": "If you have special characters in the password (!, $, #, %, etc.), URL encode and paste it here. Otherwise, just re-type the password."
+      }
+    }
+  },
+  "variables": {
+    "serverName": "[concat(parameters('name'), '-pg-server')]",
+    "adminUser": "hasura",
+    "dbName": "hasura",
+    "firewallRuleName": "allow-all-azure-firewall-rule",
+    "containerGroupName": "[concat(parameters('name'), '-container-group')]",
+    "containerName": "hasura-graphql-engine",
+    "containerImage": "hasura/graphql-engine:v1.0.0-alpha28"
+  },
+  "resources": [
+    {
+      "name": "[variables('serverName')]",
+      "location": "[resourceGroup().location]",
+      "type": "Microsoft.DBforPostgreSQL/servers",
+      "apiVersion": "2017-12-01",
+      "properties": {
+        "createMode": "Default",
+        "version": "[parameters('postgresVersion')]",
+        "administratorLogin": "hasura",
+        "administratorLoginPassword": "[parameters('administratorLoginPassword')]",
+        "storageProfile": {
+          "storageMB": "[parameters('databaseSKUSizeInMB')]"
+        }
+      },
+      "sku": {
+        "name": "[concat(if(equals(parameters('databaseSKUTier'), 'Basic'), 'B', if(equals(parameters('databaseSKUTier'), 'GeneralPurpose'), 'GP', if(equals(parameters('databaseSKUTier'), 'MemoryOptimized'), 'MO', 'X'))), '_Gen5_', parameters('databaseSKUCapacity') )]",
+        "tier": "[parameters('databaseSKUTier')]",
+        "capacity": "[parameters('databaseSKUCapacity')]",
+        "size": "[parameters('databaseSKUSizeInMB')]",
+        "family": "Gen5"
+      },
+      "resources": [
+        {
+          "name": "[variables('dbName')]",
+          "type": "databases",
+          "apiVersion": "2017-12-01",
+          "properties": {
+            "charset": "UTF8",
+            "collation": "English_United States.1252"
+          },
+          "dependsOn": [
+            "[resourceId('Microsoft.DBforPostgreSQL/servers', variables('serverName'))]"
+          ]
+        },
+        {
+          "type": "firewallRules",
+          "name": "[variables('firewallRuleName')]",
+          "apiVersion": "2017-12-01",
+          "properties": {
+            "startIpAddress": "0.0.0.0",
+            "endIpAddress": "0.0.0.0"
+          },
+          "dependsOn": [
+            "[resourceId('Microsoft.DBforPostgreSQL/servers', variables('serverName'))]"
+          ]
+
+        }
+      ]
+    },
+    {
+      "type": "Microsoft.ContainerInstance/containerGroups",
+      "name": "[variables('containerGroupName')]",
+      "apiVersion": "2018-06-01",
+      "location": "[resourceGroup().location]",
+      "properties": {
+        "containers": [
+          {
+            "name": "[variables('containerName')]",
+            "properties": {
+              "image": "[variables('containerImage')]",
+              "command": [
+                "graphql-engine",
+                "serve",
+                "--server-port",
+                "80"
+              ],
+              "ports": [
+                {
+                  "protocol": "TCP",
+                  "port": 80
+                }
+              ],
+              "environmentVariables": [
+                {
+                  "name": "HASURA_GRAPHQL_DATABASE_URL",
+                  "secureValue": "[concat('postgres://', variables('adminUser'), '%40', variables('serverName'), ':', parameters('urlEncodedAdminPassword'), '@', reference(resourceId('Microsoft.DBforPostgreSQL/servers', variables('serverName'))).fullyQualifiedDomainName, ':5432/', variables('dbName'))]"
+                }
+              ],
+              "resources": {
+                "requests": {
+                  "memoryInGB": 1,
+                  "cpu": 1
+                }
+              }
+            }
+          }
+        ],
+        "restartPolicy": "Always",
+        "ipAddress": {
+          "ports": [
+            {
+              "protocol": "TCP",
+              "port": 80
+            }
+          ],
+          "type": "Public",
+          "dnsNameLabel": "[parameters('name')]"
+        },
+        "osType": "Linux"
+      },
+      "dependsOn": [
+        "[resourceId('Microsoft.DBforPostgreSQL/servers', variables('serverName'))]"
+      ]
+    }
+  ],
+  "outputs": {
+    "fqdn": {
+      "value": "[reference(resourceId('Microsoft.ContainerInstance/containerGroups', variables('containerGroupName'))).ipAddress.fqdn]",
+      "type": "string"
+    },
+    "ipaddress": {
+      "value": "[reference(resourceId('Microsoft.ContainerInstance/containerGroups', variables('containerGroupName'))).ipAddress.ip]",
+      "type": "string"
+    }
+  }
+}

install-manifests/azure-resource-manager/azuredeploy.parameters.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "name": {
+      "value": ""
+    },
+    "administratorLoginPassword": {
+      "value": ""
+    },
+    "urlEncodedAdminPassword": {
+      "value": ""
+    }
+  }
+}