Building operating-system images
OpenFactory turns a normalized recipe into an image artifact and, when requested and available, boots that artifact for verification. The exact builders and stages vary by base-image family and deployment.
What a recipe controls
| Area | Canonical location | Review question |
|---|---|---|
| Base and hardware intent | base_image, hardware | Is this the correct distribution, release, architecture, and minimum profile? |
| Features and packages | os.features, os.packages | Are requested capabilities present and supported on this base? |
| Services and accounts | os.services, os.users | Are configuration and least-privilege access explicit? |
| Desktop and branding | os.desktop_settings, os.branding | Does the selected desktop own these settings and assets? |
| Installer and persistence | os.installer, os.persistence | Are install-to-disk and persistence requirements actually tested? |
| Custom automation | os.startup_scripts, attachments, source packages | Are inputs pinned, bounded, and safe to run as the declared user? |
| Verification | scenarios | Do tests observe every material outcome rather than just boot? |
See Recipe Schema for the full shape.
Build lifecycle
The public status stream can include planning, configuration, source-package work, image generation, finalization, and testing. These are not guaranteed to appear as identical named stages for every target. Follow the build ID returned by the start request and treat the backend’s current status as authoritative.
Keep these outcomes separate:
validatedmeans the recognized recipe shape was accepted;- a terminal successful build means an artifact was finalized;
- test success means the selected assertions passed against their environment; and
- certification or publication, where enabled, is a later policy decision.
Quiet progress is not a reason to create a duplicate build. Reconnect to the build console or status endpoint using the same build ID. If the build becomes terminally failed, preserve the stage, error, and logs before retrying.
Recommended workflow
- Write observable acceptance criteria.
- Generate or edit the recipe.
- Validate it and compare the normalized result with the full conversation.
- Inspect inferred features, external sources, installer settings, and scenarios.
- Start one build and follow its durable ID.
- Review artifact digest, package inventory, warnings, and test evidence.
- Boot or install in a disposable environment appropriate to the request.
- Promote or publish only through the applicable approval gate.
Topic guides
| Topic | Use it for |
|---|---|
| Base Images | Selecting a supported build family |
| Features | Understanding registered capability modules |
| Services | Declaring service configuration |
| Custom Software | Reviewing repository-backed package inputs |
| Users | Creating image-local accounts safely |
| Desktop | Choosing and verifying desktop settings |
| Startup Scripts | Authoring bounded first-boot units |
Start with the smallest useful image. Add features only after the prior artifact’s behavior and evidence are understood.