Project 4 Rubric: A Detailed Breakdown

by Alex Johnson 39 views

This article dives deep into the Project 4 Rubric, providing a comprehensive discussion and breakdown of each section. Understanding the rubric is crucial for achieving a high score and demonstrating mastery of the concepts. This guide will walk you through each requirement, offering explanations and insights to help you excel in your project.

Project Score: / 55

Your final project score will be out of 55 points, distributed across various components. Pay close attention to each section's point allocation to prioritize your efforts effectively. Make sure to thoroughly review each requirement and ensure your project meets the specified criteria.

GitHub Repository Contents ( / 4)

This section assesses the organization and completeness of your GitHub repository. A well-structured repository is essential for collaboration and maintainability. Ensure that your repository includes the following files and directories to secure the full 4 points:

  • README-CI.md
  • web-content folder with web application
  • Dockerfile
  • GitHub action yml file in .github/workflows

Importance of a Well-Organized Repository

A well-organized repository not only helps in grading but also demonstrates your understanding of software engineering best practices. The README-CI.md file should provide a clear overview of your project, including instructions for setup and usage. The web-content folder should contain all the necessary files for your web application. The Dockerfile is crucial for containerization, and the GitHub Actions yml file automates your CI/CD pipeline. By ensuring these elements are present and well-structured, you lay a solid foundation for the rest of your project.

Part 4 - Project Description & Diagram ( / 8)

This section evaluates your ability to articulate the project's goals, tools, and architecture. Clear and concise documentation is vital for conveying your understanding and facilitating collaboration. The documentation requirements are broken down as follows:

Documentation Requirements:

  1. Continuous Integration Project Overview
    • [ ] What is the goal of this project
    • [ ] What tools are used in this project and what are their roles
    • Diagram of project
      • [ ] clean layout
      • [ ] what happens in cloned repo
      • [ ] what happens in GitHub
      • [ ] what happens in DockerHub
    • [ ] [If applicable] What is not working in this project
  2. Resources Section
    • [ ] Uses good formatting
    • [ ] Citations appropriate to project / include notes on how they were used.

Detailed Explanation of Documentation Requirements

The project overview should clearly state the objectives of your CI/CD pipeline and how it enhances the software development process. Detailing the tools used, such as Docker, GitHub Actions, and any web application frameworks, is essential. Explain the role each tool plays in the pipeline. The project diagram should provide a visual representation of the CI/CD workflow, illustrating the flow of code from the repository to deployment. It should cover the processes within the cloned repository, GitHub, and DockerHub. Include any limitations or non-functional aspects of your project and document them, as this shows transparency and critical thinking.

The resources section should list all the materials you consulted, such as documentation, tutorials, and Stack Overflow threads. Proper formatting and citations are crucial for academic integrity and demonstrating your research process. Include notes on how each resource was used to solve specific problems or implement features. This thorough approach to documentation will significantly enhance your score in this section.

Part 1 - Create a Docker container image ( / 9)

This part focuses on your ability to create and utilize Docker containers. Docker is a cornerstone of modern CI/CD pipelines, enabling consistent and reproducible environments. This section assesses both your documentation and task completion.

Documentation Requirements:

  1. Dockerfile & Building Images
    • [ ] Explanation and links to web site content
    • [ ] Explanation of and link to Dockerfile
    • [ ] How to build an image from the repository Dockerfile
      • [ ] Include tagging requirements when planning to use DockerHub for a container image repository
    • [ ] How to run a container that will serve the web application from the image built by the Dockerfile

Task Requirements:

  • Dockerfile
    • [ ] Builds from httpd:2.4
    • [ ] Copies all content in web-content into the container filesystem in the default web content directory for httpd
  • [ ] Provides a working application when the container is run using the built image
  • [ ] DockerHub image repository shows at least one tagged image

Detailed Breakdown of Part 1

Your documentation should explain the purpose of your Dockerfile and how it automates the process of building your container image. Include links to the web site content and a direct link to your Dockerfile in the repository. Provide step-by-step instructions on building the image, emphasizing the importance of tagging for version control and DockerHub integration. Explain how to run a container using the built image and verify that the web application is served correctly. Ensure your Dockerfile builds from httpd:2.4, copies the web-content into the appropriate directory, and that your DockerHub repository contains at least one tagged image.

By thoroughly documenting your process and meeting all task requirements, you demonstrate a strong understanding of Docker and its role in CI/CD.

Part 2 - GitHub Actions and DockerHub ( / 17)

This section evaluates your ability to automate your CI/CD pipeline using GitHub Actions and DockerHub. GitHub Actions allows you to define workflows that automatically build, test, and deploy your application. DockerHub serves as your container image registry.

