From 142f534edfd2cf697528de3322987caeed1ffbbc Mon Sep 17 00:00:00 2001 From: "K.B.Dharun Krishna" Date: Fri, 2 Feb 2024 14:59:29 +0530 Subject: [PATCH] feat: add remaining docs Signed-off-by: K.B.Dharun Krishna --- README.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c9cc25e..d5d6899 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Custom Vib Image -This template repository is a starting point for creating custom [Vib images](https://github.com/Vanilla-OS/Vib) on top of our desktop image. It contains a basic recipe and an example module to get you started. +This template repository is a starting point for creating custom [Vib images](https://github.com/Vanilla-OS/Vib) on top of our [desktop image](https://github.com/Vanilla-OS/desktop-image). It contains a basic recipe and an example module to get you started. It is suggested to checkout the [Vib repository's README](https://github.com/Vanilla-OS/Vib?tab=readme-ov-file#recipe-format) to know more about the recipe format, structure of modules and the supported fields. @@ -8,11 +8,23 @@ It is suggested to checkout the [Vib repository's README](https://github.com/Van Now, that you are aware of the basic syntax, let's explore the files and directories present in this repository: -- `.github/workflows/vib-build.yml`: This file contains the GitHub Actions workflow to check for updates to base image and build the Vib image. It uses the `vib` action to build the recipe and upload it as an artifact. The generated artifact is then built using Docker and pushed to GHCR. The action runs automatically on a schedule checking updates to the base image using [Differ](https://github.com/Vanilla-OS/Differ). -- `.github/workflows/vib-pr.yml`: This file contains the GitHub Actions workflow to build the Vib image on pull requests. It uses the `vib` action to build the recipe and upload it as an artifact. You can view the artifact to verify that your changes are performed as expected. -- `.github/dependabot.yml`: This file contains the configuration for Dependabot to check for updates to the GitHub actions used in the workflow files monthly and when it finds a new version it creates a PR in your repository. -- `includes.container`: The files included in this directory are added by default to your image (It also contains ABRoot's configuration file). +- `.github/workflows/vib-build.yml`: This file contains the GitHub Actions workflow to check for updates to base image and build the Vib image. + - It uses the `vib` action to build the recipe and upload it as an artifact. The generated artifact is then built using Docker and pushed to GHCR. + - The action runs automatically on a schedule checking updates to the base image using [Differ](https://github.com/Vanilla-OS/Differ). +- `.github/workflows/vib-pr.yml`: This file contains the GitHub Actions workflow to build the Vib image on pull requests. + - It uses the `vib` action to build the recipe and upload it as an artifact. You can download and view the artifact to verify that your changes are performed as expected. +- `.github/dependabot.yml`: This file contains the configuration for GitHub's Dependabot to check for updates to the GitHub actions used in the workflow files monthly and when it finds a new version it creates a PR in your repository. +- `includes.container`: The files included in this directory are added by default to your image to the specified location. (It also contains ABRoot's configuration file) - `modules`: This directory contains the modules that are used to customize the image. You can add your own modules to this directory. -- `recipe.yml`: This file contains the recipe for the image. It contains the base image, modules and other fields to be present in the image. +- `recipe.yml`: This file contains the recipe for the image. It specfies the base image, modules and other fields to be present in the custom image. ## Getting Started + +- First, click on the "Use this template" button in top right corner, then from the drop down menu select "Create a new repository". This would create a new repository with the same files and directories as this repository. +- Go to Settings -> Actions -> General and ensure "Allow all actions and reusable workflows" are enabled and the workflow permissions are set to both "Read and write permissions". +- Now, clone the repository to your local machine and let's start customizing your image. +- Open the `vib-build.yml` workflow file and replace the custom image name with your own image name in line 11. +- Open the ABRoot JSON configuration file under `includes.container/usr/share/abroot` directory and replace the name in the format `username/image-name` (i.e. `vanillaos/custom-vib-image`). +- Open the `recipe.yml` file and replace the image name and ID with your image name and ID in line 2 and 3. +- Now, perform your additions and modifications to the recipe as per your requirements. +- Optionally, add your own modules to the `modules` directory or modify the existing ones with the format `number-module_name.yml` (Note: modules with lower numbers are added first to the image). If not required, remove the module syntax from the `recipe.yml` file.