Skip to content

Latest commit

 

History

History
153 lines (119 loc) · 7.43 KB

README.rst

File metadata and controls

153 lines (119 loc) · 7.43 KB
Raw

Picasso Workflow

Simplifies the build of Open edX Docker images for Tutor environments, providing a solution that integrates directly with GitHub Actions.

Purpose

Picasso is a tool designed to help teams simplify the build process for the Open edX Docker images, tailored explicitly for use in Tutor environments. It enables the addition of custom behaviors and features through the internal plugin tutor-contrib-picasso, allowing for additional flexibility during the build process.

This workflow integrates seamlessly with existing internal workflows, enabling it to be invoked in custom jobs. It leverages Tutor to build images starting from the Olive version, which can be deployed across both production and development environments. This ensures consistency in managing multiple environments while simplifying the overall process.

With Picasso, teams can build custom Open edX images with additional functionality, making it easier to maintain, extend, and deploy environments using modern CI/CD practices.

Workflow Overview

The Picasso Workflow is designed to build Open edX Docker images for Tutor environments.

Key features of the Picasso Workflow include:

  • Runs on GitHub-hosted runners: By default, the workflow uses ubuntu-latest runners to execute jobs. This can't be changed to self-hosted runners for the time being.
  • Builds and pushes Docker images: The workflow pushes images to Dockerhub by default. This can be customized to push images to other registries.
  • Supports multiple services: You can specify the service to build (e.g., openedx, mfe, codejail, etc.) using the SERVICE input.
  • Customizable repository and strain: The workflow allows for specifying the repository, branch, and path to the strain being built. This enables building images from different configurations.
  • Configurable BuildKit parallelism: By default, the workflow limits parallelism during the build process to optimize resource usage, although this can be changed using the ENABLE_LIMIT_BUILDKIT_PARALLELISM input. This is useful for low-powered machines, like Github Actions standard runners.
  • Private repository access: SSH keys are used to clone private repositories securely. The SSH private key should be stored as a secret in the repository, and must have access to the repository specified in STRAIN_REPOSITORY.
  • Extra commands: The workflow allows running additional custom commands with tutor picasso run-extra-commands. For details, refer to the tutor-contrib-picasso documentation.
  • Environment setup: The workflow sets up and configures Tutor Virtual Environments (TVM), installs necessary plugins like tutor-contrib-picasso, and prepares the environment to build and push Docker images using the Tutor CLI.

Configuration

Before using the workflow, ensure that you have set up the following configurations in your GitHub repository:

Picasso Workflow Configuration
Variable Description Type Source
DOCKERHUB_USERNAME (Optional) Docker Hub username to push images. string Secret
DOCKERHUB_PASSWORD (Optional) Docker Hub password for login. string Secret
AWS_ACCESS_KEY_ID (Optional) AWS access key ID for pushing images to ECR. string Secret
AWS_SECRET_ACCESS_KEY (Optional) AWS secret access key for pushing images to ECR. string Secret
AWS_REGION (Optional) AWS region for pushing images to ECR. string Secret
SSH_PRIVATE_KEY (Required) SSH private key for repository checkout. This key should have access to the repository specified in STRAIN_REPOSITORY. string Secret
STRAIN_REPOSITORY (Required) The repository to clone the strain from, e.g., edunext/repository-name. string Input
STRAIN_REPOSITORY_BRANCH (Required) The branch to clone the strain from, e.g., main. This branch should contain the version of configuration config.yml file used to build the image. string Input
STRAIN_PATH (Required) The path to the strain within the repository structure, e.g., path/to/strain. string Input
SERVICE (Required) The service name to build, e.g., openedx. This can be any service recognized by the tutor ecosystem. string Input
ENABLE_LIMIT_BUILDKIT_PARALLELISM (Optional) Enables limiting parallelism with buildkit to decrease resource consumption for those setups with low-powered machines. Default is true. boolean Input

Usage

To use the Picasso Workflow, follow these steps:

  1. Ensure your repository calls the Picasso workflow like the one below. This example demonstrates how to build an Open edX image using the Picasso workflow:

    jobs:
  build:
    name: Build Open edX Image
    uses: eduNEXT/picasso/.github/workflows/build.yml@main
    with:
      STRAIN_REPOSITORY: edunext/builds
      STRAIN_REPOSITORY_BRANCH: main
      STRAIN_PATH: redwood/base
      SERVICE: openedx
    secrets:
      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
      DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

  2. Modify the STRAIN_REPOSITORY, STRAIN_REPOSITORY_BRANCH, STRAIN_PATH, and SERVICE inputs to match your project requirements.

  3. You can also set up a custom trigger for the workflow based on your project requirements.

Getting Help

If you encounter any issues with the workflow or need further assistance, please refer to the following resources:

Contributing

Contributions are welcome and strongly encouraged! Please, open an issue or submit a pull request to suggest changes or improvements to the workflow.

License

This project is licensed under the AGPL-3.0 License. . Please note that no support or maintenance is guaranteed for public users. Any updates, bug fixes, or improvements will be made based on internal priorities, and contributions from the community may not receive immediate attention.

Reporting Security Issues

Please do not report security vulnerabilities in public forums. Instead, email [email protected].