add docker tutorial

2 files changed, 215 insertions, 0 deletions

diff --git a/python/vespa/docs/sphinx/source/create-and-deploy-vespa-docker.ipynb b/python/vespa/docs/sphinx/source/create-and-deploy-vespa-docker.ipynb
new file mode 100644
index 00000000000..13e74aa173d
--- /dev/null
+++ b/python/vespa/docs/sphinx/source/create-and-deploy-vespa-docker.ipynb
@@ -0,0 +1,214 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Deploy Vespa apps to Docker\n",
+    "\n",
+    "> Python API to deploy Vespa applications to Docker containers."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This tutorial illustrate how to deploy a Vespa application to a Docker container in your local machine. It is required to have Docker installed in the machine you are running this tutorial from. For that reason we cannot run this tutorial in Google Colab as Docker is not available on their standard runtime machines."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Application package API"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We first create a `Document` instance containing the `Field`s that we want to store in the app. In this case we will keep the application simple and only feed a unique `id`, `title` and `body` of the MS MARCO documents."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vespa.package import Document, Field\n",
+    "\n",
+    "document = Document(\n",
+    "    fields=[\n",
+    "        Field(name = \"id\", type = \"string\", indexing = [\"attribute\", \"summary\"]),\n",
+    "        Field(name = \"title\", type = \"string\", indexing = [\"index\", \"summary\"], index = \"enable-bm25\"),\n",
+    "        Field(name = \"body\", type = \"string\", indexing = [\"index\", \"summary\"], index = \"enable-bm25\")        \n",
+    "    ]\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The complete `Schema` of our application will be named `msmarco` and contains the `Document` instance that we defined above, the default `FieldSet` indicates that queries will look for matches by searching both in the titles and bodies of the documents. The default `RankProfile` indicates that all the matched documents will be ranked by the `nativeRank` expression involving the title and the body of the matched documents."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vespa.package import Schema, FieldSet, RankProfile\n",
+    "\n",
+    "msmarco_schema = Schema(\n",
+    "    name = \"msmarco\", \n",
+    "    document = document, \n",
+    "    fieldsets = [FieldSet(name = \"default\", fields = [\"title\", \"body\"])],\n",
+    "    rank_profiles = [RankProfile(name = \"default\", first_phase = \"nativeRank(title, body)\")]\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once the `Schema` is defined, all we have to do is to create our msmarco `ApplicationPackage`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vespa.package import ApplicationPackage\n",
+    "\n",
+    "app_package = ApplicationPackage(name = \"msmarco\", schema=msmarco_schema)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "At this point, `app_package` contains all the relevant information required to create our MS MARCO text search app. We now need to deploy it."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Deploy to a Docker container"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For the following to work you need to run this from a machine with Docker installed. We first create a `VespaDocker` instance based on the application package."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vespa.package import VespaDocker\n",
+    "\n",
+    "vespa_docker = VespaDocker(application_package=app_package)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We then call the `deploy` method and specify a `disk_folder`. Behind the scenes, `pyvespa` will write the Vespa config files and store them in the `disk_folder`, it will then run a Vespa engine Docker container and deploy those config files in the container."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "app = vespa_docker.deploy(disk_folder=\"/Users/username/sample_application\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The app variable above will hold a `Vespa` instance that will be used to connect and interact with our text search application. We can see the deployment message returned by the Vespa engine:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[\"Uploading application '/app/application' using http://localhost:19071/application/v2/tenant/default/session\",\n",
+       " \"Session 18 for tenant 'default' created.\",\n",
+       " 'Preparing session 18 using http://localhost:19071/application/v2/tenant/default/session/18/prepared',\n",
+       " \"WARNING: Host named 'msmarco' may not receive any config since it is not a canonical hostname. Disregard this warning when testing in a Docker container.\",\n",
+       " \"Session 18 for tenant 'default' prepared.\",\n",
+       " 'Activating session 18 using http://localhost:19071/application/v2/tenant/default/session/18/active',\n",
+       " \"Session 18 for tenant 'default' activated.\",\n",
+       " 'Checksum:   09203c16fa5f582b712711bb98932812',\n",
+       " 'Timestamp:  1598011224920',\n",
+       " 'Generation: 18',\n",
+       " '']"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "app.deployment_message"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Interact with the deployed application"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "From this point on you can interact with the deployed application the same way we did in the following tutorials:\n",
+    "* [How to connect with running Vespa instances](connect-to-vespa-instance.ipynb)\n",
+    "* [Build end-to-end Vespa apps and deploy to Vespa Cloud](create-and-deploy-vespa-cloud.ipynb)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "vespa",
+   "language": "python",
+   "name": "vespa"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/python/vespa/docs/sphinx/source/index.rst b/python/vespa/docs/sphinx/source/index.rst
index caea22ee800..03ef20c133e 100644
--- a/python/vespa/docs/sphinx/source/index.rst
+++ b/python/vespa/docs/sphinx/source/index.rst
@@ -40,6 +40,7 @@ by clicking on the badge at the top of the tutorial.
 
 - :doc:`connect-to-vespa-instance`
 - :doc:`create-and-deploy-vespa-cloud`
+- :doc:`create-and-deploy-vespa-docker`
 
 
 How-to guides