Repository: canonical/imagecraft
Pull request #109: docs: Clean and document new fields
Author: login: upils
Created: 2025-03-18T10:47:00Z | Merged: 2025-03-24T15:50:12Z

- [ ] Have you followed the guidelines for contributing?
- [ ] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
- [ ] Have you successfully run `make lint && make test`?

---

- add documentation on overlay
- clean references to `ubuntu-image`
- document the `volumes` section of the `imagecraft.yaml` (and other common fields)
- add a better `imagecraft.yaml` example (will evolve in future PRs but is now closer to what imagecraft expects)


Diff:
diff --git a/.gitignore b/.gitignore
index e8dcd1a7..1d3b62cc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -148,6 +148,7 @@ dmypy.json
 # sphinx
 docs/warnings.txt
 docs/.sphinx/.wordlist.dic
+docs/reference/commands
 .DS_Store
 __pycache__
 .idea/
diff --git a/docs/conf.py b/docs/conf.py
index 69480b01..91d652f5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -41,6 +41,10 @@
     "github_url": "https://github.com/canonical/imagecraft",
 }
 
+html_theme_options = {
+    "source_edit_link": "https://github.com/canonical/imagecraft",
+}
+
 extensions = [
     "canonical_sphinx",
     "notfound.extension",
@@ -119,6 +123,7 @@
     "common/craft-parts/reference/plugins/scons_plugin.rst",
     "common/craft-parts/reference/plugins/go_use_plugin.rst",
     "common/craft-parts/reference/plugins/uv_plugin.rst",
+    "common/craft-parts/reference/plugins/jlink_plugin.rst",
 ]
 
 linkcheck_ignore = ["http://127.0.0.1:8000", "https://apt-repo.com"]
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
index 26e5b6cd..0d9edca9 100644
--- a/docs/explanation/index.rst
+++ b/docs/explanation/index.rst
@@ -6,5 +6,6 @@ Explanation
 .. toctree::
     :maxdepth: 1
 
-    security-overview
     parts
+    overlay-step
+    security-overview
diff --git a/docs/explanation/overlay-step.rst b/docs/explanation/overlay-step.rst
new file mode 100644
index 00000000..b981e12d
--- /dev/null
+++ b/docs/explanation/overlay-step.rst
@@ -0,0 +1,19 @@
+.. _overlays:
+
+Overlay step
+============
+
+Images are built in a sequence of :doc:`five separate steps
+</reference/part-lifecycle-details>` -- pull, overlay, build, stage, and prime.
+
+The overlay step in each part provides the means to refine the contents of the
+image. ``overlay-script`` will run the provided script in this step.
+The location of the default overlay is made available in the ``${CRAFT_OVERLAY}``
+environment variable.
+The location of the partition-specific overlays is made available in the
+``${CRAFT_<partition>_OVERLAY}`` environment variables.
+``overlay`` can be used to specify which files will be
+migrated to the next steps, and when omitted its default value will be ``"*"``.
+
+.. Include a section about overlay parameters from the Craft Parts documentation.
+.. include:: /common/craft-parts/explanation/overlay_parameters.rst
diff --git a/docs/explanation/parts.rst b/docs/explanation/parts.rst
index 572bc18a..fff7f4b4 100644
--- a/docs/explanation/parts.rst
+++ b/docs/explanation/parts.rst
@@ -2,10 +2,5 @@
 
 .. include:: /common/craft-parts/explanation/parts.rst
    :end-before: _include-how-parts-are-built:
-..
-  exclude the overlay step explanation from craft-parts
-.. include:: /common/craft-parts/explanation/how_parts_are_built.rst
-   :end-before: _overlay-step-begin:
 
 .. include:: /common/craft-parts/explanation/how_parts_are_built.rst
-   :start-after: _overlay-step-end:
diff --git a/docs/explanation/security-overview.rst b/docs/explanation/security-overview.rst
index cc2d588b..057fc3ae 100644
--- a/docs/explanation/security-overview.rst
+++ b/docs/explanation/security-overview.rst
@@ -13,34 +13,3 @@ Privileged execution
 destructive mode). It is recommended to use a dedicated building machine. Make sure
 ``imagecraft`` is installed from a trusted source, and the provided configuration is
 trusted.
-
-
-Cryptography
-------------
-
-``imagecraft`` is a wrapper around several tools and mainly ``ubuntu-image``. The tool
-itself does not use cryptographic technologies. Refer to the `ubuntu-image security
-overview`_ for details on cryptographic technologies used in ``ubuntu-image``.
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-- Secrets (passwords and hashes) can be present in the configuration files provided to
-  ``imagecraft`` to build images. Specifically, in the ``ubuntu-bootstrap`` plugin
-  configuration:
-
-  * In the ``extra-ppas`` customisation section, authentication tokens
-    (``user:password``) can be defined to access private PPAs. These values are used to
-    write the ``apt`` configuration without any treatment.
-  * In the ``manual`` customisation section, user accounts can be defined with plain
-    text or hashed passwords. These values are directly passed to the ``chpassword``
-    utility without any treatment.
-
-- These configuration files for secrets should then be securely stored, and if secrets
-  are used, they should ideally be injected at runtime.
-
-
-.. LINKS
-
-.. _ubuntu-image security overview: https://canonical-subiquity.readthedocs-hosted.com/en/latest/explanation/ubuntu-image-security-overview.html
diff --git a/docs/reference/code/example/imagecraft.yaml b/docs/reference/code/example/imagecraft.yaml
index 4e8b1053..d28c2701 100644
--- a/docs/reference/code/example/imagecraft.yaml
+++ b/docs/reference/code/example/imagecraft.yaml
@@ -1,43 +1,69 @@
-name: ubuntu-server-amd64
-version: "1"
-base: ubuntu@24.04
-series: noble
+name: ubuntu-minimal
+version: "24.04.20241217"
+base: bare
+build-base: ubuntu@24.04
+
 platforms:
   amd64:
