"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[9789],{3905:(e,t,a)=>{a.d(t,{Zo:()=>u,kt:()=>m});var r=a(67294);function o(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function n(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,r)}return a}function i(e){for(var t=1;t<arguments.length;t++){var a=null!=arguments[t]?arguments[t]:{};t%2?n(Object(a),!0).forEach((function(t){o(e,t,a[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(a)):n(Object(a)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(a,t))}))}return e}function l(e,t){if(null==e)return{};var a,r,o=function(e,t){if(null==e)return{};var a,r,o={},n=Object.keys(e);for(r=0;r<n.length;r++)a=n[r],t.indexOf(a)>=0||(o[a]=e[a]);return o}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(r=0;r<n.length;r++)a=n[r],t.indexOf(a)>=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(o[a]=e[a])}return o}var p=r.createContext({}),s=function(e){var t=r.useContext(p),a=t;return e&&(a="function"==typeof e?e(t):i(i({},t),e)),a},u=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},c="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},k=r.forwardRef((function(e,t){var a=e.components,o=e.mdxType,n=e.originalType,p=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),c=s(a),k=o,m=c["".concat(p,".").concat(k)]||c[k]||d[k]||n;return a?r.createElement(m,i(i({ref:t},u),{},{components:a})):r.createElement(m,i({ref:t},u))}));function m(e,t){var a=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var n=a.length,i=new Array(n);i[0]=k;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l[c]="string"==typeof e?e:o,i[1]=l;for(var s=2;s<n;s++)i[s]=a[s];return r.createElement.apply(null,i)}return r.createElement.apply(null,a)}k.displayName="MDXCreateElement"},31357:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>u,contentTitle:()=>p,default:()=>m,frontMatter:()=>l,metadata:()=>s,toc:()=>c});var r=a(87462),o=a(63366),n=(a(67294),a(3905)),i=["components"],l={id:"tutorial-jupyter-docker",title:"Docker for Jupyter Notebook tutorials",sidebar_label:"Docker for tutorials"},p=void 0,s={unversionedId:"tutorials/tutorial-jupyter-docker",id:"tutorials/tutorial-jupyter-docker",title:"Docker for Jupyter Notebook tutorials",description:"\x3c!--",source:"@site/docs/latest/tutorials/tutorial-jupyter-docker.md",sourceDirName:"tutorials",slug:"/tutorials/tutorial-jupyter-docker",permalink:"/docs/latest/tutorials/tutorial-jupyter-docker",draft:!1,tags:[],version:"current",frontMatter:{id:"tutorial-jupyter-docker",title:"Docker for Jupyter Notebook tutorials",sidebar_label:"Docker for tutorials"},sidebar:"docs",previous:{title:"Jupyter Notebook tutorials",permalink:"/docs/latest/tutorials/tutorial-jupyter-index"},next:{title:"JDBC connector",permalink:"/docs/latest/tutorials/tutorial-jdbc"}},u={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Launch the Docker containers",id:"launch-the-docker-containers",level:2},{value:"Start only the Jupyter container",id:"start-only-the-jupyter-container",level:3},{value:"Start Jupyter and Druid",id:"start-jupyter-and-druid",level:3},{value:"Start Jupyter, Druid, and Kafka",id:"start-jupyter-druid-and-kafka",level:3},{value:"Start Kafka and Jupyter",id:"start-kafka-and-jupyter",level:3},{value:"Update image from Docker Hub",id:"update-image-from-docker-hub",level:3},{value:"Use locally built image",id:"use-locally-built-image",level:3},{value:"Access Jupyter-based tutorials",id:"access-jupyter-based-tutorials",level:2},{value:"View the Druid web console",id:"view-the-druid-web-console",level:2},{value:"Stop Docker containers",id:"stop-docker-containers",level:2},{value:"Tutorial setup without using Docker",id:"tutorial-setup-without-using-docker",level:2},{value:"Tutorial setup for ARM-based devices",id:"tutorial-setup-for-arm-based-devices",level:2},{value:"Learn more",id:"learn-more",level:2}],d={toc:c},k="wrapper";function m(e){var t=e.components,a=(0,o.Z)(e,i);return(0,n.kt)(k,(0,r.Z)({},d,a,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,"Apache Druid provides a custom Jupyter container that contains the prerequisites\nfor all ",(0,n.kt)("a",{parentName:"p",href:"/docs/latest/tutorials/tutorial-jupyter-index"},"Jupyter-based Druid tutorials"),", as well as all of the tutorials themselves.\nYou can run the Jupyter container, as well as containers for Druid and Apache Kafka,\nusing the Docker Compose file provided in the Druid GitHub repository."),(0,n.kt)("p",null,"You can run the following combination of applications:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"#start-only-the-jupyter-container"},"Jupyter only")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"#start-jupyter-and-druid"},"Jupyter and Druid")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"#start-jupyter-druid-and-kafka"},"Jupyter, Druid, and Kafka")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"#start-kafka-and-jupyter"},"Kafka and Jupyter"))),(0,n.kt)("h2",{id:"prerequisites"},"Prerequisites"),(0,n.kt)("p",null,"Jupyter in Docker requires that you have ",(0,n.kt)("strong",{parentName:"p"},"Docker")," and ",(0,n.kt)("strong",{parentName:"p"},"Docker Compose"),".\nWe recommend installing these through ",(0,n.kt)("a",{parentName:"p",href:"https://docs.docker.com/desktop/"},"Docker Desktop"),"."),(0,n.kt)("p",null,"For ARM-based devices, see ",(0,n.kt)("a",{parentName:"p",href:"#tutorial-setup-for-arm-based-devices"},"Tutorial setup for ARM-based devices"),"."),(0,n.kt)("h2",{id:"launch-the-docker-containers"},"Launch the Docker containers"),(0,n.kt)("p",null,"You run Docker Compose to launch Jupyter and optionally Druid or Kafka.\nDocker Compose references the configuration in ",(0,n.kt)("inlineCode",{parentName:"p"},"docker-compose.yaml"),".\nRunning Druid in Docker also requires the ",(0,n.kt)("inlineCode",{parentName:"p"},"environment")," file, which\nsets the configuration properties for the Druid services.\nTo get started, download both ",(0,n.kt)("inlineCode",{parentName:"p"},"docker-compose.yaml")," and ",(0,n.kt)("inlineCode",{parentName:"p"},"environment")," from\n",(0,n.kt)("a",{parentName:"p",href:"https://github.com/apache/druid/blob/master/examples/quickstart/jupyter-notebooks/docker-jupyter/tutorial-jupyter-docker.zip"},(0,n.kt)("inlineCode",{parentName:"a"},"tutorial-jupyter-docker.zip")),"."),(0,n.kt)("p",null,"Alternatively, you can clone the ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/apache/druid"},"Apache Druid repo")," and\naccess the files in ",(0,n.kt)("inlineCode",{parentName:"p"},"druid/examples/quickstart/jupyter-notebooks/docker-jupyter"),"."),(0,n.kt)("h3",{id:"start-only-the-jupyter-container"},"Start only the Jupyter container"),(0,n.kt)("p",null,"If you already have Druid running locally or on another machine, you can run the Docker containers for Jupyter only.\nIn the same directory as ",(0,n.kt)("inlineCode",{parentName:"p"},"docker-compose.yaml"),", start the application:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose --profile jupyter up -d\n")),(0,n.kt)("p",null,"The Docker Compose file assigns ",(0,n.kt)("inlineCode",{parentName:"p"},"8889")," for the Jupyter port.\nYou can override the port number by setting the ",(0,n.kt)("inlineCode",{parentName:"p"},"JUPYTER_PORT")," environment variable before starting the Docker application."),(0,n.kt)("p",null,"If Druid is running local to the same machine as Jupyter, open the tutorial and set the ",(0,n.kt)("inlineCode",{parentName:"p"},"host")," variable to ",(0,n.kt)("inlineCode",{parentName:"p"},"host.docker.internal")," before starting. For example:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-python"},'host = "host.docker.internal"\n')),(0,n.kt)("h3",{id:"start-jupyter-and-druid"},"Start Jupyter and Druid"),(0,n.kt)("p",null,"Running Druid in Docker requires the ",(0,n.kt)("inlineCode",{parentName:"p"},"environment")," file as well as an environment variable named ",(0,n.kt)("inlineCode",{parentName:"p"},"DRUID_VERSION"),",\nwhich determines the version of Druid to use. The Druid version references the Docker tag to pull from the\n",(0,n.kt)("a",{parentName:"p",href:"https://hub.docker.com/r/apache/druid/tags"},"Apache Druid Docker Hub"),"."),(0,n.kt)("p",null,"In the same directory as ",(0,n.kt)("inlineCode",{parentName:"p"},"docker-compose.yaml")," and ",(0,n.kt)("inlineCode",{parentName:"p"},"environment"),", start the application:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"DRUID_VERSION=28.0.0 docker compose --profile druid-jupyter up -d\n")),(0,n.kt)("h3",{id:"start-jupyter-druid-and-kafka"},"Start Jupyter, Druid, and Kafka"),(0,n.kt)("p",null,"Running Druid in Docker requires the ",(0,n.kt)("inlineCode",{parentName:"p"},"environment")," file as well as the ",(0,n.kt)("inlineCode",{parentName:"p"},"DRUID_VERSION")," environment variable."),(0,n.kt)("p",null,"In the same directory as ",(0,n.kt)("inlineCode",{parentName:"p"},"docker-compose.yaml")," and ",(0,n.kt)("inlineCode",{parentName:"p"},"environment"),", start the application:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"DRUID_VERSION=28.0.0 docker compose --profile all-services up -d\n")),(0,n.kt)("h3",{id:"start-kafka-and-jupyter"},"Start Kafka and Jupyter"),(0,n.kt)("p",null,"If you already have Druid running externally, such as an existing cluster or a dedicated infrastructure for Druid, you can run the Docker containers for Kafka and Jupyter only."),(0,n.kt)("p",null,"In the same directory as ",(0,n.kt)("inlineCode",{parentName:"p"},"docker-compose.yaml")," and ",(0,n.kt)("inlineCode",{parentName:"p"},"environment"),", start the application:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"DRUID_VERSION=28.0.0 docker compose --profile kafka-jupyter up -d\n")),(0,n.kt)("p",null,"If you have an external Druid instance running on a different machine than the one hosting the Docker Compose environment, change the ",(0,n.kt)("inlineCode",{parentName:"p"},"host")," variable in the notebook tutorial to the hostname or address of the machine where Druid is running."),(0,n.kt)("p",null,"If Druid is running local to the same machine as Jupyter, open the tutorial and set the ",(0,n.kt)("inlineCode",{parentName:"p"},"host")," variable to ",(0,n.kt)("inlineCode",{parentName:"p"},"host.docker.internal")," before starting. For example:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-python"},'host = "host.docker.internal"\n')),(0,n.kt)("p",null,"To enable Druid to ingest data from Kafka within the Docker Compose environment, update the ",(0,n.kt)("inlineCode",{parentName:"p"},"bootstrap.servers")," property in the Kafka ingestion spec to ",(0,n.kt)("inlineCode",{parentName:"p"},"localhost:9094")," before ingesting. For reference, see ",(0,n.kt)("a",{parentName:"p",href:"/docs/latest/development/extensions-core/kafka-supervisor-reference#consumer-properties"},"Consumer properties"),"."),(0,n.kt)("h3",{id:"update-image-from-docker-hub"},"Update image from Docker Hub"),(0,n.kt)("p",null,"If you already have a local cache of the Jupyter image, you can update the image before running the application using the following command:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose pull jupyter\n")),(0,n.kt)("h3",{id:"use-locally-built-image"},"Use locally built image"),(0,n.kt)("p",null,"The default Docker Compose file pulls the custom Jupyter Notebook image from a third party Docker Hub.\nIf you prefer to build the image locally from the official source, do the following:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},"Clone the Apache Druid repository."),(0,n.kt)("li",{parentName:"ol"},"Navigate to ",(0,n.kt)("inlineCode",{parentName:"li"},"examples/quickstart/jupyter-notebooks/docker-jupyter"),"."),(0,n.kt)("li",{parentName:"ol"},"Start the services using ",(0,n.kt)("inlineCode",{parentName:"li"},"-f docker-compose-local.yaml")," in the ",(0,n.kt)("inlineCode",{parentName:"li"},"docker compose")," command. For example:")),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"DRUID_VERSION=28.0.0 docker compose --profile all-services -f docker-compose-local.yaml up -d\n")),(0,n.kt)("h2",{id:"access-jupyter-based-tutorials"},"Access Jupyter-based tutorials"),(0,n.kt)("p",null,"The following steps show you how to access the Jupyter notebook tutorials from the Docker container.\nAt startup, Docker creates and mounts a volume to persist data from the container to your local machine.\nThis way you can save your work completed within the Docker container."),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Navigate to the notebooks at http://localhost:8889."),(0,n.kt)("admonition",{parentName:"li",type:"info"},(0,n.kt)("p",{parentName:"admonition"}," If you set ",(0,n.kt)("inlineCode",{parentName:"p"},"JUPYTER_PORT")," to another port number, replace ",(0,n.kt)("inlineCode",{parentName:"p"},"8889")," with the value of the Jupyter port."))),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Select a tutorial. If you don't plan to save your changes, you can use the notebook directly as is. Otherwise, continue to the next step.")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Optional: To save a local copy of your tutorial work,\nselect ",(0,n.kt)("strong",{parentName:"p"},"File > Save as...")," from the navigation menu. Then enter ",(0,n.kt)("inlineCode",{parentName:"p"},"work/<notebook name>.ipynb"),".\nIf the notebook still displays as read only, you may need to refresh the page in your browser.\nAccess the saved files in the ",(0,n.kt)("inlineCode",{parentName:"p"},"notebooks")," folder in your local working directory."))),(0,n.kt)("h2",{id:"view-the-druid-web-console"},"View the Druid web console"),(0,n.kt)("p",null,"To access the Druid web console in Docker, go to http://localhost:8888/unified-console.html.\nUse the web console to view datasources and ingestion tasks that you create in the tutorials."),(0,n.kt)("h2",{id:"stop-docker-containers"},"Stop Docker containers"),(0,n.kt)("p",null,"Shut down the Docker application using the following command:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose down -v\n")),(0,n.kt)("h2",{id:"tutorial-setup-without-using-docker"},"Tutorial setup without using Docker"),(0,n.kt)("p",null,"To use the Jupyter Notebook-based tutorials without using Docker, do the following:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Clone the Apache Druid repo, or download the ",(0,n.kt)("a",{parentName:"p",href:"/docs/latest/tutorials/tutorial-jupyter-index#tutorials"},"tutorials"),"\nas well as the ",(0,n.kt)("a",{parentName:"p",href:"/docs/latest/tutorials/tutorial-jupyter-index#python-api-for-druid"},"Python client for Druid"),".")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Install the prerequisite Python packages with the following commands:"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"# Install requests\npip install requests\n")),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"# Install JupyterLab\npip install jupyterlab\n\n# Install Jupyter Notebook\npip install notebook\n")),(0,n.kt)("p",{parentName:"li"},"Individual notebooks may list additional packages you need to install to complete the tutorial.")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"In your Druid source repo, install ",(0,n.kt)("inlineCode",{parentName:"p"},"druidapi")," with the following commands:"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"cd examples/quickstart/jupyter-notebooks/druidapi\npip install .\n"))),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Start Jupyter, in the same directory as the tutorials, using either JupyterLab or Jupyter Notebook:"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"# Start JupyterLab on port 3001\njupyter lab --port 3001\n\n# Start Jupyter Notebook on port 3001\njupyter notebook --port 3001\n"))),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Start Druid. You can use the ",(0,n.kt)("a",{parentName:"p",href:"/docs/latest/tutorials/"},"Quickstart (local)")," instance. The tutorials\nassume that you are using the quickstart, so no authentication or authorization\nis expected unless explicitly mentioned."),(0,n.kt)("p",{parentName:"li"},"If you contribute to Druid, and work with Druid integration tests, you can use a test cluster.\nAssume you have an environment variable, ",(0,n.kt)("inlineCode",{parentName:"p"},"DRUID_DEV"),", which identifies your Druid source repo."),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"cd $DRUID_DEV\n./it.sh build\n./it.sh image\n./it.sh up <category>\n")),(0,n.kt)("p",{parentName:"li"},"Replace ",(0,n.kt)("inlineCode",{parentName:"p"},"<category>")," with one of the available integration test categories. See the integration\ntest ",(0,n.kt)("inlineCode",{parentName:"p"},"README.md")," for details."))),(0,n.kt)("p",null,"You should now be able to access and complete the tutorials."),(0,n.kt)("h2",{id:"tutorial-setup-for-arm-based-devices"},"Tutorial setup for ARM-based devices"),(0,n.kt)("p",null,"For ARM-based devices, follow this setup to start Druid externally, while keeping Kafka and Jupyter within the Docker Compose environment:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Start Druid using the ",(0,n.kt)("inlineCode",{parentName:"p"},"start-druid")," script. You can follow ",(0,n.kt)("a",{parentName:"p",href:"/docs/latest/tutorials/"},"Quickstart (local)")," instructions. The tutorials\nassume that you are using the quickstart, so no authentication or authorization is expected unless explicitly mentioned.")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Start either Jupyter only or Jupyter and Kafka using the following commands in the same directory as ",(0,n.kt)("inlineCode",{parentName:"p"},"docker-compose.yaml")," and ",(0,n.kt)("inlineCode",{parentName:"p"},"environment"),":"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"# Start only Jupyter\ndocker compose --profile jupyter up -d\n\n# Start Kafka and Jupyter\nDRUID_VERSION=28.0.0 docker compose --profile kafka-jupyter up -d\n"))),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"If Druid is running local to the same machine as Jupyter, open the tutorial and set the ",(0,n.kt)("inlineCode",{parentName:"p"},"host")," variable to ",(0,n.kt)("inlineCode",{parentName:"p"},"host.docker.internal")," before starting. For example:"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-python"},'host = "host.docker.internal"\n'))),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"If using Kafka to handle the data stream that will be ingested into Druid and Druid is running local to the same machine, update the consumer property ",(0,n.kt)("inlineCode",{parentName:"p"},"bootstrap.servers")," to ",(0,n.kt)("inlineCode",{parentName:"p"},"localhost:9094"),"."))),(0,n.kt)("h2",{id:"learn-more"},"Learn more"),(0,n.kt)("p",null,"See the following topics for more information:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"/docs/latest/tutorials/tutorial-jupyter-index"},"Jupyter Notebook tutorials")," for the available Jupyter Notebook-based tutorials for Druid"),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"/docs/latest/tutorials/docker"},"Tutorial: Run with Docker")," for running Druid from a Docker container")))}m.isMDXComponent=!0}}]);