Documentation Requirements:

  1. Configuring GitHub Repository Secrets:
    • [ ] How to create a PAT for authentication (and recommended PAT scope for this project)
    • [ ] How to set repository Secrets for use by GitHub Actions
    • [ ] Describe the Secrets set for this project
  2. CI with GitHub Actions
    • [ ] Explanation of workflow trigger
    • [ ] Explanation of workflow steps
    • Explanation / highlight of values that need updated if used in a different repository
      • [ ] changes in workflow
      • [ ] changes in repository
    • [ ] Link to workflow file in your GitHub repository
  3. Testing & Validating
    • [ ] How to test that your workflow did its tasking
    • [ ] How to verify that the image in DockerHub works when a container is run using the image
    • [ ] Link to your DockerHub repository

Task Requirements - 2 pts each:

  • [ ] Secrets set in repository
  • [ ] Workflow defined, triggers on push to main
  • [ ] GitHub Action has run workflow at least once

Comprehensive Explanation of Part 2

Begin by documenting how to create a Personal Access Token (PAT) with the necessary scope for authenticating with DockerHub. Detail the steps to set repository Secrets in GitHub for use by your Actions, ensuring sensitive information is securely stored. Clearly describe the Secrets you have set for the project. Explain the trigger for your workflow, typically a push to the main branch, and provide a step-by-step explanation of your workflow, including building the Docker image and pushing it to DockerHub.

Highlight any values that would need to be updated if the workflow is used in a different repository, such as repository names or DockerHub credentials. Include a direct link to your workflow file in the GitHub repository. Document the testing and validation process, including how to verify the workflow's execution and how to run a container using the image from DockerHub. Provide a link to your DockerHub repository for easy access. Ensure that you have set the necessary Secrets, defined a workflow that triggers on pushes to the main branch, and that the GitHub Action has run successfully at least once.

Part 3 - Semantic Versioning ( / 17)

Semantic versioning is crucial for managing software releases and dependencies. This part assesses your understanding and implementation of semantic versioning in your CI/CD pipeline.

Documentation Requirements:

  1. Generating tags
    • [ ] How to see tags in a git repository
    • [ ] How to generate a tag in a git repository
    • [ ] How to push a tag in a git repository to GitHub
  2. Semantic Versioning Container Images with GitHub Actions
    • [ ] Explanation of workflow trigger
    • [ ] Explanation of workflow steps
    • Explanation / highlight of values that need updated if used in a different repository
      • [ ] changes in workflow
      • [ ] changes in repository
    • [ ] Link to workflow file in your GitHub repository
  3. Testing & Validating
    • [ ] How to test that your workflow did its tasking
    • [ ] How to verify that the image in DockerHub works when a container is run using the image
    • [ ] Link to your DockerHub repository with evidence of the tag set

Task Requirements - 2 pts each:

  • [ ] Workflow defined, trigger on push of tags
  • [ ] GitHub Action has run workflow at least once with tag being the event
  • [ ] DockerHub shows semantically tagged versions from GH Action

In-Depth Analysis of Part 3

Document the process of generating tags in a Git repository, including how to view existing tags, create new tags, and push them to GitHub. Explain how semantic versioning is applied to your container images, following the MAJOR.MINOR.PATCH format. Describe the workflow trigger, which should be a push of tags, and provide a detailed explanation of the workflow steps. Highlight any values that would need updating for different repositories. Include a direct link to your workflow file. Document how you tested and validated your workflow, verifying that the tagged images in DockerHub match the semantic versions.

Ensure that your workflow is defined to trigger on tag pushes, that the GitHub Action has run successfully at least once with a tag event, and that DockerHub displays semantically tagged versions from your GitHub Action.

Common Point Deductions:

  • [ ] (-30%) Documentation not well organized with markdown OR includes project descriptive text
  • [ ] (-10%) Documentation fails to address what was not implemented / implies the project is fully functional. Always document shortcomings and note what is "research" on how the rest should be done
  • [ ] (-5%) Dockerfile does not build viable container image to run application
  • [ ] (-5%) GitHub Action does not push image(s) to DockerHub
  • [ ] (-5%) Images in DockerHub do not use semantic versions in tagging
  • [ ] No citations of referenced material

    [!WARNING] May result in Academic Integrity Violation with a penalty of a 0 on the project

Key Areas to Avoid Point Deductions

Pay close attention to these common pitfalls to avoid losing points. Ensure your documentation is well-organized using Markdown and avoid simply transcribing project descriptions; instead, focus on explanations and insights. Always document any limitations or non-functional aspects of your project. Verify that your Dockerfile builds a viable container image, that your GitHub Action pushes images to DockerHub, and that your images in DockerHub use semantic versioning. Most importantly, properly cite all referenced materials to avoid academic integrity issues.

Conclusion

By thoroughly understanding and addressing each aspect of the Project 4 Rubric, you can significantly increase your chances of achieving a high score. Remember to focus on clear documentation, proper implementation, and adherence to best practices in CI/CD. Good luck with your project!

For more information on CI/CD and best practices, check out this comprehensive guide.