Skip to content

Commit bdfa9ba

Browse files
yockgenyockgen
authored
Merge branch 'main' into dev_feiyu
2 parents 8d4ebe1 + 72c7c0b commit bdfa9ba

File tree

2 files changed

+197
-5
lines changed

2 files changed

+197
-5
lines changed

‎Earthfile‎

Lines changed: 81 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,4 +139,84 @@ test-debug:
139139

140140
test-quick:
141141
FROM +golang-base
142-
RUN go test ./...
142+
RUN go test ./...
143+
144+
deb:
145+
FROM debian:bookworm-slim
146+
ARG VERSION=1.0.0
147+
ARG ARCH=amd64
148+
149+
WORKDIR /pkg
150+
151+
# Create directory structure following FHS (Filesystem Hierarchy Standard)
152+
RUN mkdir -p usr/local/bin \
153+
etc/os-image-composer/config \
154+
usr/share/os-image-composer/examples \
155+
usr/share/doc/os-image-composer \
156+
var/cache/os-image-composer \
157+
DEBIAN
158+
159+
# Copy the built binary from the build target
160+
COPY +build/os-image-composer usr/local/bin/os-image-composer
161+
162+
# Make the binary executable
163+
RUN chmod +x usr/local/bin/os-image-composer
164+
165+
# Create default global configuration with system paths (user-editable)
166+
# Note: Must be named config.yml to match the default search paths in the code
167+
RUN echo "# OS Image Composer - Global Configuration" > etc/os-image-composer/config.yml && \
168+
echo "# This file contains tool-level settings that apply across all image builds." >> etc/os-image-composer/config.yml && \
169+
echo "# Image-specific parameters should be defined in the image specification." >> etc/os-image-composer/config.yml && \
170+
echo "" >> etc/os-image-composer/config.yml && \
171+
echo "# Core tool settings" >> etc/os-image-composer/config.yml && \
172+
echo "workers: 8" >> etc/os-image-composer/config.yml && \
173+
echo "# Number of concurrent download workers (1-100, default: 8)" >> etc/os-image-composer/config.yml && \
174+
echo "" >> etc/os-image-composer/config.yml && \
175+
echo "config_dir: \"/etc/os-image-composer/config\"" >> etc/os-image-composer/config.yml && \
176+
echo "# Directory containing configuration files for different target OSs" >> etc/os-image-composer/config.yml && \
177+
echo "" >> etc/os-image-composer/config.yml && \
178+
echo "cache_dir: \"/var/cache/os-image-composer\"" >> etc/os-image-composer/config.yml && \
179+
echo "# Package cache directory where downloaded RPMs/DEBs are stored" >> etc/os-image-composer/config.yml && \
180+
echo "" >> etc/os-image-composer/config.yml && \
181+
echo "work_dir: \"/tmp/os-image-composer\"" >> etc/os-image-composer/config.yml && \
182+
echo "# Working directory for build operations and image assembly" >> etc/os-image-composer/config.yml && \
183+
echo "" >> etc/os-image-composer/config.yml && \
184+
echo "temp_dir: \"/tmp\"" >> etc/os-image-composer/config.yml && \
185+
echo "# Temporary directory for short-lived files" >> etc/os-image-composer/config.yml && \
186+
echo "" >> etc/os-image-composer/config.yml && \
187+
echo "# Logging configuration" >> etc/os-image-composer/config.yml && \
188+
echo "logging:" >> etc/os-image-composer/config.yml && \
189+
echo " level: \"info\"" >> etc/os-image-composer/config.yml && \
190+
echo " # Log verbosity level: debug, info, warn, error" >> etc/os-image-composer/config.yml
191+
192+
# Copy OS variant configuration files (user-editable)
193+
COPY config etc/os-image-composer/config
194+
195+
# Copy image templates as examples (read-only, for reference)
196+
COPY image-templates usr/share/os-image-composer/examples
197+
198+
# Copy documentation
199+
COPY README.md usr/share/doc/os-image-composer/
200+
COPY LICENSE usr/share/doc/os-image-composer/
201+
COPY docs/architecture/os-image-composer-cli-specification.md usr/share/doc/os-image-composer/
202+
203+
# Create the DEBIAN control file with proper metadata
204+
RUN echo "Package: os-image-composer" > DEBIAN/control && \
205+
echo "Version: ${VERSION}" >> DEBIAN/control && \
206+
echo "Section: utils" >> DEBIAN/control && \
207+
echo "Priority: optional" >> DEBIAN/control && \
208+
echo "Architecture: ${ARCH}" >> DEBIAN/control && \
209+
echo "Maintainer: Intel Edge Software Team <edge.platform@intel.com>" >> DEBIAN/control && \
210+
echo "Depends: bash, coreutils, unzip, dosfstools, xorriso, grub-common" >> DEBIAN/control && \
211+
echo "Recommends: mmdebstrap, debootstrap" >> DEBIAN/control && \
212+
echo "License: MIT" >> DEBIAN/control && \
213+
echo "Description: OS Image Composer (OIC)" >> DEBIAN/control && \
214+
echo " OIC enables users to compose custom bootable OS images based on a" >> DEBIAN/control && \
215+
echo " user-provided template that specifies package lists, configurations," >> DEBIAN/control && \
216+
echo " and output formats for supported distributions." >> DEBIAN/control
217+
218+
# Build the debian package
219+
RUN dpkg-deb --build . os-image-composer_${VERSION}_${ARCH}.deb
220+
221+
# Save the debian package artifact to dist/ directory
222+
SAVE ARTIFACT os-image-composer_${VERSION}_${ARCH}.deb AS LOCAL dist/os-image-composer_${VERSION}_${ARCH}.deb

