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)