-    build-for: [amd64]
-    build-on: [amd64]
-
-package-repositories:
-  - type: apt
-    components: [main, restricted, universe, multiverse]
-    url: http://archive.ubuntu.com/ubuntu/
-    pocket: updates
-    used-for: build
 
 parts:
-  gadget:
-    plugin: gadget
-    source: https://github.com/snapcore/pc-gadget.git
-    source-branch: classic
   rootfs:
-    plugin: ubuntu-bootstrap
-    ubuntu-bootstrap-pocket: updates
-    ubuntu-bootstrap-germinate:
-      urls:
-        - "git://git.launchpad.net/~ubuntu-core-dev/ubuntu-seeds/+git/"
-      branch: noble
-      vcs: true
-      names:
-        - server
-        - minimal
-        - standard
-        - cloud-image
-    ubuntu-bootstrap-kernel: linux-image-generic
-    ubuntu-bootstrap-extra-snaps: [snapd]
-    stage:
-      - -rootfs/etc/cloud/cloud.cfg.d/90_dpkg.cfg
-  cloud-init:
-    plugin: dump
-    source: cloud-init/
+    plugin: nil
+    overlay-script: |
+      mmdebstrap --arch amd64 --mode=sudo --format=dir --variant=minbase --include=apt noble $CRAFT_OVERLAY/ http://archive.ubuntu.com/ubuntu/
     organize:
