diff --git a/content/guides/how_to_build_your_first_image.md b/content/guides/how_to_build_your_first_image.md new file mode 100644 index 0000000000000000000000000000000000000000..657f8f884b8e4d91015ec2794e11a881e21997a4 --- /dev/null +++ b/content/guides/how_to_build_your_first_image.md @@ -0,0 +1,157 @@ ++++ +date = "2021-10-07" +weight = 100 +toc = true + +title = "How to Build Your First Image on Apertis" ++++ + +This guide aims to explain how to build your first image on Apertis +using the GitLab UI. A comprehensive documentation to manually build +a customized image is available at [Image building]( {{< ref "image_building.md" >}} ). + +This document will explain how to create a GitLab account and +how to use its UI and pipelines to modify and create a custom Apertis +image. + +# Create a GitLab account + +To build your Apertis image, you first need an account on the +[Apertis GitLab](https://gitlab.apertis.org) instance. + +To create one, please go on at <https://gitlab.apertis.org>, then click on `Sign in / Register`: + + + +On the next webpage, you will have a `Register now` button: + + +Fill the form, then click on `Register`: + + +At this step, you will have to wait until an administrator approves +your registration: + +` +You have signed up successfully. However, we could not sign you in +because your account is awaiting approval from your GitLab administrator. +` + +Once your account is approved, you will be notified through an email entitled +`Welcome to GitLab` from `<gitlab at gitlab.apertis.org>`. + +The next step is to set up your account. A first useful configuration is to add +your SSH key to be able to push/pull without having to give your +username/password for each action. +For this, you need to go into `Preferences`: + + +Then, into the `SSH Keys` part: + +The instructions [to generate a new key](https://gitlab.apertis.org/help/ssh/index#generate-an-ssh-key-pair) +or [to add an existing one](https://gitlab.apertis.org/help/ssh/index#see-if-you-have-an-existing-ssh-key-pair) +are available. +Please follow the relevant one to configure your SSH key. + +# Fork a repository + +It is now possible to fork a repository using the GitLab UI. +By forking a repository, you will copy a repository under your +GitLab namespace. That means you will be able to modify files of +the newly forked project, and then later you can eventually do a +`Merge request` to send your changes back to the *upstream* (or original) project. + +For this example, we will fork the `image-recipes-sample` example +repository at <https://gitlab.apertis.org/demo/image-recipes-sample>. +This repository contains a recipe to build a custom Apertis image for a +*Raspberry Pi* board. + +Click on the `Fork` button: + + +A form will be displayed, where you can add information regarding your fork: + + +By clicking on `Fork project`, you will engage the fork process +that it is confirmed by a message saying `Forking in progress`. +Then, after few seconds (or minutes depending of the size of the +repository), you will get a `The project was successfully forked` +message. + + +# Add new package to this image recipe + +In this example, we will add some `.deb` packages into our first customized +Apertis image. + +The recipe to generate an image is a `.yaml` file that is read and +used by [debos](https://github.com/go-debos/debos) to build the image. +The complete syntax of the debos `.yaml` is available on its +[GitHub repository](https://github.com/go-debos/debos) +or you can have a look at its [manpage](https://manpages.debian.org/unstable/debos/debos.1.en.html). + +We will modify the `image-rpi64.yaml` file in our just forked +`image-recipes-sample` repository. Scroll down until you see the +`image-rpi64.yaml` file: + + +Then, click on it and on the `Edit` button: + + +For our example, we will add two additional `.deb` packages +(`fonts-dejavu` and `flac`) to the image, for this we need to add the +following section in `image-rpi64.yaml`. +``` yaml + - action: apt + description: My additional packages + packages: + - fonts-dejavu + - flac +``` +We add it at the end of all *apt* actions and before the first +*run* action. +The order of the different `action` parts is important because these +are run sequentially by `debos`. + + +Add the new section, a commit message and then, click on `Commit changes`. +You should receive a `Your changes have been successfully committed` +message. + +# Build an Apertis image + +The GitLab CI uses a recipe to build the Apertis Image. +This is configured in the [.gitlab-ci.yml](https://gitlab.apertis.org/demo/image-recipes-sample/-/blob/main/.gitlab-ci.yml) +file located in the root directory of the repository. +Please refer to the official [GitLab CI documentation](https://docs.gitlab.com/ee/ci/) +for more information. + +The GitLab CI pipeline will generate a new Apertis Image for +each push (or commit through the UI) into the forked `image-recipes-sample` +repository. If needed, it is possible to generate an image on demand by +selecting `CI/CD`, then `Pipelines` in the sidebar. + + + +Then, click on `Run pipeline`, select on which branch the pipeline +should be run against and eventually some variables can be defined. +Finally, after another click on `Run pipeline`, the process will start. + +The progress of the building can be followed in `CI/CD`, then `Pipelines`: + + + +Once all jobs ran successfully (i.e. they should be in green), +it is possible to download the generated image by clicking on the +last job `apt-image-build...`. + + +Then, on `Download` at the right panel: + + +The image is also available from an URL, in our example we can +download the last image built for the original `images-recipe-sample` repository at +<https://gitlab.apertis.org/demo/image-recipes-sample/-/jobs/artifacts/main/download?job=apt-image-build-arm64-rpi64_containers-rpi64>. + +Please refer to these [instructions]( {{< ref "rpi4_setup.md" >}} ) +to setup and test your newly built image. diff --git a/static/images/apertis_gitlab_preferences.png b/static/images/apertis_gitlab_preferences.png new file mode 100644 index 0000000000000000000000000000000000000000..32b6ea479dffff54a61c98d9f4fa30cb7bddf2a4 Binary files /dev/null and b/static/images/apertis_gitlab_preferences.png differ diff --git a/static/images/apertis_gitlab_repo_commit.png b/static/images/apertis_gitlab_repo_commit.png new file mode 100644 index 0000000000000000000000000000000000000000..9b662723fcf233b6ccbde884fe20bd115984196a Binary files /dev/null and b/static/images/apertis_gitlab_repo_commit.png differ diff --git a/static/images/apertis_gitlab_repo_edit.png b/static/images/apertis_gitlab_repo_edit.png new file mode 100644 index 0000000000000000000000000000000000000000..5b98b06784d1dd0724c39994d482a9ca88ea5f22 Binary files /dev/null and b/static/images/apertis_gitlab_repo_edit.png differ diff --git a/static/images/apertis_gitlab_repo_example.png b/static/images/apertis_gitlab_repo_example.png new file mode 100644 index 0000000000000000000000000000000000000000..6e7631312b2a0926e765a36b5611c94abc92676a Binary files /dev/null and b/static/images/apertis_gitlab_repo_example.png differ diff --git a/static/images/apertis_gitlab_repo_fork.png b/static/images/apertis_gitlab_repo_fork.png new file mode 100644 index 0000000000000000000000000000000000000000..fc44025587d317f0869ee54589169519ada7ccf5 Binary files /dev/null and b/static/images/apertis_gitlab_repo_fork.png differ diff --git a/static/images/apertis_gitlab_repo_my_fork.png b/static/images/apertis_gitlab_repo_my_fork.png new file mode 100644 index 0000000000000000000000000000000000000000..baa7b85623396c09c4620d66c1707ff059ae372a Binary files /dev/null and b/static/images/apertis_gitlab_repo_my_fork.png differ diff --git a/static/images/apertis_gitlab_repo_pipeline_download.png b/static/images/apertis_gitlab_repo_pipeline_download.png new file mode 100644 index 0000000000000000000000000000000000000000..f3d330f3620034ff99db6a01825d2366c68c275a Binary files /dev/null and b/static/images/apertis_gitlab_repo_pipeline_download.png differ diff --git a/static/images/apertis_gitlab_repo_pipeline_jobs.png b/static/images/apertis_gitlab_repo_pipeline_jobs.png new file mode 100644 index 0000000000000000000000000000000000000000..2545b08caff01bcb22cb7fd83adbdbb746d9f741 Binary files /dev/null and b/static/images/apertis_gitlab_repo_pipeline_jobs.png differ diff --git a/static/images/apertis_gitlab_repo_pipeline_new_running.png b/static/images/apertis_gitlab_repo_pipeline_new_running.png new file mode 100644 index 0000000000000000000000000000000000000000..ead81cceb045bed27391bdbc5373218901f9a1cb Binary files /dev/null and b/static/images/apertis_gitlab_repo_pipeline_new_running.png differ diff --git a/static/images/apertis_gitlab_repo_pipelines.png b/static/images/apertis_gitlab_repo_pipelines.png new file mode 100644 index 0000000000000000000000000000000000000000..59cfc3dc63d0a0753a790429c9f607b4a793f497 Binary files /dev/null and b/static/images/apertis_gitlab_repo_pipelines.png differ diff --git a/static/images/apertis_gitlab_repo_scrolldown.png b/static/images/apertis_gitlab_repo_scrolldown.png new file mode 100644 index 0000000000000000000000000000000000000000..169cb3ffcca7a5471ef0ecd1b8251f5296f55816 Binary files /dev/null and b/static/images/apertis_gitlab_repo_scrolldown.png differ diff --git a/static/images/apertis_gitlab_signin.png b/static/images/apertis_gitlab_signin.png new file mode 100644 index 0000000000000000000000000000000000000000..2082d6b6ddd8bfc2143fab0ad681f1ecad8be5f3 Binary files /dev/null and b/static/images/apertis_gitlab_signin.png differ diff --git a/static/images/apertis_gitlab_signup.png b/static/images/apertis_gitlab_signup.png new file mode 100644 index 0000000000000000000000000000000000000000..c4c1b5715bf1dbbf4ebabb3967e6e582a85aea36 Binary files /dev/null and b/static/images/apertis_gitlab_signup.png differ diff --git a/static/images/apertis_gitlab_ssh.png b/static/images/apertis_gitlab_ssh.png new file mode 100644 index 0000000000000000000000000000000000000000..ab173bc937091fd9a5b6bfa9ca8e1d739d43e033 Binary files /dev/null and b/static/images/apertis_gitlab_ssh.png differ diff --git a/static/images/apertis_gitlab_website.png b/static/images/apertis_gitlab_website.png new file mode 100644 index 0000000000000000000000000000000000000000..e8182cec9d278b8f092d4c2189b43c69e5406e18 Binary files /dev/null and b/static/images/apertis_gitlab_website.png differ