TARDIS Project

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Learning Docker ======

This is a brief overview of using Docker, matching the contents of the 2025 Docker Workshop.


==== What is Docker? ====
Docker is a platform for containerising applications. This is like running applications in Virtual Machines (VMs), although with a smaller resource footprint and the advantage of being able to re-use base images to save setup.
For most users Docker enables the rapid setting up of software, so if you do or are interested in self hosting then you should find this very useful.

=== The Docker Workflow ===
  - Start with an application
  - Write a **Dockerfile** that replicates the setup needed for the application
  - Use the **Docker Client** to build your application into an **image** using the **Dockerfile**
  - Then use the **Client** again to run the **image** as a **container**
  - Manage the running and configuration of multiple containers with **Docker Compose**

=== Parts of the Docker architecture ===
== Dockerfiles ==
Dockerfiles are text files placed in the root of a project directory with instructions to build a **container**. They are comprised of **layers**, where each layer is modification to the image created by every layer "beneath" it. As such Dockerfiles normally start with a **Base Image** that provides a useful reusable starting point. Any image can be used as a base image, but normally they are things like particular OSes, or environments for a particular language or library (Python, Java, Node, etc). An example from the workshop is provided below:
<file>
FROM python:3.10-alpine

# Install flask
WORKDIR /code
COPY requirements.txt /code
RUN pip3 install -r requirements.txt

# Copy the code to the image
COPY . .

# Open the flask port
EXPOSE 5000

CMD ["python", "FlaskApp/FlaskApp.py"]

</file>
Each line is a layer, and does the following:
  - Loads the python 3.10 base image
  - Moves into the /code directory
  - Copies in the requirements file
  - Installs the requirements
  - Copies in the rest of the code
  - Exposes the port the application uses
  - Defines the command that runs when the container starts.
== Images ==
Images are built from Dockerfiles. They are immutable collections of binaries, config files, libraries and other files that are needed to run a particular application. Base images are uploaded to registries and can save a lot of work in creating your own images. This ranges from particular operating system environments to entire ready-to-configure applications.
== Containers ==
Containers are created from images. Containers are similar to virtual machines, but are not the same thing. They run applications in isolated, self-reliant environments. One of the advantages of Docker is that pretty much anywhere it runs, containers will run.
== Compose ==
Docker Compose is an extra tool for managing the running of multiple-container applications. It makes things like networking easier, as well as configuration by storing parameters manually passed to //docker run// in a configuration file (normally called //docker-compose.yml//). Note that Compose V1 is run with //docker-compose//, whereas V2 uses //docker compose//. Some systems will still use V1, but they function mostly the same, and identically for the sake of this guide.

The //docker-compose.yml// file contains a list of services for the application, each of which has a defined configuration. All of these services can be brought up with a single command, which is handy. Below is an example of a compose file used in the workshop, although the extra networking configuration is specific to make it work on Sandbox.
<file>
version: "3.0"
services:
  flask:
    image: localhost/myname/flaskapp
    container_name: flask-compose
    ports:
      - YourPort:5000
    environment:
      - DISPLAY_NAME=YourName
    networks:
      - external

# Below fixes a problem with Tardis container networking
networks:
  external:
    name: podman
    external: true
</file>

==== Workshop tasks ====
Below is the interactive tasks from the workshop for people to work through at their own pace. Familiarity with Linux and Git is expected. [[https://git.tardisproject.uk/emily747/docker-workshop-2025|The workshop repo can be found here.]]
=== Setup ===
Sign up to Tardis if you haven't already and SSH into Sandbox.
Clone the workshop repo:
  git clone https://git.tardisproject.uk/emily747/docker-workshop-2025
Look inside the Dockerfile, what does each layer do?
=== Build an image ===
Run the below in the same directory as the Dockerfile to build the image. Change "myname" to your name. The ":latest" tags the version of the image.
<code>docker build -t myname/flaskapp:latest .</code>
See the list of saved images with:
<code>docker images</code>
=== Run a  container ===
Start your container with the following command, changing the display name argument and the port number. If the port number is in use run //docker rm flask// then try a different port.
<code>
docker run -e DISPLAY_NAME=YourName --name flask -p YourPort:5000 -d flaskapp
</code>
You can check if the container is working properly by making a request to the port it uses, by listing your running containers and by checking the logs of the container.
<code>
curl localhost:YourPort
docker ps
docker logs flask
</code>
Then stop and remove the container. Note that docker does not automatically remove stopped containers, you can see stopped containers with //docker ps -a//.
<code>
docker stop flask && docker rm flask
</code>
=== Configure your container with Compose ===
Make sure your current container is stopped, then edit the //docker-compose.yml// file to have your name and port number. You can then start the container with Compose using:
  docker-compose up -d
The //-d// flag detaches the container output from your terminal window. Check the output from the container with //curl localhost:YourPort// as above. Then, modify the DisplayName environment variable in the compose file and bring the container down and up again.
<code> docker-compose down && docker-compose up -d</code>
Curl the port again - it should have changed. Stop your container again with //docker-compose down//.
=== Extra tasks to look into ===
  * Look into mounting and accessing a volume with Compose
  * Open a shell in the container with //docker exec -it flask(-compose) sh//
  * Try finding a docker image online and adding it as a service
  * Find a piece of self-hosted software you can run as a Docker container