Skip to content

Commit a0e2e3c

Browse files
nicole-brewernicole-brewer
committedJul 8, 2024
Added deploying with docker instructions to 04a
1 parent df1dc6b commit a0e2e3c

File tree

2 files changed

+154
-2
lines changed

2 files changed

+154
-2
lines changed
 

‎04a_deployment_serverside.ipynb

Lines changed: 132 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,137 @@
9696
"source": [
9797
"## Running Voilà in a Docker Container\n",
9898
"\n",
99-
"# Maybe Nicole can add some notes here?!?"
99+
"In this section we will learn how to deploy Voila using Docker. We will use an example dashboard from a template project - [rcpurdue/nbtmpl](https://github.com/rcpurdue/nbtmpl) - that inspired the dashboard we just built in this tutorial. \n",
100+
"\n",
101+
"> NOTE: The Docker build process is time consuming, so **we do not expect you to actually run through the build process**. Rather, we want to familiarize you with your deployment options so you can learn more on your own time. That said, the following is a working example and we will leave you with an exercise if you want to try it for yourself with the codebase you have created in this tutorial. \n",
102+
"\n",
103+
"**Docker** is a platform that uses containerization to allow developers to package applications and their dependencies into portable containers that can run consistently across different environments. Docker can be used with service providers to quickly deploy single servers hosting Voila. \n",
104+
"\n",
105+
"**Dockerfile** is a script containing a series of instructions on how to build a Docker image, specifying the base image, dependencies, configurations, and the application itself. \n",
106+
"\n",
107+
"**Our goal** here is to create and understand a standalone Dockerfile that automatically deploys our Voila server.\n",
108+
"\n",
109+
"Note that the Dockerfile and build command are written in such a way that having a local clone of the entire tutorial repository is not required. Rather, the repository is cloned by Docker upon build. That is so that if we just want to deploy the our app with a service provider, we need only provide a Dockerfile. "
110+
]
111+
},
112+
{
113+
"cell_type": "markdown",
114+
"id": "879ea8e0-5cfc-4f48-962b-e167006e7f94",
115+
"metadata": {},
116+
"source": [
117+
"### Dockerfile "
118+
]
119+
},
120+
{
121+
"cell_type": "code",
122+
"execution_count": null,
123+
"id": "a1167fdd-3f3e-4ab8-b402-f06bfe08088d",
124+
"metadata": {},
125+
"outputs": [],
126+
"source": [
127+
"# %load Dockerfile"
128+
]
129+
},
130+
{
131+
"cell_type": "markdown",
132+
"id": "532d1e5f-2607-42ec-a8a1-0f22dc041487",
133+
"metadata": {},
134+
"source": [
135+
"### Docker Build Command\n",
136+
"\n",
137+
"The following command is used to build a Docker image from a Dockerfile.\n",
138+
"\n",
139+
"```bash\n",
140+
"docker build -t voila-dashboard --build-arg repourl=https://github.com/Jupyter4Science/scipy2024-jupyter-widgets-tutorial.git .\n",
141+
"```\n",
142+
"\n",
143+
"`-t voila-dashboard`: The -t option tags the image with a name. In this case, the image is tagged as voila-dashboard. This tag makes it easier to reference the image later, such as when running a container.\n",
144+
"\n",
145+
"`--build-arg repourl=https://github.com/rcpurdue/nbtmpl.git`: The --build-arg option allows you to pass build-time variables to the Dockerfile. Here, repourl is set to https://github.com/rcpurdue/nbtmpl.git. This argument is used in the Dockerfile to specify the repository URL that should be cloned during the build process.\n",
146+
"\n",
147+
"`.` (dot): The dot at the end of the command specifies the build context, which is the current directory. Docker will use the files in this directory, including the Dockerfile, to build the image.\n"
148+
]
149+
},
150+
{
151+
"cell_type": "markdown",
152+
"id": "9acd0c03-af60-459f-b61f-5f33db821d61",
153+
"metadata": {},
154+
"source": [
155+
"### Takehome Exercise\n",
156+
"\n",
157+
"**Goal**: Build our Dockerfile and run the image on our local machine. Access our Voila app in our browser. \n",
158+
"\n",
159+
"1. [Install Docker](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository). Note that you may need admin access to run Docker commands.\n",
160+
"2. Start a command line (terminal) session.\n",
161+
"3. Make sure Docker by executing `docker info`.\n",
162+
"4. Use command explained above to build the Docker image labeled with the tag \"voila-dashboard\""
163+
]
164+
},
165+
{
166+
"cell_type": "code",
167+
"execution_count": null,
168+
"id": "01f88ddd-f6ef-4151-a157-aa2506c1170a",
169+
"metadata": {},
170+
"outputs": [],
171+
"source": [
172+
"# DO NOT UNCOMMENT: unless you have Docker already installed and you want to build a container\n",
173+
"\n",
174+
"# docker build -t voila-dashboard --build-arg repourl=https://github.com/Jupyter4Science/scipy2024-jupyter-widgets-tutorial.git ."
175+
]
176+
},
177+
{
178+
"cell_type": "markdown",
179+
"id": "b3137076-bf6e-4e6e-ac0e-532450a9039b",
180+
"metadata": {},
181+
"source": [
182+
"5. Run the image called \"voila-dashboard\" "
183+
]
184+
},
185+
{
186+
"cell_type": "code",
187+
"execution_count": null,
188+
"id": "d0cb8afc-8ff4-4231-aacd-d19fd2efe312",
189+
"metadata": {},
190+
"outputs": [],
191+
"source": [
192+
"# DO NOT UNCOMMENT: unless you have Docker already installed and you want to build a container\n",
193+
"\n",
194+
"# docker run -p 8866:8866 voila-dashboard"
195+
]
196+
},
197+
{
198+
"cell_type": "markdown",
199+
"id": "9ac06df7-e55e-451e-8590-fc9fcd40c82e",
200+
"metadata": {},
201+
"source": [
202+
"The `-p` flag in the docker run command is used to publish a container's port to the host machine, allowing external access to services running inside the container. \n",
203+
"\n",
204+
"In the command `docker run -p 8866:8866 voila-dashboard`, the `-p 8866:8866` part maps port 8866 of the host machine to port 8866 of the container. This makes the next step possible.\n",
205+
"\n",
206+
"6. Open your Voila app in your browser by visiting http://localhost:8866."
207+
]
208+
},
209+
{
210+
"cell_type": "markdown",
211+
"id": "db188c9f-a5cf-4e18-ac84-3eec45bf2f21",
212+
"metadata": {},
213+
"source": [
214+
"### High-Level Instructions for Deploying Voila with a Service Provider\n",
215+
"\n",
216+
"If you wish to achieve the same result with a service provider, things get a little more tricky because of the firewalls and permissions that need to be set up to access Voila through the public IP. Here are some general requirements that may look different depending on the service or platform you are working on. \n",
217+
"\n",
218+
"#### Configure Security Groups/Firewalls\n",
219+
"Set up security groups or firewall rules to allow inbound traffic on the port you will be using (e.g., port 8866 for Voila). Ensure that SSH access (port 22) is also allowed so you can manage your server.\n",
220+
"\n",
221+
"#### Create and Attach a Floating Public IP\n",
222+
"Allocate a floating public IP address for your virtual machine. It may be neccesary to attach the allocated public IP to your virtual machine instance to enable access from the internet.\n",
223+
"\n",
224+
"#### Upload a Dockerfile or transfer to your server\n",
225+
"Some composible services support starting images directly from Dockerfiles, while others may require you to log into the node to install Docker and build your container for yourself.\n",
226+
"\n",
227+
"#### Access Your Application\n",
228+
"\n",
229+
"Once the Docker container is running and ports are properly configured, you can access your Voila dashboard through the public IP address of your virtual machine (e.g., `http://<public-ip>:8866`)."
100230
]
101231
},
102232
{
@@ -216,7 +346,7 @@
216346
],
217347
"metadata": {
218348
"kernelspec": {
219-
"display_name": "python3",
349+
"display_name": "Python 3 (ipykernel)",
220350
"language": "python",
221351
"name": "python3"
222352
}

‎Dockerfile

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Use the Jupyter SciPy notebook as the base image
2+
FROM jupyter/scipy-notebook
3+
4+
# Define a build argument to pass the repository URL
5+
ARG repourl
6+
7+
# Install additional packages and clone the specified repository
8+
# - voila: A tool to convert Jupyter notebooks into standalone web applications
9+
# - jupyterthemes: A set of custom themes for Jupyter notebooks
10+
# - git clone: Clone the repository from the provided URL into the 'target' directory
11+
RUN conda install -c conda-forge voila jupyterthemes \
12+
&& git clone --depth 1 $repourl target
13+
14+
# Set the working directory to the cloned repository
15+
WORKDIR /home/jovyan/target
16+
17+
# Define the default command to run when the container starts
18+
# - voila: Serve the Jupyter notebook as a web application
19+
# - notebook.ipynb: The notebook to be served
20+
# - --no-browser: Do not open a web browser on the host machine
21+
# - --Voila.ip: Bind the Voila server to all available IP addresses (0.0.0.0)
22+
CMD ["voila", "notebook.ipynb", "--no-browser", "--Voila.ip", "0.0.0.0"]

0 commit comments

Comments
 (0)
Please sign in to comment.