Welcome to M347-Portfolio, a ToDo application built using Docker and Kubernetes. This README provides documentation on how to set up, manage, and debug the application. The application consists of a frontend, backend, and a MariaDB database.
Before you begin, ensure you have the following tools & services installed on your local machine:
- Docker - Used for running and building the application.
- Kubernetes (Kubectl) - Used for managing the application in a Kubernetes cluster (Local or Cloud).
- Minikube - Used for running a local Kubernetes cluster.
Normally, the Docker images for the frontend and backend are built using GitHub Actions, when pushing a commit to the main branch. However, you can also build the Docker images locally using the following commands:
docker build -t <frontend or backend> ./<Frontend or Backend>For running the application locally quickly, you can use Docker Compose. This will create & run the Docker containers for the frontend, backend, and MariaDB database. To start the application, run the following command:
docker-compose up -dTo stop the application, run the following command:
docker-compose downHere are some useful docker commands for debugging:
# 1. List all running containers, including their IDs, names, and statuses.
docker ps
# 2. Show the logs of a specific container, which can help you find error messages or trace the application's execution.
docker logs <container-id/name>
# 3. Execute a command inside a running container, such as running a shell (`/bin/bash` or `/bin/sh`) to investigate the container's file system and processes.
docker exec -it <container-id/name> <command>
# 4. Provide detailed information about a container, including its configuration, network settings, and mounted volumes.
docker inspect <container-id/name>
# 5. Display real-time performance statistics for all running containers, including CPU usage, memory consumption, and network I/O.
docker stats
# 6. Show the running processes inside a container, similar to the `top` command on Linux.
docker top <container-id/name>
# 7. List the file system changes made in a container compared to the base image.
docker diff <container-id/name>
# 8. Copy files or directories between a container and the local file system, which can be helpful for examining application data or configuration files.
docker cp <container-id/name>:<path/to/source> <path/to/destination>
# 9. If you are using Docker Compose, show the logs for all services defined in the `docker-compose.yml` file.
docker-compose logs
#10. Tear down the current services and rebuild the containers from scratch if you've made changes to your application's code or dependencies.
docker-compose down && docker-compose up --buildFor running the application locally, you can use Minikube. This will create the Kubernetes cluster. To start Minikube, run the following command:
minikube startTo stop Minikube again, run:
minikube stopAfter the Kubernetes cluster was created, you can apply the Kubernetes resources for the application using the following commands.
kubectl apply -f .To delete the Kubernetes resources, use the delete keyword instead of apply.
Here are some useful kubectl commands for debugging:
# 1. Get information about all resources in the cluster (e.g., pods, services, deployments)
kubectl get <resource-type>
# 2. Describe a specific resource in detail
kubectl describe <resource-type> <resource-name>
# 3. Get logs from a specific pod
kubectl logs <pod-name>
# 4. Stream logs from a specific pod in real-time
kubectl logs -f <pod-name>
# 5. Get the current state of a Kubernetes configuration
kubectl config view
# 6. Switch between different Kubernetes contexts
kubectl config use-context <context-name>
# 7. Execute a command within a specific pod
kubectl exec -it <pod-name> -- <command>
# 8. Get the current status of a specific deployment
kubectl rollout status deployment/<deployment-name>
# 9. Display the history of a specific deployment
kubectl rollout history deployment/<deployment-name>
# 10. Get resource usage information for each pod in the namespace
kubectl top pod
# 11. Get resource usage information for each node in the cluster
kubectl top node
# 12. Debug issues with ingress by displaying ingress resources
kubectl get ingress
The application uses the following environment variables:
DB_HOST # The hostname of the MariaDB database server.
DB_USER # The username to use for connecting to the MariaDB database.
DB_PASSWORD # The password to use for connecting to the MariaDB database.
DB_NAME # The name of the MariaDB database to use.These environment variables can be set in the respective Docker and Kubernetes configuration files.
publish.yml, is responsible for building and publishing Docker images for the frontend and backend components of the application. The action is triggered on each push to the repository.
The publish.yml file is composed of two jobs: publish-frontend-image and publish-backend-image. Both jobs have similar steps:
- Check out the repository using the
actions/checkout@v2action. - Log in to the GitHub Container Registry using the
docker/login-action@v1action, with theGHCR_PATsecret for authentication. - Build the Docker image for either the frontend or backend, tagging it with the appropriate path in the GitHub Container Registry (e.g.,
ghcr.io/jonathanxdr/todo-frontend:latestorghcr.io/jonathanxdr/todo-backend:latest). - Push the built image to the GitHub Container Registry.
This GitHub Action allows for automated building and publishing of the Docker images, ensuring that the latest versions are always available in the GitHub Container Registry.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent