docs: refactor README
With the introduction of man-pages, this now moves the usage information, examples, and pipeline descriptions into the man-page. With this out of the way, the README is restructured with information on how to install the project, what dependencies exist, and directions on where to find further information or contact upstream. Signed-off-by: David Rheinsberg <david.rheinsberg@gmail.com>
This commit is contained in:
David Rheinsberg
Tom Gundersen
parent
71e71a0c77
commit
a1540fd32d
1 changed files with 55 additions and 104 deletions
159
README.md
159
README.md
|
|
@ -1,116 +1,67 @@
|
|||
# osbuild
|
||||
OSBuild
|
||||
=======
|
||||
|
||||
A build system for operating system images, working towards an image build
|
||||
pipeline that's more comprehensible, reproducible, and extendable.
|
||||
Build-Pipelines for Operating System Artifacts
|
||||
|
||||
## Pipelines
|
||||
OSBuild is a pipeline-based build system for operating system artifacts. It
|
||||
defines a universal pipeline description and a build system to execute them,
|
||||
producing artifacts like operating system images, working towards an image
|
||||
build pipeline that is more comprehensible, reproducible, and extendable.
|
||||
|
||||
The build process for an image is described by a pipeline. Each
|
||||
[*stage*](/stages) in a pipeline is a program that, given some configuration,
|
||||
modifies a file system tree. Finally, an assembler takes a filesystem tree, and
|
||||
assembles it into an image. Pipelines are defined as JSON files like this one:
|
||||
See the `osbuild(1)` man-page for details on how to run osbuild, the definition
|
||||
of the pipeline description, and more.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Example Image",
|
||||
"stages": [
|
||||
{
|
||||
"name": "org.osbuild.dnf",
|
||||
"options": {
|
||||
"releasever": "30",
|
||||
"basearch": "x86_64",
|
||||
"repos": [
|
||||
{
|
||||
"metalink": "https://mirrors.fedoraproject.org/metalink?repo=fedora-$releasever&arch=$basearch",
|
||||
"checksum": "sha256:9f596e18f585bee30ac41c11fb11a83ed6b11d5b341c1cb56ca4015d7717cb97",
|
||||
"gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINBFturGcBEACv0xBo91V2n0uEC2vh69ywCiSyvUgN/AQH8EZpCVtM7NyjKgKm\nbbY4G3R0M3ir1xXmvUDvK0493/qOiFrjkplvzXFTGpPTi0ypqGgxc5d0ohRA1M75\nL+0AIlXoOgHQ358/c4uO8X0JAA1NYxCkAW1KSJgFJ3RjukrfqSHWthS1d4o8fhHy\nKJKEnirE5hHqB50dafXrBfgZdaOs3C6ppRIePFe2o4vUEapMTCHFw0woQR8Ah4/R\nn7Z9G9Ln+0Cinmy0nbIDiZJ+pgLAXCOWBfDUzcOjDGKvcpoZharA07c0q1/5ojzO\n4F0Fh4g/BUmtrASwHfcIbjHyCSr1j/3Iz883iy07gJY5Yhiuaqmp0o0f9fgHkG53\n2xCU1owmACqaIBNQMukvXRDtB2GJMuKa/asTZDP6R5re+iXs7+s9ohcRRAKGyAyc\nYKIQKcaA+6M8T7/G+TPHZX6HJWqJJiYB+EC2ERblpvq9TPlLguEWcmvjbVc31nyq\nSDoO3ncFWKFmVsbQPTbP+pKUmlLfJwtb5XqxNR5GEXSwVv4I7IqBmJz1MmRafnBZ\ng0FJUtH668GnldO20XbnSVBr820F5SISMXVwCXDXEvGwwiB8Lt8PvqzXnGIFDAu3\nDlQI5sxSqpPVWSyw08ppKT2Tpmy8adiBotLfaCFl2VTHwOae48X2dMPBvQARAQAB\ntDFGZWRvcmEgKDMwKSA8ZmVkb3JhLTMwLXByaW1hcnlAZmVkb3JhcHJvamVjdC5v\ncmc+iQI4BBMBAgAiBQJbbqxnAhsPBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgAAK\nCRDvPBEfz8ZZudTnD/9170LL3nyTVUCFmBjT9wZ4gYnpwtKVPa/pKnxbbS+Bmmac\ng9TrT9pZbqOHrNJLiZ3Zx1Hp+8uxr3Lo6kbYwImLhkOEDrf4aP17HfQ6VYFbQZI8\nf79OFxWJ7si9+3gfzeh9UYFEqOQfzIjLWFyfnas0OnV/P+RMQ1Zr+vPRqO7AR2va\nN9wg+Xl7157dhXPCGYnGMNSoxCbpRs0JNlzvJMuAea5nTTznRaJZtK/xKsqLn51D\nK07k9MHVFXakOH8QtMCUglbwfTfIpO5YRq5imxlWbqsYWVQy1WGJFyW6hWC0+RcJ\nOx5zGtOfi4/dN+xJ+ibnbyvy/il7Qm+vyFhCYqIPyS5m2UVJUuao3eApE38k78/o\n8aQOTnFQZ+U1Sw+6woFTxjqRQBXlQm2+7Bt3bqGATg4sXXWPbmwdL87Ic+mxn/ml\nSMfQux/5k6iAu1kQhwkO2YJn9eII6HIPkW+2m5N1JsUyJQe4cbtZE5Yh3TRA0dm7\n+zoBRfCXkOW4krchbgww/ptVmzMMP7GINJdROrJnsGl5FVeid9qHzV7aZycWSma7\nCxBYB1J8HCbty5NjtD6XMYRrMLxXugvX6Q4NPPH+2NKjzX4SIDejS6JjgrP3KA3O\npMuo7ZHMfveBngv8yP+ZD/1sS6l+dfExvdaJdOdgFCnp4p3gPbw5+Lv70HrMjA==\n=BfZ/\n-----END PGP PUBLIC KEY BLOCK-----\n"
|
||||
}
|
||||
],
|
||||
"packages": [ "@Core", "grub2-pc", "httpd" ]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "org.osbuild.systemd",
|
||||
"options": {
|
||||
"enabled_services": [ "httpd" ]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "org.osbuild.grub2",
|
||||
"options": {
|
||||
"root_fs_uuid": "76a22bf4-f153-4541-b6c7-0332c0dfaeac"
|
||||
}
|
||||
}
|
||||
],
|
||||
"assembler": {
|
||||
"name": "org.osbuild.qemu",
|
||||
"options": {
|
||||
"format": "qcow2",
|
||||
"filename": "example.qcow2",
|
||||
"ptuuid": "0x7e83a7ba",
|
||||
"root_fs_uuid": "76a22bf4-f153-4541-b6c7-0332c0dfaeac",
|
||||
"size": 3221225472
|
||||
}
|
||||
}
|
||||
}
|
||||
### Project
|
||||
|
||||
* **Website**: <https://www.osbuild.org>
|
||||
* **Bug Tracker**: <https://github.com/osbuild/osbuild/issues>
|
||||
|
||||
### Requirements
|
||||
|
||||
The requirements for this project are:
|
||||
|
||||
* `python >= 3.7`
|
||||
* `systemd-nspawn >= 244`
|
||||
|
||||
Additionally, the built-in stages require:
|
||||
|
||||
* `bash >= 5.0`
|
||||
* `coreutils >= 8.31`
|
||||
* `curl >= 7.68`
|
||||
* `qemu-img >= 4.2.0`
|
||||
* `rpm >= 4.15`
|
||||
* `tar >= 1.32`
|
||||
* `util-linux >= 235`
|
||||
|
||||
At build-time, the following software is required:
|
||||
|
||||
* `python-docutils >= 0.13`
|
||||
* `pkg-config >= 0.29`
|
||||
|
||||
### Build
|
||||
|
||||
The standard python package system is used. Consult upstream documentation for
|
||||
detailed help. In most situations the following commands are sufficient to
|
||||
build and install from source:
|
||||
|
||||
```sh
|
||||
python setup.py build
|
||||
python setup.py install --skip-build --root=/
|
||||
```
|
||||
|
||||
`osbuild` runs each of the stages in turn, isolating them from the host and
|
||||
from each other, with the exception that they all operate on the same
|
||||
filesystem-tree. The assembler is similarly isolated, and given the same
|
||||
tree, in read-only mode and assembles it into an image without altering
|
||||
its contents.
|
||||
The man-pages require `python-docutils` and can be built via:
|
||||
|
||||
The filesystem tree produced by the final stage of a pipeline, is named
|
||||
and optionally saved to be reused as the base for future pipelines.
|
||||
|
||||
Each stage is passed the (appended) `options` object as JSON over stdin.
|
||||
|
||||
The above pipeline has no base and produces a qcow2 image.
|
||||
|
||||
## Running
|
||||
|
||||
```
|
||||
usage: __main__.py [-h] [--build-env ENV] [--store DIRECTORY] [-l DIRECTORY]
|
||||
[--json]
|
||||
PIPELINE
|
||||
|
||||
Build operating system images
|
||||
|
||||
positional arguments:
|
||||
PIPELINE json file containing the pipeline that should be
|
||||
built, or a '-' to read from stdin
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--build-env ENV json file containing a description of the build
|
||||
environment
|
||||
--store DIRECTORY the directory where intermediary os trees are stored
|
||||
--sources SOURCES json file containing a dictionary of source
|
||||
configuration
|
||||
-l DIRECTORY, --libdir DIRECTORY
|
||||
the directory containing stages, assemblers, and the
|
||||
osbuild library
|
||||
--json output results in JSON format
|
||||
```sh
|
||||
rst2man docs/<input-file>.rst <output-file>
|
||||
```
|
||||
|
||||
### Running example
|
||||
### Repository:
|
||||
|
||||
You can build basic qcow2 image of Fedora 30 by running a following command:
|
||||
- **web**: <https://github.com/osbuild/osbuild>
|
||||
- **https**: `https://github.com/osbuild/osbuild.git`
|
||||
- **ssh**: `git@github.com:osbuild/osbuild.git`
|
||||
|
||||
```
|
||||
sudo python3 -m osbuild --libdir . --sources samples/sources.json samples/base-qcow2.json
|
||||
```
|
||||
### License:
|
||||
|
||||
- Root rights are required because osbuild heavily relies on creating
|
||||
systemd containers and bind mounting.
|
||||
|
||||
It shouldn't interfere with host OS but please be **careful**! It's still under
|
||||
development!
|
||||
|
||||
- `--libdir` argument is required because `osbuild` expects itself to be
|
||||
installed in directories under `/usr`. Using this argument you can change
|
||||
the expected path.
|
||||
|
||||
- You don't need to use any kind of virtual environment, modern version of
|
||||
Python 3 is enough. `osbuild` uses only standard library and linux commands.
|
||||
- **Apache-2.0**
|
||||
- See LICENSE file for details.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue