✨ (Section 4) Add short hands-on section on running Flask on Docker

Author: jslvtr

docs/docs-upcoming/04_docker_intro/01_project_overview/README.md

@@ -0,0 +1,29 @@
+# What is a Docker container?
+
+I'm sure you have heard of the term "Virtual Machine". A Virtual Machine is an emulation of an Operating System.
+
+This means that you can run a Windows Virtual Machine on a computer running Mac OS. When you do that, you can have the Windows Operating System running inside an app in your Mac.
+
+When you run a Virtual Machine, you can configure what hardware it has access to (e.g. 50% of the host's RAM, 2 CPU cores, etc).
+
+Docker containers are a bit different because they don't emulate an Operating System. They use the Operating System kernel of your computer, and run as a process within the host.
+
+Containers have their own storage and networking, but because they don't have to emulate the operating system and everything that entails, they are much more lightweight and efficient. Another benefit of containers is that their start-up time is very fast.
+
+Naturally, there's pros and cons to both. For example, you can't run a Windows Docker container if you are using Mac OS in your machine. You'd have to run a Windows Virtual Machine, and then run Docker containers in that, which isn't very efficient!
+
+:::caution
+Because Docker containers use your OS kernel, you can run Linux images in a Mac OS container.
+
+However, new Mac computers use a different CPU architecture (ARM), and this can pose problems in some cases. More on this later on!
+:::
+
+## What does a Docker container run?
+
+If you want to run your Flask app in a Docker container, you need to get (or create) a Docker image that has all the dependencies your Flask app uses:
+
+- Python
+- Dependencies from `requirements.txt`
+- Possibly nginx or gunicorn (more on this when we talk about deployment)
+
+Let's take a look at Docker images in the next lecture.

docs/docs-upcoming/04_docker_intro/README.md

@@ -0,0 +1,29 @@
+# What is a Docker image?
+
+A Docker image is a snapshot of source code, libraries, dependencies, tools, and everything else (except the Operating System kernel!) that a container needs to run.
+
+There are many pre-built images that you can use. For example, some come with Ubuntu (a Linux distribution). Others come with Ubuntu and Python already installed. You can also make your own images that already have Flask installed (as well as other dependencies your app needs).
+
+Creating a Docker image is straightforward (when you know how!). I'll guide you through how to do this in the next lecture, but bear with me for a second:
+
+```dockerfile
+FROM python:3.10
+WORKDIR /app
+COPY ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+COPY . .
+CMD ["gunicorn", "--bind", "0.0.0.0:80", "main:app"]
+```
+
+This is a `Dockerfile`, a definition of how to create a Docker image. Once you have this file, you can ask Docker to create the Docker image. Then, after creating the Docker image, you can ask Docker to run it as a container.
+
+In this `Dockerfile` you can see the first line: `FROM python:3.10`. This tells Docker to first download the `python:3.10` image (an image someone else already created), and once that image is created, run the following commands.
+
+The following commands are specific to our use case, and do things like install requirements, copy our source code into the image, and tell Docker what command to run when we start a container from this image.
+
+This separation between images and containers is interesting because once the image is created you can ship it across the internet and:
+
+- Share it with other developers.
+- Deploy it to servers.
+
+Plus once you've downloaded the image (which can take a while), starting a container from it is almost instant since there's very little work to do.

docs/docs/04_docker_intro/01_what_is_docker_container/README.md

@@ -0,0 +1,123 @@
+# How to run a Docker container
+
+## Install Docker Desktop
+
+Docker Desktop is an application to help you manage your images and containers. Download it and install it here: [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/).
+
+## Create your Docker image
+
+Next, download the REST API code from Section 3. You can download it here: LINK.
+
+If you want to use the code you wrote while following the videos, that's fine! Just make sure it works by running the Flask app locally and testing it with Insomnia REST Client or Postman.
+
+### Write the `Dockerfile`
+
+In your project folder (i.e. the same folder as `app.py`), we're going to write the Dockerfile.
+
+To do this, make a file called `Dockerfile`.
+
+:::caution
+Make sure the file is called `Dockerfile`, and not `Dockerfile.txt` or anything like that!
+:::
+
+Inside the `Dockerfile` we're going to write this:
+
+```dockerfile
+FROM python:3.10
+WORKDIR /app
+RUN pip install flask
+COPY . .
+CMD ["flask", "run", "--host", "0.0.0.0"]
+```
+
+Here's a quick breakdown of what each line does:
+
+1. `FROM python:3.10` uses the `python:3.10` image as a base.
+2. `WORKDIR /app` does it so everything we do in the Docker image will happen in the image's `/app` directory.
+3. `RUN pip install flask` runs a command in the image. Here the command is `pip install flask`, which is what we need to run our app.
+4. `COPY . .` is a bit cryptic! It copies everything in the current folder (so `app.py`) into the image's current folder (so `/app`).
+5. `CMD ["flask", "run", "--host", "0.0.0.0"]` tells the image what command to run when you start a container. Here the command is `flask run --host=0.0.0.0`.
+
+:::tip
+We need `--host=0.0.0.0` to make Docker be able to do port forwarding, as otherwise the Flask app will only be accessible within the container, but not outside the container.
+:::
+
+Now we need to create the Docker image.
+
+We do this with the `docker build` command in the terminal.
+
+:::caution
+Make sure to restart your terminal after installing Docker Desktop, so that you have access to the `docker` program in your terminal.
+:::
+
+Open a terminal (in VSCode that's CMD+J or CTRL+J), and run this command:
+
+```
+docker build -t rest-apis-flask-python .
+```
+
+The `-t rest-apis-flask-python` flag is optional, but tags the image, giving it a name. It can be handy for later! The final `.` at the end of the command is not a mistake; it tells the command _what_ to build. The `.` means "the current directory".
+
+This command can take a while to run as it needs to download the `python:3.10` image first. You should see quite a lot of output while the command runs.
+
+When the command is finished, you should see this (among other things):
+
+```
+ => [2/4] WORKDIR /app                                                                             0.4s
+ => [3/4] RUN pip install flask                                                                    2.9s
+ => [4/4] COPY . .                                                                                 0.0s
+ => exporting to image                                                                             0.1s
+ => => exporting layers                                                                            0.1s
+ => => writing image sha256:d9a68a03f868e74bca48567dfc9a0b702d1618941a71b77de12ff14e908ba155       0.0s
+ => => naming to docker.io/library/rest-apis-first-rest-api                                        0.0s
+```
+
+And now your image is built! You should be able to see it in the "Images" section of your Docker Desktop app.
+
+## Run the Docker container
+
+When we start a Docker container from this image, it will run the `flask run` command. Remember that by default, `flask run` starts a Flask app using port 5000.
+
+But the container's ports are not accessible from outside the container by default. We need to tell Docker that when we access a certain port in our computer, those requests and responses should be forwarded to a certain port in our container.
+
+So we'll run the container, but we must remember to a port (e.g. 5000) in our computer to port 5000 in the container
+
+To do so, run this command:
+
+```
+docker run -d -p 5000:5000 rest-apis-flask-python
+```
+
+We're passing a few things to `docker run`:
+
+1. `-d` runs the container in the background, so that you can close the terminal and the container keeps running.
+2. `-p 5000:5000` maps port 5000 in your computer to port 5000 in the container.
+3. `rest-apis-flask-python` is the image tag that you want to run.
+
+You should see something like this as your output:
+
+```
+9f3c564ac64a1723069dda0e80becb70d3697d4bfcbcb626cd5add0c65df173f
+```
+
+That's the ID of the container. If you're not using Docker Desktop, you need this ID in order to stop the container later (with `docker rm 9f3c564`, that's the first few characters of the ID).
+
+And now, if everything has worked, you should be able to access the Flask app _just as if it was running without Docker_!
+
+:::caution Did something not work?
+A common error can happen when the port that you tried to forward isn't available (e.g. because something else is already running):
+
+```
+docker: Error response from daemon: driver failed programming external connectivity on endpoint bold_goldwasser (ff58b1755c1d1d0fd6b1dd4f59ab3b903b0e68f320624c4a2495672a735039d5): Bind for 0.0.0.0:5000 failed: port is already allocated.
+```
+
+You have two options: either figure out what is running on port 5000 and shut it down before trying again, or you can change the port that you want to use in your computer:
+
+```
+docker run -dp 5001:5000 rest-apis-flask-python
+```
+:::
+
+Try making requests using the URL `127.0.0.1:5000` with Insomnia REST Client or Postman, and you should see it working well!
+
+![Insomnia REST Client successfully made a request to the API running in Docker](assets/running-app-docker.png)