‎README.md‎

Lines changed: 116 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,22 +36,132 @@ earthly +build
3636
earthly +build --version=1.0.0
3737
```
3838

39+
### Install via Debian Package (Ubuntu/Debian)
40+
41+
For Ubuntu and Debian systems, you can build and install OS Image Composer as a Debian package. This method provides a cleaner installation with proper package management.
42+
43+
#### Build the Debian Package
44+
45+
Use the Earthly `+deb` target to create a `.deb` package:
46+
47+
```bash
48+
# Build with default parameters (version 1.0.0, amd64)
49+
earthly +deb
50+
51+
# Build with custom version and architecture
52+
earthly +deb --VERSION=1.2.0 --ARCH=amd64
53+
54+
# Build for ARM64
55+
earthly +deb --VERSION=1.0.0 --ARCH=arm64
56+
```
57+
58+
The package will be created in the `dist/` directory as `os-image-composer_<VERSION>_<ARCH>.deb`.
59+
60+
#### Install the Package
61+
62+
```bash
63+
# Install using apt (recommended - automatically resolves and installs dependencies)
64+
sudo apt install <PATH TO FILE>/os-image-composer_1.0.0_amd64.deb
65+
66+
# Or using dpkg (requires manual dependency installation)
67+
# First install required dependencies:
68+
sudo apt-get update
69+
sudo apt-get install -y bash coreutils unzip dosfstools xorriso grub-common
70+
# Then install the package:
71+
sudo dpkg -i dist/os-image-composer_1.0.0_amd64.deb
72+
# Optionally install bootstrap tools:
73+
sudo apt-get install -y mmdebstrap || sudo apt-get install -y debootstrap
74+
```
75+
76+
**Note:** Using `apt install` is strongly recommended as it automatically handles all dependencies. If you use `dpkg -i` and encounter dependency errors, run `sudo apt-get install -f` to fix them.
77+
78+
#### Verify Installation
79+
80+
```bash
81+
# Check if package is installed
82+
dpkg -l | grep os-image-composer
83+
84+
# View installed files
85+
dpkg -L os-image-composer
86+
87+
# Verify the binary works
88+
os-image-composer version
89+
```
90+
91+
#### Package Contents
92+
93+
The Debian package installs the following files:
94+
95+
* **Binary:** `/usr/local/bin/os-image-composer` - Main executable
96+
* **Configuration:** `/etc/os-image-composer/` - Default configuration and OS variant configs
97+
- `/etc/os-image-composer/config.yml` - Global configuration with system paths
98+
- `/etc/os-image-composer/config/` - OS variant configuration files
99+
* **Examples:** `/usr/share/os-image-composer/examples/` - Sample image templates
100+
* **Documentation:** `/usr/share/doc/os-image-composer/` - README, LICENSE, and CLI specification
101+
* **Cache Directory:** `/var/cache/os-image-composer/` - Package cache storage
102+
103+
After installation via the Debian package, you can use `os-image-composer` directly from any directory. The configuration is pre-set to use system paths, and you can reference the example templates from `/usr/share/os-image-composer/examples/`.
104+
105+
#### Package Dependencies
106+
107+
The Debian package automatically installs the following runtime dependencies:
108+
109+
**Required Dependencies:**
110+
* `bash` - Shell for script execution
111+
* `coreutils` - Core GNU utilities
112+
* `unzip` - Archive extraction utility
113+
* `dosfstools` - FAT filesystem utilities
114+
* `xorriso` - ISO image creation tool
115+
* `grub-common` - Bootloader utilities
116+
117+
**Recommended Dependencies (installed if available):**
118+
* `mmdebstrap` - Debian bootstrap tool (preferred, version 1.4.3+ required)
119+
* `debootstrap` - Alternative Debian bootstrap tool
120+
121+
**Important:** `mmdebstrap` version 0.8.x (included in Ubuntu 22.04) has known issues. For Ubuntu 22.04 users, you must install `mmdebstrap` version 1.4.3+ manually as described in the [prerequisite documentation](./docs/tutorial/prerequisite.md#mmdebstrap).
122+
123+
#### Uninstall the Package
124+
125+
```bash
126+
# Remove package (keeps configuration files)
127+
sudo dpkg -r os-image-composer
128+
129+
# Remove package and configuration files
130+
sudo dpkg --purge os-image-composer
131+
```
132+
39133
### Install the Prerequisites for Composing an Image
40134

41-
Before you compose an operating system image with the OS Image Composer tool, follow the [instructions to install two prerequisites](./docs/tutorial/prerequisite.md):
135+
Before you compose an operating system image with the OS Image Composer tool, you need to install additional prerequisites:
42136

43-
* `ukify`, which combines components -- typically a kernel, an initrd, and a UEFI boot stub -- to create a signed Unified Kernel Image (UKI), which is a PE binary that firmware executes to start an embedded Linux kernel.
137+
**Required Tools:**
44138

45-
* `mmdebstrap`, which downloads, unpacks, and installs Debian packages to initialize a chroot.
139+
* **`ukify`** - Combines kernel, initrd, and UEFI boot stub to create signed Unified Kernel Images (UKI)
140+
* **Ubuntu 23.04+**: Available via `sudo apt install systemd-ukify`
141+
* **Ubuntu 22.04 and earlier**: Must be installed manually from systemd source
142+
* See [detailed ukify installation instructions](./docs/tutorial/prerequisite.md#ukify)
143+
144+
* **`mmdebstrap`** - Downloads and installs Debian packages to initialize a chroot
145+
* **Ubuntu 23.04+**: Automatically installed with the Debian package (version 1.4.3+)
146+
* **Ubuntu 22.04**: The version in Ubuntu 22.04 repositories (0.8.x) has known bugs and will not work
147+
* **Required:** Manually install version 1.4.3+ following [mmdebstrap installation instructions](./docs/tutorial/prerequisite.md#mmdebstrap)
148+
* **Alternative**: Can use `debootstrap` for Debian-based images
149+
150+
**Note:** If you installed os-image-composer via the Debian package, `mmdebstrap` may already be installed. You still need to install `ukify` separately following the instructions above.
46151

47152
### Compose or Validate an Image
48153

49-
Now you're ready to compose an image from a built-in template or validate a template.
154+
Now you're ready to compose an image from a built-in template or validate a template.
50155

51156
```bash
52157
# Build an image from template
53158
sudo -E ./os-image-composer build image-templates/azl3-x86_64-edge-raw.yml
54159

160+
# If installed via Debian package, use system paths:
161+
sudo os-image-composer build /usr/share/os-image-composer/examples/azl3-x86_64-edge-raw.yml
162+
163+
> Note: The default configuration at `/etc/os-image-composer/config.yml` is discovered automatically; no extra flags are required.
164+
55165
# Validate a template:
56166
./os-image-composer validate image-templates/azl3-x86_64-edge-raw.yml
57167
```
@@ -82,6 +192,8 @@ The tool searches for configuration files in the following order:
82192
5. `~/.config/os-image-composer/config.yaml` (XDG config directory)
83193
6. `/etc/os-image-composer/config.yaml` (system-wide)
84194

195+
**Note:** When installed via the Debian package, the default configuration is located at `/etc/os-image-composer/config.yml` and is pre-configured with system paths.
196+
85197

86198
### Configuration Parameters
87199

0 commit comments

Comments
 (0)