github.com/canonical/ubuntu-image@v0.0.0-20240430122802-2202fe98b290/README.md (about)

     1  # ubuntu-image: build Ubuntu images
     2  
     3  [![ubuntu-image](https://snapcraft.io/ubuntu-image/badge.svg)](https://snapcraft.io/ubuntu-image)
     4  ![Build](https://github.com/canonical/ubuntu-image/actions/workflows/build-and-test.yml/badge.svg)
     5  [![codecov](https://codecov.io/gh/canonical/ubuntu-image/branch/main/graph/badge.svg?token=F9jE9HKo1a)](https://codecov.io/gh/canonical/ubuntu-image)
     6  [![Go Report Card](https://goreportcard.com/badge/github.com/canonical/ubuntu-image)](https://goreportcard.com/report/github.com/canonical/ubuntu-image)
     7  
     8  ubuntu-image is a tool used for generating bootable images. You can use it to build Ubuntu images such as:
     9  
    10  - Snap-based Ubuntu Core images from model assertions
    11  
    12  - Classical preinstalled Ubuntu images using image definitions
    13  
    14  The future versions of this tool will be more generalized, allowing users to build a wider range of Ubuntu images, including ISO/installer.
    15  
    16  ## Getting started
    17  
    18  ### Requirements
    19  
    20  * Ubuntu 18.04 (Bionic Beaver) or newer (recommended: Ubuntu 22.04 (Jammy Jellyfish))
    21  
    22  * Ability to install snaps ([SnapStore: ubuntu-image](https://snapcraft.io/ubuntu-image))
    23  
    24  ### Quickstart
    25  
    26  See [Build your first Ubuntu Core image](https://ubuntu.com/core/docs/build-an-image) for instructions on how to use ubuntu-image to build an Ubuntu core image on a **Raspberry Pi**.
    27  
    28  ## Building images
    29  
    30  ubuntu-image offers two basic sub-commands for building snap-based and classical images.
    31  
    32  ### Building snap-based images
    33  
    34  To build a snap-based image with ubuntu-image, you need a [model assertion](https://ubuntu.com/core/docs/reference/assertions/model). A model assertion is a YAML file that describes a particular combination of core, kernel, and gadget snaps, along with other declarations, signed with a digital signature asserting its authenticity. The `ubuntu-image` command only requires the path to this model assertion to build snap-based images.
    35  
    36  To build snap-based images with `ubuntu-image`, use the following command:
    37  
    38  ```
    39  ubuntu-image snap model.assertion
    40  ```
    41  
    42  See [Build your first Ubuntu Core image](https://ubuntu.com/core/docs/build-an-image) for more information on building snap-based images using ubuntu-image. To build an image with custom snaps, see [Build an image with custom snaps](https://ubuntu.com/core/docs/custom-images).
    43  
    44  ### Building classical images
    45  
    46  Classical images are built from image definitions, which are YAML files. The image definition YAML file specifies the various configurations required to build a classical image, including the path to the `gadget.yaml` file. See [Image Definition](internal/imagedefinition/README.rst) for the detailed specification of what is supported in the image definition YAML file.
    47  
    48  To build classical images with ubuntu-image, use the following command:
    49  
    50  ```
    51  ubuntu-image classic image_definition.yaml
    52  ```
    53  
    54  ## Building and testing ubuntu-image
    55  
    56  See [Contributing to ubuntu-image](/CONTRIBUTING.md) for instructions on how to set up, build, and test ubuntu-image in development mode.
    57  
    58  ## License
    59  
    60  The ubuntu-image project is licensed under [GNU General Public License v3.0](/LICENSE).
    61  
    62  ## Contributing to ubuntu-image
    63  
    64  To learn how to contribute to the ubuntu-image project, see [Contributing to ubuntu-image](/CONTRIBUTING.md).
    65  
    66  ## Project details
    67  
    68  * Project home: https://github.com/Canonical/ubuntu-image
    69  * Report bugs at: https://bugs.launchpad.net/ubuntu-image
    70  * Git clone: https://github.com/Canonical/ubuntu-image.git
    71  * Reference page: [`ubuntu-image` syntax and options](https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/ubuntu-image.html)
    72  * Building a gadget snap: [Building a gadget snap](https://ubuntu.com/core/docs/gadget-building)
    73  * Gadget tree: [pc-gadget](https://github.com/snapcore/pc-gadget)
    74  * `gadget.yaml` specification: [Gadget snaps](https://forum.snapcraft.io/t/gadget-snaps)