From 07710d6638adaeceefcd79a4829c3ce23998b6a5 Mon Sep 17 00:00:00 2001 From: "K.B.Dharun Krishna" Date: Mon, 22 Apr 2024 13:56:56 +0530 Subject: [PATCH] chore: update docs Signed-off-by: K.B.Dharun Krishna --- docs/articles/en/getting-started.md | 15 +++++++------ docs/articles/en/github-action.md | 30 ++++++++++++++------------ docs/articles/en/project-structure.md | 31 ++++++++++++++------------- docs/articles/en/recipe-structure.md | 23 +++++++++++--------- docs/articles/en/use-modules.md | 9 ++++---- docs/articles/en/vscode-extension.md | 9 ++++---- docs/website/src/examples.hbs | 3 ++- docs/website/src/index.hbs | 3 ++- 8 files changed, 67 insertions(+), 56 deletions(-) diff --git a/docs/articles/en/getting-started.md b/docs/articles/en/getting-started.md index b862d1f..8520c72 100644 --- a/docs/articles/en/getting-started.md +++ b/docs/articles/en/getting-started.md @@ -4,6 +4,7 @@ Description: How to start using Vib to build your Container images. PublicationDate: 2024-02-11 Authors: - mirkobrombin + - kbdharun Tags: - getting-started --- @@ -14,7 +15,7 @@ Vib is a powerful tool that allows you to create container images using a YAML r To use Vib, there are no specific requirements; you just need a Linux\* operating system (Mac OS and Windows will be supported in the future). Optionally, you can install a container engine to test and publish the images created to a registry. -\* Currently, Vib requires a Linux distribution with glibc. +\* Currently, Vib requires a Linux distribution with `glibc`. ### Supported Container Engines @@ -45,17 +46,17 @@ mv vib ~/.local/bin ## Usage -To start using Vib, create a `vib.yaml` file in a new directory. This file will contain the recipe for your container image. +To start using Vib, create a `vib.yml` file in a new directory. This file will contain the recipe for your container image. ```bash mkdir my-vib-project cd my-vib-project -touch vib.yaml +touch vib.yml ``` -Here's an example `vib.yaml` file: +Here's an example `vib.yml` file: -```yaml +```yml name: My Image id: my-image stages: @@ -102,13 +103,13 @@ vib build vib.yaml to turn your recipe into a Containerfile. Use that file to build the container image with your container engine. To streamline the process, you can use the `compile` command to build the container image directly: ```bash -vib compile vib.yaml --runtime docker +vib compile vib.yml --runtime docker ``` changing `docker` with the container engine you have installed. Both `docker` and `podman` are supported. If you leave out the `--runtime` flag, Vib will use the default container engine giving priority to Docker. > **Note:** -> For versions of Vib prior to 0.5.0, the syntax of the `compile` command was different. The `--runtime` flag was not available, and the command was `vib compile vib.yaml docker`. +> For versions of Vib before 0.5.0, the syntax of the `compile` command was different. The `--runtime` flag was not available, and the command was `vib compile vib.yml docker`. The generated `Containerfile` is compatible with both Docker and Podman. diff --git a/docs/articles/en/github-action.md b/docs/articles/en/github-action.md index 495d3e7..a94efd1 100644 --- a/docs/articles/en/github-action.md +++ b/docs/articles/en/github-action.md @@ -4,6 +4,7 @@ Description: How to build a Vib image using GitHub Actions. PublicationDate: 2024-02-14 Authors: - mirkobrombin + - kbdharun Tags: - github - build @@ -13,7 +14,7 @@ Many projects use GitHub to host their code, and GitHub Actions to automate thei ## Setup the Workflow -To use the Vib GitHub Action, you need to create a workflow file in the repository where your Vib recipe is located. Create a new file in the `.github/workflows` directory, for example `vib-build.yml`, and add the following content: +To use the Vib GitHub Action, you need to create a workflow file in the repository where your Vib recipe is located. Create a new file in the `.github/workflows` directory, for example, `vib-build.yml`, and add the following content: ```yaml name: Vib Build @@ -30,9 +31,10 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: vanilla-os/vib-gh-action@v0.6.2 + - uses: vanilla-os/vib-gh-action@v0.7.0 with: - recipe: "vib.yaml" + recipe: "vib.yml" + plugins: "org/repo:tag, org/repo:tag" - name: Build the Docker image run: docker image build -f Containerfile --tag ghcr.io/your_org/your_image:main . @@ -46,8 +48,8 @@ Let's break down the workflow file: - `runs-on`: The type of machine to run the job on. In this case, the job runs on the latest version of Ubuntu; check [here](https://github.com/actions/runner-images?tab=readme-ov-file#available-images) for the available machine types. - `steps`: The sequence of tasks to run in the job. - `actions/checkout@v4`: A standard action to check out the repository. - - `vanilla-os/vib-gh-action@v0.3.3-1`: The Vib GitHub Action to build the image. The `with` section specifies the recipe file to use. - - `run`: A standard command to build the Docker image. The `--tag` option specifies the name and tag of the image, in this case `ghcr.io/your_org/your_image:main`, you can change it according to your needs. + - `vanilla-os/vib-gh-action@v0.7.0`: The Vib GitHub Action to build the image. The `with` section specifies the recipe file and additional plugins to use. + - `run`: Contains a standard command to build the Docker image. The `--tag` option specifies the name and tag of the image, in this case, the tag is `ghcr.io/your_org/your_image:main`, you can change it according to your needs. ### Using Custom Plugins @@ -55,9 +57,9 @@ If you are using custom Vib plugins in your recipe, you can include them in the ```yaml # other steps -- uses: vanilla-os/vib-gh-action@v0.6.2 +- uses: vanilla-os/vib-gh-action@v0.7.0 with: - recipe: "vib.yaml" + recipe: "vib.yml" plugins: "your_org/my-plugin:v0.0.1" # the rest of the workflow ``` @@ -72,10 +74,10 @@ To use more than one plugin, simply separate them with a comma: ```yaml # other steps -- uses: vanilla-os/vib-gh-action@v0.6.2 +- uses: vanilla-os/vib-gh-action@v0.7.0 with: - recipe: "vib.yaml" - plugins: "your_org/my-plugin:v0.0.1,another_org/another-plugin:v1.2.3" + recipe: "vib.yml" + plugins: "your_org/my-plugin:v0.0.1, another_org/another-plugin:v1.2.3" # the rest of the workflow ``` @@ -102,16 +104,16 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: vanilla-os/vib-gh-action@v0.6.2 + - uses: vanilla-os/vib-gh-action@v0.7.0 with: - recipe: "vib.yaml" + recipe: "vib.yml" - name: Build the Docker image - run: docker image build -f Containerfile --tag ghcr.io/your_org/your_image . + run: docker image build -f Containerfile --tag ghcr.io/your_org/your_image:main . # Push the image to GHCR (Image Registry) - name: Push To GHCR - if: github.repository == 'your_org/your_image' + if: github.repository == 'your_org/your_repo' run: | docker login ghcr.io -u ${{ env.REGISTRY_USER }} -p ${{ env.REGISTRY_PASSWORD }} docker image push "ghcr.io/your_org/your_image:main" diff --git a/docs/articles/en/project-structure.md b/docs/articles/en/project-structure.md index 6e16f63..b62f481 100644 --- a/docs/articles/en/project-structure.md +++ b/docs/articles/en/project-structure.md @@ -4,21 +4,22 @@ Description: How to structure your Vib project. PublicationDate: 2024-02-13 Authors: - mirkobrombin + - kbdharun Tags: - project --- -Vib only requires a `vib.yaml` file to build in the root of your project. However, to take full advantage of Vib, you can follow a specific project structure. +Vib only requires a `vib.yml` file to build in the root of your project. However, to take full advantage of Vib, you can follow a specific project structure. ## Standard Project -A project is a directory containing a `vib.yaml` file, this is the easiest way to use Vib in your existing projects, whatever their structure is. Then simply run `vib build` to build the image according to your recipe. +A project is a directory containing a `vib.yml` file, this is the easiest way to use Vib in your existing projects, whatever their structure is. Then simply run `vib build` to build the image according to your recipe. The following is an example of a project structure: ```plaintext my-project/ -├── vib.yaml +├── vib.yml ``` ## Vib Project @@ -47,55 +48,55 @@ my-project/ ### Structure Details -Here some details about the structure: +Here are some details about the structure: - `vib/` is the directory containing the Vib project. - `includes.container/` is the directory containing the files to be included in the image. It can contain any file or directory you want to include in the image. The files in this directory will be copied to the root of the image following the same structure. - `modules/` is the directory containing the modules used in the recipes. You can create as many modules directories as you want, naming them as you prefer. Each module directory contains one or more YAML files, each one representing a module, name them as you prefer. -- `vib.yaml` is the recipe file for the image. You can have multiple `vib.yaml` files in the same project, each one representing a different image. For example, you can have a `dev.yaml` and a `prod.yaml` file to build different images for development and production environments, then build them with `vib build dev.yaml` and `vib build prod.yaml`. +- `vib.yml` is the recipe file for the image. You can have multiple `vib.yml` files in the same project, each one representing a different image. For example, you can have a `dev.yml` and a `prod.yml` file to build different images for development and production environments, then build them with `vib build dev.yml` and `vib build prod.yml`. ### Include Modules in the Recipe You can define your modules directly in the recipe file but the above structure is recommended to keep the project organized and to reuse the modules across different recipes. So, once you have defined your modules directories, you can include them in the recipe file using the `include` module: -```yaml +```yml - name: deps-modules type: includes includes: - - modules/node.yaml - - modules/python.yaml + - modules/node.yml + - modules/python.yml - name: proj-modules type: includes includes: - - modules/myproject.yaml + - modules/myproject.yml ``` #### Remote Modules Vib has support for remote modules, you can include them in the recipe file using the module URL or the `gh` pattern: -```yaml +```yml - name: deps-modules type: includes includes: - - https://my-repo.com/modules/node.yaml - - gh:my-org/my-repo/modules/python.yaml + - https://my-repo.com/modules/node.yml + - gh:my-org/my-repo/modules/python.yml ``` -As you can see in the above example, we are explicitly including each module in the recipe file and not pointing to the whole modules directory. This is because the `include` module ensure each module gets included in the exact order you specify, ensuring the build process is predictable. +As you can see in the above example, we are explicitly including each module in the recipe file and not pointing to the whole `modules` directory. This is because the `include` module ensures each module gets included in the exact order you specify, ensuring the build process is predictable. ### Usecase of the includes.container Directory As mentioned, the `includes.container` directory contains the files to be included in the image. This directory is useful to include files that are not part of the project, for example, configuration files, desktop files, or any other file you want to include in the image. -This is useful expecially when you need to configure the Linux system with custom configuration files or new systemd services. +This is useful especially when you need to configure the Linux system with custom configuration files or new `systemd` services. ### Use the `adds` Directive Optionally, you can use the `adds` directive to include more directories and files in the image: -```yaml +```yml adds: - extra-files/ - /etc/my-config-file diff --git a/docs/articles/en/recipe-structure.md b/docs/articles/en/recipe-structure.md index 921cd1c..7f55c69 100644 --- a/docs/articles/en/recipe-structure.md +++ b/docs/articles/en/recipe-structure.md @@ -4,13 +4,14 @@ Description: Learn about the structure of a Vib recipe. PublicationDate: 2024-02-13 Authors: - mirkobrombin + - kbdharun Tags: - modules - recipe --- > **Note** -> Stages were introduced in Vib v0.6.0, if you are using an older version, please keep in mind all the stage's fields are at the top level of the recipe, so no multiple stages are supported. +> Stages were introduced in Vib v0.6.0, if you are using an older version, please keep in mind all the stage fields are at the top level of the recipe, so no multiple stages are supported. A Vib recipe is a YAML file that contains the instructions to build a container image. It's composed of two blocks: @@ -19,7 +20,7 @@ A Vib recipe is a YAML file that contains the instructions to build a container The following is a complete example of a Vib recipe: -```yaml +```yml # metadata name: My Image id: my-image-id @@ -60,7 +61,9 @@ stages: singlelayer: false labels: maintainer: My Awesome Team - expose: 8080 + expose: + "8080": "tcp" + "8081": "" entrypoint: ["/app"] copy: - from: build @@ -80,7 +83,7 @@ The metadata block contains the following mandatory fields: - `base`: the base image to start from, can be any Docker image from any registry or even `scratch`. - `name`: the name of the image. -- `id`: the ID of the image, can be used by platforms like [Atlas](https://images.vanillaos.org/#/) to identify the image. +- `id`: the ID of the image is used to specify an image's unique identifier, it is used by platforms like [Atlas](https://images.vanillaos.org/#/) to identify the image. - `stages`: a list of stages to build the image, useful to split the build process into multiple stages (e.g. to build the application in one stage and copy the artifacts into another one). ## Stages @@ -93,7 +96,7 @@ Each stage has the following fields: - `labels`: a map of labels to apply to the image, useful to add metadata to the image that can be read by the container runtime. - `adds`: a list of files or directories to add to the image, useful to include files in the image that are not part of the source code (the preferred way to include files in the image is to use the `includes.container/` directory, see [Project Structure](/docs/articles/en/project-structure)). - `args`: a list of environment variables to set in the image. -- `runs`: a list of commands to run in the image (as an alternative to the `shell` module, useful for dividing the commands of your recipe from those needed to configure the image, for example to disable the recommended packages in apt). +- `runs`: a list of commands to run in the image (as an alternative to the `shell` module, useful for dividing the commands of your recipe from those needed to configure the image, for example, to disable the recommended packages in apt). - `expose`: a list of ports to expose in the image. - `cmd`: the command to run when the container starts. - `entrypoint`: the entry point for the container, it's similar to `cmd` but it's not overridden by the command passed to the container at runtime, useful to handle the container as an executable. @@ -104,7 +107,7 @@ Each stage has the following fields: The modules block contains a list of modules to use in the recipe. Each module is a YAML snippet that defines a set of instructions. The common structure is: -```yaml +```yml - name: name-of-the-module type: type-of-the-module # specific fields for the module type @@ -112,13 +115,13 @@ The modules block contains a list of modules to use in the recipe. Each module i Refer to the [Use Modules](/vib/en/use-modules) article for more information on how to use modules in a recipe and [Built-in Modules](/vib/en/built-in-modules) for a list of the built-in modules and their specific fields. -You can also write your own modules by making a Vib plugin, see the [Making a Plugin](/vib/en/making-plugin) article for more information. +You can also write your custom modules by making a Vib plugin, see the [Making a Plugin](/vib/en/making-plugin) article for more information. ### Copying files between stages -You can copy files between stages using the `copy` field. This consist in a list of files or directories to copy from another stage. Each item in the list is a YAML snippet that defines the source and destination of the copy operation. The common structure is: +You can copy files between stages using the `copy` field. This consists of a list of files or directories to copy from another stage. Each item in the list is a YAML snippet that defines the source and destination of the copy operation. The common structure is: -```yaml +```yml - from: stage-id-to-copy-from paths: - src: /path/to/source @@ -127,7 +130,7 @@ You can copy files between stages using the `copy` field. This consist in a list For example, to copy the `/path/to/output` directory from the `build` stage to the `/app` directory in the `dist` stage, you can use the following snippet: -```yaml +```yml - from: build paths: - src: /path/to/output diff --git a/docs/articles/en/use-modules.md b/docs/articles/en/use-modules.md index c6dceae..06dbf58 100644 --- a/docs/articles/en/use-modules.md +++ b/docs/articles/en/use-modules.md @@ -4,6 +4,7 @@ Description: How to use predefined and custom modules in your Vib recipes. PublicationDate: 2024-02-13 Authors: - mirkobrombin + - kbdharun Tags: - modules --- @@ -13,7 +14,7 @@ Modules are a fundamental part of Vib, likely the thing you will interact with t ## Familiarize with Vib Recipes > **Note** -> Stages were introduced in Vib v0.6.0, if you are using an older version, please keep in mind all the stage's fields are at the top level of the recipe, so no multiple stages are supported. +> Stages were introduced in Vib v0.6.0, if you are using an older version, please keep in mind all the stage fields are at the top level of the recipe, so no multiple stages are supported. Before diving into the modules, it's important to understand the structure of a Vib recipe. @@ -32,7 +33,7 @@ To get more information about the structure of a recipe and its fields, please r A module is a YAML snippet that defines a set of instructions, the common structure is: -```yaml +```yml name: name-of-the-module type: type-of-the-module # specific fields for the module type @@ -40,9 +41,9 @@ type: type-of-the-module While the `name` and `type` fields are mandatory, the specific fields depend on the module type. For example, a `shell` module has a `commands` field that contains the shell commands to execute to complete the task. -You will find that some modules has a common `source` field, this instructs Vib to download a resource required for the module to work: +You will find that some modules have a common `source` field, this instructs Vib to download a resource required for the module to work: -```yaml +```yml - name: vanilla-tools type: shell source: diff --git a/docs/articles/en/vscode-extension.md b/docs/articles/en/vscode-extension.md index f9446ab..3180a74 100644 --- a/docs/articles/en/vscode-extension.md +++ b/docs/articles/en/vscode-extension.md @@ -4,6 +4,7 @@ Description: Learn how to work with Vib recipes in Visual Studio Code using our PublicationDate: 2024-02-14 Authors: - mirkobrombin + - kbdharun Tags: - development - vscode @@ -11,7 +12,7 @@ Tags: Visual Studio Code is a popular code editor that provides a wide range of features to help you write, debug, and deploy your code, other than being highly customizable, it also offers a wide range of extensions to enhance your development experience, for example for working with YAML files. -Vib recipes are written in YAML, and usually a standard text editor or the YAML support provided by Visual Studio Code is enough to work with them. However, we have developed a dedicated extension for Visual Studio Code to make working with Vib recipes even easier and more efficient. +Vib recipes are written in YAML, and usually, a standard text editor or the YAML support provided by Visual Studio Code is enough to work with them. However, we have developed a dedicated extension for Visual Studio Code to make working with Vib recipes even easier and more efficient. ## Features @@ -35,10 +36,10 @@ To install the Vib extension, follow these steps: ## Usage -Once the extension is installed, you can start using it to work with Vib recipes. For it to work, you need to put the following header at the beginning of your recipe: +Once the extension gets installed, you can start using it to work with Vib recipes. For it to work, you need to put the following header at the beginning of your recipe: -```yaml +```yml # vib ``` -This header is used to identify the file as a Vib recipe and to enable the extension features. In the future, we plan to have support for our own file extension, but for now, this is the way to go. +This header is used to identify the file as a Vib recipe and to enable the extension features. In the future, we plan to have support for our dedicated file extension, but for now, this is the way to go. diff --git a/docs/website/src/examples.hbs b/docs/website/src/examples.hbs index 10caeb7..d2a7430 100644 --- a/docs/website/src/examples.hbs +++ b/docs/website/src/examples.hbs @@ -33,7 +33,8 @@ stages: maintainer: My Awesome Team args: DEBIAN_FRONTEND: noninteractive - expose: 3000 + expose: + "3000": "" entrypoint: ["node", "/app/app.js"] runs: - echo 'APT::Install-Recommends "0";' > /etc/apt/apt.conf.d/01norecommends diff --git a/docs/website/src/index.hbs b/docs/website/src/index.hbs index 2ec1d77..c533b9b 100644 --- a/docs/website/src/index.hbs +++ b/docs/website/src/index.hbs @@ -74,7 +74,8 @@

We chose YAML as the format for recipes, because it's easy to read and write, and it's familiar to most developers.

- 
name: my-recipe
+      
name: My recipe
+id: my-recipe
 stages:
   - id: build
     base: debian:sid-slim