-      '*': rootfs/
+      "*": (volume/party/rootfs)/
+
+  packages:
+    plugin: nil
+    after: [rootfs]
+    overlay-script: |
+      mkdir -p $CRAFT_OVERLAY/dev $CRAFT_OVERLAY/sys $CRAFT_OVERLAY/proc
+      mount -t devtmpfs devtmpfs-build $CRAFT_OVERLAY/dev
+      mount -t devpts devpts-build -o nodev,nosuid $CRAFT_OVERLAY/dev/pts
+      mount -t sysfs sysfs-build $CRAFT_OVERLAY/sys
+      mount -t proc proc-build $CRAFT_OVERLAY/proc
+      mount --bind /run $CRAFT_OVERLAY/run
+
+      DEBIAN_FRONTEND=noninteractive chroot $CRAFT_OVERLAY apt update
+      DEBIAN_FRONTEND=noninteractive chroot $CRAFT_OVERLAY apt install --assume-yes --quiet \
+        --option=Dpkg::options::=--force-unsafe-io --option=Dpkg::Options::=--force-confold \
+        ubuntu-server-minimal
+
+      mount --make-rprivate $CRAFT_OVERLAY/run
+      umount --recursive $CRAFT_OVERLAY/run
+      mount --make-rprivate $CRAFT_OVERLAY/sys
+      umount --recursive $CRAFT_OVERLAY/sys
+      mount --make-rprivate $CRAFT_OVERLAY/proc
+      umount --recursive $CRAFT_OVERLAY/proc
+      mount --make-rprivate $CRAFT_OVERLAY/dev/pts
+      umount --recursive $CRAFT_OVERLAY/dev/pts
+      mount --make-rprivate $CRAFT_OVERLAY/dev
+      umount --recursive $CRAFT_OVERLAY/dev
+
+  snaps:
+    plugin: nil
+    after: [kernel]
+    overlay-script: |
+      snap prepare-image --classic --arch=amd64 \
+        --snap snapd --snap core24 "" $CRAFT_OVERLAY
+      /usr/lib/snapd/snap-preseed $CRAFT_OVERLAY
+      mv $CRAFT_OVERLAY/boot/* $CRAFT_VOLUME_PC_EFI_OVERLAY/boot/
+      mv $CRAFT_OVERLAY/* $CRAFT_VOLUME_PC_ROOTFS_OVERLAY/
+
+volumes:
+  pc:
+    schema: gpt
+    structure:
+      - name: efi
+        type: C12A7328-F81F-11D2-BA4B-00A0C93EC93B
+        filesystem: vfat
+        role: system-boot
+        filesystem-label: EFI System
+        size: 256MiB
+      - name: rootfs
+        type: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
+        filesystem: ext4
+        filesystem-label: writable
+        role: system-data
+        size: 6GiB
diff --git a/docs/reference/commands/build.rst b/docs/reference/commands/build.rst
deleted file mode 100644
index 0790a732..00000000
--- a/docs/reference/commands/build.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-
-.. _ref_commands_build:
-
-build
-=====
-
-Build artifacts defined for a part. If part names are specified only
-those parts will be built, otherwise all parts will be built.
-
-
-Usage
------
-
-:command:`imagecraft build [options] <part-name>`
-
-Required
---------
-
-``part-name``
-   Optional list of parts to process.
-
-Options
--------
-
-``--build-for``
-   Set architecture to build for.
-``--debug``
-   Shell into the environment if the build fails.
-``--destructive-mode``
-   Build in the current host.
-``--platform``
-   Set platform to build for.
-``--shell``
-   Shell into the environment in lieu of the step to run.
-``--shell-after``
-   Shell into the environment after the step has run.
-``--use-lxd``
-   Build in a LXD container.
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/commands/clean.rst b/docs/reference/commands/clean.rst
deleted file mode 100644
index e426ff1c..00000000
--- a/docs/reference/commands/clean.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-
-.. _ref_commands_clean:
-
-clean
-=====
-
-Clean up artifacts belonging to parts. If no parts are specified,
-remove the packing environment.
-
-
-Usage
------
-
-:command:`imagecraft clean [options] <part-name>`
-
-Required
---------
-
-``part-name``
-   Optional list of parts to process.
-
-Options
--------
-
-``--destructive-mode``
-   Build in the current host.
-``--platform``
-   Platform to clean.
-``--use-lxd``
-   Build in a LXD container.
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/commands/lifecycle-commands.rst b/docs/reference/commands/lifecycle-commands.rst
deleted file mode 100644
index ff79507e..00000000
--- a/docs/reference/commands/lifecycle-commands.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-:ref:`ref_commands_build`
-   Build artifacts defined for a part.
-
-:ref:`ref_commands_clean`
-   Remove a part's assets.
-
-:ref:`ref_commands_pack`
-   Create the final artifact.
-
-:ref:`ref_commands_prime`
-   Prime artifacts defined for a part.
-
-:ref:`ref_commands_pull`
-   Download or retrieve artifacts defined for a part.
-
-:ref:`ref_commands_stage`
-   Stage built artifacts into a common staging area.
-
diff --git a/docs/reference/commands/other-commands.rst b/docs/reference/commands/other-commands.rst
deleted file mode 100644
index e69de29b..00000000
diff --git a/docs/reference/commands/overlay.rst b/docs/reference/commands/overlay.rst
deleted file mode 100644
index d5b568f7..00000000
--- a/docs/reference/commands/overlay.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-
-.. _ref_commands_overlay:
-
-overlay
-=======
-
-Execute operations defined for each part on a layer over the base
-filesystem, potentially modifying its contents.
-
-
-Usage
------
-
-:command:`imagecraft overlay [options] <part-name>`
-
-Required
---------
-
-``part-name``
-   Optional list of parts to process.
-
-Options
--------
-
-``--build-for``
-   Set architecture to build for.
-``--debug``
-   Shell into the environment if the build fails.
-``--destructive-mode``
-   Build in the current host.
-``--platform``
-   Set platform to build for.
-``--shell``
-   Shell into the environment in lieu of the step to run.
-``--shell-after``
-   Shell into the environment after the step has run.
-``--use-lxd``
-   Build in a LXD container.
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/commands/pack.rst b/docs/reference/commands/pack.rst
deleted file mode 100644
index eb64baad..00000000
--- a/docs/reference/commands/pack.rst
+++ /dev/null
@@ -1,49 +0,0 @@
-
-.. _ref_commands_pack:
-
-pack
-====
-
-Process parts and create the final artifact.
-
-
-Usage
------
-
-:command:`imagecraft pack [options]`
-
-
-Options
--------
-
-``--build-for``
-   Set architecture to build for.
-``--debug``
-   Shell into the environment if the build fails.
-``--destructive-mode``
-   Build in the current host.
-``--output`` or ``-o``
-   Output directory for created packages.
-``--platform``
-   Set platform to build for.
-``--shell``
-   Shell into the environment in lieu of the step to run.
-``--shell-after``
-   Shell into the environment after the step has run.
-``--use-lxd``
-   Build in a LXD container.
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/commands/prime.rst b/docs/reference/commands/prime.rst
deleted file mode 100644
index e732e1c0..00000000
--- a/docs/reference/commands/prime.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-
-.. _ref_commands_prime:
-
-prime
-=====
-
-Prepare the final payload to be packed, performing additional
-processing and adding metadata files. If part names are specified only
-those parts will be primed. The default is to prime all parts.
-
-
-Usage
------
-
-:command:`imagecraft prime [options] <part-name>`
-
-Required
---------
-
-``part-name``
-   Optional list of parts to process.
-
-Options
--------
-
-``--build-for``
-   Set architecture to build for.
-``--debug``
-   Shell into the environment if the build fails.
-``--destructive-mode``
-   Build in the current host.
-``--platform``
-   Set platform to build for.
-``--shell``
-   Shell into the environment in lieu of the step to run.
-``--shell-after``
-   Shell into the environment after the step has run.
-``--use-lxd``
-   Build in a LXD container.
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/commands/pull.rst b/docs/reference/commands/pull.rst
deleted file mode 100644
index 5a41d99c..00000000
--- a/docs/reference/commands/pull.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-
-.. _ref_commands_pull:
-
-pull
-====
-
-Download or retrieve artifacts defined for a part. If part names
-are specified only those parts will be pulled, otherwise all parts
-will be pulled.
-
-
-Usage
------
-
-:command:`imagecraft pull [options] <part-name>`
-
-Required
---------
-
-``part-name``
-   Optional list of parts to process.
-
-Options
--------
-
-``--build-for``
-   Set architecture to build for.
-``--debug``
-   Shell into the environment if the build fails.
-``--destructive-mode``
-   Build in the current host.
-``--platform``
-   Set platform to build for.
-``--shell``
-   Shell into the environment in lieu of the step to run.
-``--shell-after``
-   Shell into the environment after the step has run.
-``--use-lxd``
-   Build in a LXD container.
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/commands/stage.rst b/docs/reference/commands/stage.rst
deleted file mode 100644
index ece8b837..00000000
--- a/docs/reference/commands/stage.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-
-.. _ref_commands_stage:
-
-stage
-=====
-
-Stage built artifacts into a common staging area. If part names are
-specified only those parts will be staged. The default is to stage
-all parts.
-
-
-Usage
------
-
-:command:`imagecraft stage [options] <part-name>`
-
-Required
---------
-
-``part-name``
-   Optional list of parts to process.
-
-Options
--------
-
-``--build-for``
-   Set architecture to build for.
-``--debug``
-   Shell into the environment if the build fails.
-``--destructive-mode``
-   Build in the current host.
-``--platform``
-   Set platform to build for.
-``--shell``
-   Shell into the environment in lieu of the step to run.
-``--shell-after``
-   Shell into the environment after the step has run.
-``--use-lxd``
-   Build in a LXD container.
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/commands/toc.rst b/docs/reference/commands/toc.rst
deleted file mode 100644
index 80056166..00000000
--- a/docs/reference/commands/toc.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. toctree::
-   :hidden:
-
-   /reference/commands/build
-   /reference/commands/clean
-   /reference/commands/overlay
-   /reference/commands/pack
-   /reference/commands/prime
-   /reference/commands/pull
-   /reference/commands/stage
-   /reference/commands/version
diff --git a/docs/reference/commands/version.rst b/docs/reference/commands/version.rst
deleted file mode 100644
index d3178527..00000000
--- a/docs/reference/commands/version.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-
-.. _ref_commands_version:
-
-version
-=======
-Show the application version and exit
-
-Usage
------
-
-:command:`imagecraft version [options]`
-
-
-
-Global options
---------------
-
-``-h`` or ``--help``
-   Show this help message and exit.
-``-q`` or ``--quiet``
-   Only show warnings and errors, not progress.
-``-v`` or ``--verbose``
-   Show debug information and be more verbose.
-``--verbosity``
-   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
-``-V`` or ``--version``
-   Show the application version and exit.
-
diff --git a/docs/reference/image_parts/toc.rst b/docs/reference/image_parts/toc.rst
deleted file mode 100644
index 934cfe26..00000000
--- a/docs/reference/image_parts/toc.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. toctree::
-   :hidden:
-
-   /common/craft-parts/reference/part_properties
diff --git a/docs/reference/imagecraft-yaml-file.rst b/docs/reference/imagecraft-yaml-file.rst
index e0f098bb..bc1f5979 100644
--- a/docs/reference/imagecraft-yaml-file.rst
+++ b/docs/reference/imagecraft-yaml-file.rst
@@ -3,8 +3,6 @@
 ``imagecraft.yaml`` file
 ========================
 
-.. include:: image_parts/toc.rst
-
 An Imagecraft project is defined in a YAML file named ``imagecraft.yaml``
 at the root of the project tree in the filesystem.
 
@@ -12,8 +10,8 @@ This Reference section is for when you need to know which options can be
 used, and how, in this ``imagecraft.yaml`` file.
 
 
-``name``
---------
+name
+----
 
 **Type**: string
 
@@ -27,8 +25,8 @@ The name of the image. This value must:
 - not end with a hyphen, and must not contain two or more consecutive
   hyphens.
 
-``title``
----------
+title
+-----
 
 **Type**: string
 
@@ -36,8 +34,8 @@ The name of the image. This value must:
 
 The human-readable title of the image. If omitted, defaults to ``name``.
 
-``summary``
------------
+summary
+-------
 
 **Type**: string
 
@@ -45,8 +43,8 @@ The human-readable title of the image. If omitted, defaults to ``name``.
 
 A short summary describing the image.
 
-``description``
----------------
+description
+-----------
 
 **Type**: string
 
@@ -54,8 +52,8 @@ A short summary describing the image.
 
 A longer, possibly multi-line description of the image.
 
-``version``
------------
+version
+-------
 
 **Type**: string
 
@@ -63,9 +61,44 @@ A longer, possibly multi-line description of the image.
 
 The imagecraft configuration version, used to track changes to the configuration file.
 
+base
+----
+
+**Type**: string ``bare``
+
+**Required**: Yes
+
+Base to use as a first layer for the image.
+
+build-base
+----------
+
+**Type**: One of ``ubuntu@20.04 | ubuntu@22.04 | ubuntu@24.04 | devel``
 
-``platforms``
--------------
+**Required**: Yes
+
+The system and version that will be used during the build, but not
+included in the final image itself. It comprises the set of tools and libraries
+that Imagecraft will use when building the image contents.
+
+.. note::
+   ``devel`` is a "special" value that means "the next Ubuntu version, currently
+   in development". This means that the contents of this system changes
+   frequently and should not be relied on for production images.
+
+license
+-------
+
+**Type**: string, in `SPDX format <https://spdx.org/licenses/>`_
+
+**Required**: No
+
+The license of the software packaged inside the image. This must either be
+"proprietary" or match the SPDX format. It is case insensitive (e.g. both
+``MIT`` and ``mit`` are valid).
+
+platforms
+---------
 
 **Type**: dict
 
@@ -82,30 +115,30 @@ supported architecture (in Debian format).
    the host where Imagecraft is being executed (i.e. emulation is not supported
    at the moment).
 
-``platforms.<entry>.build-for``
--------------------------------
+platforms.<platform>.build-for
+------------------------------
 
 **Type**: string | list[string]
 
-**Required**: Yes, if ``<entry>`` is not a supported architecture name.
+**Required**: Yes, if ``<platform>`` is not a supported architecture name.
 
-Target architecture the image will be built for. Defaults to ``<entry>`` that
-is a valid, supported architecture name.
+Target architecture the image will be built for. Defaults to ``<platform>`` that is a
+valid, supported architecture name.
 
 .. note::
    At the moment Imagecraft will only build for a single architecture, so
    if provided ``build-for`` must be a single string or a list with exactly one
    element.
 
-``platforms.<entry>.build-on``
-------------------------------
+platforms.<platform>.build-on
+-----------------------------
 
 **Type**: string | list[string]
 
-**Required**: Yes, if ``build-for`` is specified *or* if ``<entry>`` is not a
+**Required**: Yes, if ``build-for`` is specified *or* if ``<platform>`` is not a
 supported architecture name.
 
-Host architectures where the image will be built. Defaults to ``<entry>`` if that
+Host architectures where the image will be built. Defaults to ``<platform>`` if that
 is a valid, supported architecture name.
 
 .. note::
@@ -113,15 +146,120 @@ is a valid, supported architecture name.
    if provided ``build-on`` must be a single string or a list with exactly one
    element.
 
-``parts``
----------
+parts
+-----
 
 **Type**: dict
 
 **Required**: Yes
 
-The set of parts that compose the image's contents
-(see :doc:`/common/craft-parts/reference/part_properties`).
+The set of parts that compose the image's contents. See :ref:`part_properties`
+for more details.
+
+volumes
+-------
+
+**Type**: dict (single entry)
+
+**Required**: Yes
+
+Structure and content of the image. A volume represents a "disk".
+
+volumes.<volume>.schema
+-----------------------
+
+**Type**: string ``gpt``
+
+**Required**: Yes
+
+Partitioning schema to use.
+
+volumes.<volume>.structure
+--------------------------
+
+**Type**: dict (at least one node entry)
+
+**Required**: Yes
+
+Structure of the image, defining partitions.
+
+volumes.<volume>.structure.<item>.name
+---------------------------------------
+
+**Type**: string
+
+**Required**: Yes
+
+Structure item name. Must respect the following:
+- contain only lowercase letters [a-z] or hyphens;
+- cannot start or end with a hyphen;
+- maximum length: 36 characters (maximum of a partition name
+for GPT in the UTF-16 character set);
+
+Structure names must be unique in a volume.
+
+volumes.<volume>.structure.<item>.id
+------------------------------------
+
+**Type**: string
+
+**Required**: No
+
+GPT unique partition id.
+
+volumes.<volume>.structure.<item>.role
+--------------------------------------
+
+**Type**: One of ``system-boot | system-data``
+
+**Required**: Yes
+
+Role defines a special role for this item in the image.
+- ``system-boot``: Partition holding the boot assets.
+- ``system-data``: Partition holding the main operating system data.
+
+volumes.<volume>.structure.<item>.type
+--------------------------------------
+
+**Type**: string
+
+**Required**: Yes
+
+Type of structure. A GPT partition type GUID.
+
+volumes.<volume>.structure.<item>.size
+--------------------------------------
+
+**Type**: string
+
+**Required**: Yes
+
+Size for structure item. Conforms to the IEC 80000-13 Standard.
+
+.. collapse:: Example
+
+    .. code-block:: yaml
+
+        size: "6GiB"
+
+volumes.<volume>.structure.<item>.filesystem
+--------------------------------------------
+
+**Type**: One of ``fat16 | vfat | ext4 | ext3``
+
+**Required**: Yes
+
+Filesystem type.
+
+volumes.<volume>.structure.<item>.filesystem-label
+--------------------------------------------------
+
+**Type**: string
+
+**Required**: No
+
+Filesystem label. Defaults to name of structure item.
+Labels must be unique in a volume.
 
 
 Example file
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 87f99c57..377c5ecd 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -7,13 +7,8 @@ Reference
     :maxdepth: 1
 
     imagecraft-yaml-file
+    /common/craft-parts/reference/part_properties
     commands
     parts-steps
     part-lifecycle-details
     /common/craft-parts/explanation/filesets
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
diff --git a/docs/reference/parts-steps.rst b/docs/reference/parts-steps.rst
index 6c4628c5..ae8c952d 100644
--- a/docs/reference/parts-steps.rst
+++ b/docs/reference/parts-steps.rst
@@ -5,3 +5,5 @@
 .. include:: /common/craft-parts/reference/step_execution_environment.rst
 
 .. include:: /common/craft-parts/reference/step_output_directories.rst
+
+.. include:: /common/craft-parts/reference/partition_specific_output_directory_variables.rst


Reviews:
user: login: medubelko
body: > @medubelko is the integration of the parts properties now closer to what you had in mind?

Yes! But, it has some side effects I didn't anticipate. I'll come up with an alternative soon.

I left some questions and suggestions.
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T01:18:26Z
user: login: upils
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T09:16:33Z
user: login: upils
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T10:05:58Z
user: login: upils
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T10:27:26Z
user: login: upils
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T10:48:09Z
user: login: upils
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T10:51:35Z
user: login: medubelko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T22:15:14Z
user: login: medubelko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T22:18:30Z
user: login: medubelko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T22:26:33Z
user: login: medubelko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T22:30:06Z
user: login: medubelko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T22:30:34Z
user: login: medubelko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T22:52:59Z
user: login: upils
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T08:02:23Z
user: login: medubelko
body: @upils I tweaked the key format to be more in line with what the extension will produce.
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T23:13:05Z
user: login: tigarmo
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-24T11:50:44Z

Review comments:
diff_hunk: @@ -0,0 +1,20 @@
+.. _overlays:
+
+Overlay step
+============
+
+Images are built in a sequence of five separate steps: pull, overlay,
+build, stage and prime.
+
+The overlay step is configured with overlay parameters.
+To learn more about pull, build, stage and prime see
+:doc:`/reference/part-lifecycle-details`
path: docs/explanation/overlay-step.rst
user: login: medubelko
body: ```suggestion
Images are built in a sequence of :doc:`five separate steps
</reference/part-lifecycle-details>` -- pull, overlay, build, stage, and prime.
```
created_at: 2025-03-20T00:28:48Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,20 @@
+.. _overlays:
+
+Overlay step
+============
+
+Images are built in a sequence of five separate steps: pull, overlay,
+build, stage and prime.
+
+The overlay step is configured with overlay parameters.
+To learn more about pull, build, stage and prime see
+:doc:`/reference/part-lifecycle-details`
+
+The overlay step provides the means to refine the content of an image parts
+after parts. ``overlay-script`` will run the provided script in this step.
path: docs/explanation/overlay-step.rst
user: login: medubelko
body: > of an image parts after parts.

Should this be "of an image's parts"?
created_at: 2025-03-20T00:56:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,20 @@
+.. _overlays:
+
+Overlay step
+============
+
+Images are built in a sequence of five separate steps: pull, overlay,
+build, stage and prime.
+
+The overlay step is configured with overlay parameters.
+To learn more about pull, build, stage and prime see
+:doc:`/reference/part-lifecycle-details`
+
+The overlay step provides the means to refine the content of an image parts
+after parts. ``overlay-script`` will run the provided script in this step.
+The location of the overlay is made available in the ${CRAFT_OVERLAY}
path: docs/explanation/overlay-step.rst
user: login: medubelko
body: ```suggestion
The location of the overlay is made available in the ``${CRAFT_OVERLAY}``
```
created_at: 2025-03-20T00:56:37Z
author_association: CONTRIBUTOR
path: docs/explanation/overlay-step.rst
user: login: medubelko
body: I think this topic would fit better as a reference. There isn't much of a thesis, but rather a mechanical description of how the overlay step works in the app.
created_at: 2025-03-20T00:58:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,52 @@
+
+.. _ref_commands_init:
+
+init
+====
+
+Initialise a project.
+
+If '<project-dir>' is provided, initialise in that directory,
+otherwise initialise in the current working directory.
+
+If '--name <name>' is provided, the project will be named '<name>'.
+Otherwise, the project will be named after the directory it is initialised in.
+
+'--profile <profile>' is used to initialise the project for a specific use case.
+
+Init can work in an existing project directory. If there are any files in the
+directory that would be overwritten, then init command will fail.
path: docs/reference/commands/init.rst
user: login: medubelko
body: What do you think about my reviewing the command strings as a 25.10 task, for alignment with our CLI specs? I've done it for some of the other new apps.
created_at: 2025-03-20T01:00:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -18,29 +18,5 @@ trusted.
 Cryptography
 ------------
 
-``imagecraft`` is a wrapper around several tools and mainly ``ubuntu-image``. The tool
-itself does not use cryptographic technologies. Refer to the `ubuntu-image security
-overview`_ for details on cryptographic technologies used in ``ubuntu-image``.
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-- Secrets (passwords and hashes) can be present in the configuration files provided to
-  ``imagecraft`` to build images. Specifically, in the ``ubuntu-bootstrap`` plugin
-  configuration:
-
-  * In the ``extra-ppas`` customisation section, authentication tokens
-    (``user:password``) can be defined to access private PPAs. These values are used to
-    write the ``apt`` configuration without any treatment.
-  * In the ``manual`` customisation section, user accounts can be defined with plain
-    text or hashed passwords. These values are directly passed to the ``chpassword``
-    utility without any treatment.
-
-- These configuration files for secrets should then be securely stored, and if secrets
-  are used, they should ideally be injected at runtime.
-
-
-.. LINKS
-
-.. _ubuntu-image security overview: https://canonical-subiquity.readthedocs-hosted.com/en/latest/explanation/ubuntu-image-security-overview.html
+``imagecraft`` is a wrapper around several tools. The tool itself does not use
+cryptographic technologies.
path: docs/explanation/security-overview.rst
user: login: medubelko
body: Double-checking: was this cleared with the relevant stakeholders?
created_at: 2025-03-20T01:02:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,5 @@
+:ref:`ref_commands_init`
+   Create an initial project filetree.
+
+:ref:`ref_commands_version`
+   Show the application version and exit.
path: docs/reference/commands/other-commands.rst
user: login: medubelko
body: I don't quite understand why we needed to transclude these – couldn't we have included this content and `lifecycle-commands.rst` directly in `commands.rst`?
created_at: 2025-03-20T01:08:47Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,20 @@
+.. _overlays:
+
+Overlay step
+============
+
+Images are built in a sequence of five separate steps: pull, overlay,
+build, stage and prime.
+
+The overlay step is configured with overlay parameters.
+To learn more about pull, build, stage and prime see
+:doc:`/reference/part-lifecycle-details`
+
+The overlay step provides the means to refine the content of an image parts
+after parts. ``overlay-script`` will run the provided script in this step.
path: docs/explanation/overlay-step.rst
user: login: upils
body: In the context of imagecraft the overlay is not so much a "env to build stuff in" but the actual target of the building process. The idea is to bootstrap a rootfs in the first part and then refine/add content/packages in it via the following parts. The part themselves will just hold what was added/modified but the consolidated result (when the overlay is fully mounted/merged) will be a full rootfs.

If you want I can show you a demo to clarify that.
created_at: 2025-03-20T09:16:33Z
author_association: CONTRIBUTOR
path: docs/explanation/overlay-step.rst
user: login: upils
body: I do not have strong opinion on that but this page includes another one from the explanation section of craft-parts. So out of coherence I am tempted to keep it here. What do you think?
created_at: 2025-03-20T10:05:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -18,29 +18,5 @@ trusted.
 Cryptography
 ------------
 
-``imagecraft`` is a wrapper around several tools and mainly ``ubuntu-image``. The tool
-itself does not use cryptographic technologies. Refer to the `ubuntu-image security
-overview`_ for details on cryptographic technologies used in ``ubuntu-image``.
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-- Secrets (passwords and hashes) can be present in the configuration files provided to
-  ``imagecraft`` to build images. Specifically, in the ``ubuntu-bootstrap`` plugin
-  configuration:
-
-  * In the ``extra-ppas`` customisation section, authentication tokens
-    (``user:password``) can be defined to access private PPAs. These values are used to
-    write the ``apt`` configuration without any treatment.
-  * In the ``manual`` customisation section, user accounts can be defined with plain
-    text or hashed passwords. These values are directly passed to the ``chpassword``
-    utility without any treatment.
-
-- These configuration files for secrets should then be securely stored, and if secrets
-  are used, they should ideally be injected at runtime.
-
-
-.. LINKS
-
-.. _ubuntu-image security overview: https://canonical-subiquity.readthedocs-hosted.com/en/latest/explanation/ubuntu-image-security-overview.html
+``imagecraft`` is a wrapper around several tools. The tool itself does not use
+cryptographic technologies.
path: docs/explanation/security-overview.rst
user: login: upils
body: Imagecraft is not using `ubuntu-image` anymore. The `ubuntu-bootstrap` is also gone. Even if imagecraft's code is not doing any cryptographic operation, the craft framework probably do. I did not fully evaluated this, so what do you think of completely removing this `Cryptographic` section until I can properly assert that next cycle?
created_at: 2025-03-20T10:27:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,5 @@
+:ref:`ref_commands_init`
+   Create an initial project filetree.
+
+:ref:`ref_commands_version`
+   Show the application version and exit.
path: docs/reference/commands/other-commands.rst
user: login: upils
body: I do not know enough about sphinx best practices to know if this is needed or not. I suggest reworking that for both files if we want in another PR.
created_at: 2025-03-20T10:48:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,52 @@
+
+.. _ref_commands_init:
+
+init
+====
+
+Initialise a project.
+
+If '<project-dir>' is provided, initialise in that directory,
+otherwise initialise in the current working directory.
+
+If '--name <name>' is provided, the project will be named '<name>'.
+Otherwise, the project will be named after the directory it is initialised in.
+
+'--profile <profile>' is used to initialise the project for a specific use case.
+
+Init can work in an existing project directory. If there are any files in the
+directory that would be overwritten, then init command will fail.
path: docs/reference/commands/init.rst
user: login: upils
body: This piece of doc is automatically generated from the CLI and in this case is not specific to imagecraft.
So I guess any CLI rework will happen in craft-application. Unless you meant something else?
created_at: 2025-03-20T10:51:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,20 @@
+.. _overlays:
+
+Overlay step
+============
+
+Images are built in a sequence of five separate steps: pull, overlay,
+build, stage and prime.
+
+The overlay step is configured with overlay parameters.
+To learn more about pull, build, stage and prime see
+:doc:`/reference/part-lifecycle-details`
+
+The overlay step provides the means to refine the content of an image parts
+after parts. ``overlay-script`` will run the provided script in this step.
path: docs/explanation/overlay-step.rst
user: login: medubelko
body: I believe I understand. My comment was more pointed at the grammar. As-is it's not clear. :)

From your description, it sounds like the sentence should read more like this:

> The overlay step in each part provides the means to refine the contents of the image.

What do you think?
created_at: 2025-03-20T22:15:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,52 @@
+
+.. _ref_commands_init:
+
+init
+====
+
+Initialise a project.
+
+If '<project-dir>' is provided, initialise in that directory,
+otherwise initialise in the current working directory.
+
+If '--name <name>' is provided, the project will be named '<name>'.
+Otherwise, the project will be named after the directory it is initialised in.
+
+'--profile <profile>' is used to initialise the project for a specific use case.
+
+Init can work in an existing project directory. If there are any files in the
+directory that would be overwritten, then init command will fail.
path: docs/reference/commands/init.rst
user: login: medubelko
body: That's what I meant. :) It's older content that predates both of us.

The reason I suggested it is because we're bubbling up content that normally doesn't get seen outside of the CLI, so we can double our value if I review it once and improve it in both docs and CLI.


created_at: 2025-03-20T22:18:30Z
author_association: CONTRIBUTOR
path: docs/reference/commands/init.rst
user: login: medubelko
body: Our discussion reminds me of something else. I should have picked up on this earlier.

Pages created by the `gen_cli` script shouldn't be committed. The other apps have placed their autogenerated paths in [.gitignore](https://github.com/canonical/rockcraft/blob/adb3031276a7f2f4039c35cf2388254aaa88861f/.gitignore#L151).
created_at: 2025-03-20T22:26:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -18,29 +18,5 @@ trusted.
 Cryptography
 ------------
 
-``imagecraft`` is a wrapper around several tools and mainly ``ubuntu-image``. The tool
-itself does not use cryptographic technologies. Refer to the `ubuntu-image security
-overview`_ for details on cryptographic technologies used in ``ubuntu-image``.
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-- Secrets (passwords and hashes) can be present in the configuration files provided to
-  ``imagecraft`` to build images. Specifically, in the ``ubuntu-bootstrap`` plugin
-  configuration:
-
-  * In the ``extra-ppas`` customisation section, authentication tokens
-    (``user:password``) can be defined to access private PPAs. These values are used to
-    write the ``apt`` configuration without any treatment.
-  * In the ``manual`` customisation section, user accounts can be defined with plain
-    text or hashed passwords. These values are directly passed to the ``chpassword``
-    utility without any treatment.
-
-- These configuration files for secrets should then be securely stored, and if secrets
-  are used, they should ideally be injected at runtime.
-
-
-.. LINKS
-
-.. _ubuntu-image security overview: https://canonical-subiquity.readthedocs-hosted.com/en/latest/explanation/ubuntu-image-security-overview.html
+``imagecraft`` is a wrapper around several tools. The tool itself does not use
+cryptographic technologies.
path: docs/explanation/security-overview.rst
user: login: medubelko
body: Agreed, let's remove the section for now. I'm in discussion with Sergio about a good template we could use for all libraries that then gets transcluded in apps as-needed.
created_at: 2025-03-20T22:30:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,5 @@
+:ref:`ref_commands_init`
+   Create an initial project filetree.
+
+:ref:`ref_commands_version`
+   Show the application version and exit.
path: docs/reference/commands/other-commands.rst
user: login: medubelko
body: Sure, let's earmark this.
created_at: 2025-03-20T22:30:34Z
author_association: CONTRIBUTOR
path: docs/explanation/overlay-step.rst
user: login: medubelko
body: I see, that's a good point. Let's leave it as-is for now, and we'll rethink Craft Parts' making it an explanation later.
created_at: 2025-03-20T22:52:59Z
author_association: CONTRIBUTOR
path: docs/reference/commands/init.rst
user: login: upils
body: I missed that, thanks. See https://github.com/canonical/imagecraft/pull/109/commits/8168665738ec1b96c955cf5b837e4617b93161b1
created_at: 2025-03-21T08:02:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -5,7 +5,3 @@
 ..
   exclude the overlay step explanation from craft-parts
path: docs/explanation/parts.rst
user: login: tigarmo
body: (minor) this comment is outdated now
created_at: 2025-03-24T11:48:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -27,45 +25,80 @@ The name of the image. This value must:
 - not end with a hyphen, and must not contain two or more consecutive
   hyphens.
 
-``title``
----------
+title
+-----
 
 **Type**: string
 
 **Required**: No
 
 The human-readable title of the image. If omitted, defaults to ``name``.
 
-``summary``
------------
+summary
+-------
 
 **Type**: string
 
 **Required**: Yes
 
 A short summary describing the image.
 
-``description``
----------------
+description
+-----------
 
 **Type**: string
 
 **Required**: Yes
 
 A longer, possibly multi-line description of the image.
 
-``version``
------------
+version
+-------
 
 **Type**: string
 
 **Required**: Yes
 
 The imagecraft configuration version, used to track changes to the configuration file.
 
+base
+----
+
+**Type**: string ``bare``
+
+**Required**: Yes
+
+Base to use as a first layer for the image.
+
+build-base
+----------
+
+**Type**: One of ``ubuntu@20.04 | ubuntu@22.04 | ubuntu@24.04 | devel``
 
-``platforms``
--------------
+**Required**: Yes
+
+The system and version that will be used during the build, but not
+included in the final image itself. It comprises the set of tools and libraries
+that Imagecraft will use when building the image contents.
+
+.. note::
+   ``devel`` is a "special" value that means "the next Ubuntu version, currently
+   in development". This means that the contents of this system changes
+   frequently and should not be relied on for production rocks.
path: docs/reference/imagecraft-yaml-file.rst
user: login: tigarmo
body: ```suggestion
   frequently and should not be relied on for production images.
```
created_at: 2025-03-24T11:50:03Z
author_association: CONTRIBUTOR

PR comments:
user: login: upils
created_at: 2025-03-19T16:31:59Z
body: @medubelko is the integration of the parts properties now closer to what you had in mind? I was unable to hide the Part properties page from the navigation list though, so if you know a way let me know :).
author_association: CONTRIBUTOR
user: login: medubelko
created_at: 2025-03-20T22:55:47Z
body: >  I'll come up with an alternative soon.

I gave this some more thought, and restored the page. Snapcraft has this page too, but is missing its project file reference.

All apps will have their project file refernces served by the upcoming Pydantic model extension, so we'll have a solution soon.
author_association: CONTRIBUTOR