Skip to content

(3) How to Deploy

Jump to bottom
David Mang edited this page Aug 30, 2024 · 1 revision

This repository uses GitHub Actions to automate the build and deployment process for the application. The following section explains the purpose of each workflow file and how they work together to handle deployment. The workflow file can be found under the .github folder

Workflow Files

1. build_docker.yml

This file defines the workflow to build Docker containers for the application. The build process is triggered when there is a push to the main branch or when invoked by another workflow. This workflow handles:

  • Building Docker images for the application components (such as the server and client). It thereby uses the compose.yml file in the root directory.
  • Pushing the built images to a Docker registry.

Key Steps:

  1. Checkout Code: Retrieves the latest code from the repository.
  2. Set up Docker Buildx: Configures the Docker environment for building images.
  3. Log in to Docker Registry: Authenticates with the Docker registry using secrets. We are using the GitHub container registry to push and pull images (ghcr.io). The script automatically sets the GitHub actor and token to authenticate with the registry.
  4. Build and Push Images: Builds the Docker images for the client and server and pushes them to the registry.

2. deploy_docker.yml

This file defines the workflow for deploying the Docker containers to the production environment. It is dependent on the successful completion of the build_docker.yml workflow. To connect to the VM the script uses the following secrets stored at Settings > Secrets and variables > Actions:

  • SERVER_DOMAIN: Domain of the VM to which you want to connect to (eg. ma-mang.ase.cit.tum.com).
  • SERVER_USER: User created on the VM which has permissions to create folders and run commands on the VM.
  • SSH_KEY: Private SSH key to establish a connection to the VM.

The following variables are used to enable a connection between GitHub and a VM running on the TUM's servers with a proxy gateway. Those variables are automatically set:

  • DEPLOYMENT_GATEWAY_HOST
  • DEPLOYMENT_GATEWAY_USER
  • DEPLOYMENT_GATEWAY_SSH_KEY
  • DEPLOYMENT_GATEWAY_PORT

Key Steps:

  1. Connect to VM and Stop Docker Container: Execute docker compose down to stop the container for the deployment.
  2. Checkout Code: Retrieves the codebase to use for deployment configuration.
  3. Copy Docker Compose File to VM: Copy the compose.yml file from the root directory to the VM for later execution.
  4. Copy Letsencrypt Directory to VM: Copy the acme.json and the traefik.yml to the VM. These files are necessary to create a certificate to establish a TLS connection (LetsEncrypt)
  5. Setting Up Environment Variables: Adds the environment variables specified in How to Setup to a .env file on the VM. You must define the varibales before at Settings > Secrets and variables > Actions as secrets.
  6. Pull Docker Images: Pulls the built Docker images from the registry.
  7. Deploy to Production: Deploys the Docker containers to the production environment using the specified configuration by running docker compose.
  8. Notify on Success/Failure: Sends an email notification upon successful deployment or failure.

Inputs:

  • Environment: Specifies the target environment for deployment (e.g., Production).
  • Server Image Tag: The Docker tag for the server image (e.g., latest).
  • Client Image Tag: The Docker tag for the client image (e.g., latest).

3. prod.yml

This file (prod.yml) combines the build and deployment workflows into a single process that is triggered on a push to the main branch. It consists of two main jobs:

  • build-prod-container: Uses build_docker.yml to build and push Docker images.
  • deploy-prod-container: Depends on the build-prod-container job and uses deploy_docker.yml to deploy the application to the production environment.

Workflow Overview:

  • Trigger: The workflow is triggered by a push to the main branch.
  • Job Sequence:
    1. Build Docker Containers: The build-prod-container job builds and pushes the Docker images.
    2. Deploy Docker Containers: The deploy-prod-container job waits for the build to complete and then deploys the containers to the production environment.

How to Use These Workflows

  1. Set Up Secrets: Make sure the required secrets are added to the repository settings under Settings > Secrets and variables > Actions. These secrets are necessary for authenticating and performing operations like Docker image builds and deployments. These secrets include all environment variables for the server defined in How to Setup and the SERVER_DOMAIN, SERVER_USER, SSH_KEY used in the deploy_docker workflow.

  2. Modify Configurations: Update the docker-compose configurations, image tags, environment variables, or any other parameters in build_docker.yml and deploy_docker.yml according to your project’s requirements.

  3. Trigger Deployment: Push changes to the main branch to trigger the prod.yml workflow. This will start the build and deployment process automatically.

Troubleshooting

  • Build Failures: Check the logs for the build_docker.yml workflow under the Actions tab to identify any issues during the Docker image build process.
  • Deployment Failures: Review the logs for the deploy_docker.yml workflow to diagnose deployment issues. Ensure that the target environment is properly configured and accessible.
Clone this wiki locally