{"id":26792962,"url":"https://github.com/osbuild/weldr-client","last_synced_at":"2025-06-10T18:37:08.053Z","repository":{"id":37831877,"uuid":"310146450","full_name":"osbuild/weldr-client","owner":"osbuild","description":"Go client library and cmdline tool for WELDR API servers like lorax-composer and osbuild-composer","archived":false,"fork":false,"pushed_at":"2025-04-09T09:14:14.000Z","size":1304,"stargazers_count":6,"open_issues_count":2,"forks_count":16,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-22T15:11:53.661Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osbuild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-11-05T00:06:48.000Z","updated_at":"2025-04-09T09:14:19.000Z","dependencies_parsed_at":"2025-01-13T18:40:37.008Z","dependency_job_id":"d6f3f34d-7ed9-496f-9917-3e1c1f46e162","html_url":"https://github.com/osbuild/weldr-client","commit_stats":{"total_commits":309,"total_committers":11,"mean_commits":28.09090909090909,"dds":"0.15533980582524276","last_synced_commit":"d81ecc3f6c6689811b4f94a934c7d054bc06a7bb"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fweldr-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fweldr-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fweldr-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fweldr-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osbuild","download_url":"https://codeload.github.com/osbuild/weldr-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fweldr-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259124639,"owners_count":22808991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-29T16:18:21.304Z","updated_at":"2025-06-10T18:37:08.033Z","avatar_url":"https://github.com/osbuild.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# composer-cli\n\n`composer-cli` is a command line utility used with\n[osbuild-composer](https://www.osbuild.org) to manage blueprints, build and\nupload images, and manage source repositories.  \nA (newer) alternative to `composer-cli` is [image-builder](https://github.com/osbuild/image-builder-cli),\nwhich works without a local systemd service setup.\n\n## Project\n\n* **Website**: https://www.osbuild.org\n* **Bug Tracker**: https://github.com/osbuild/weldr-client/issues\n* **Discussions**: https://github.com/orgs/osbuild/discussions\n* **Matrix**: #image-builder on [fedoraproject.org](https://matrix.to/#/#image-builder:fedoraproject.org)\n\n* [Edit a Blueprint](#edit-a-blueprint)\n* [Build an image](#build-an-image)\n* [Monitor the build status](#monitor-the-build-status)\n* [Download the image](#download-the-image)\n* [Image Uploads](#image-uploads)\n* [Build an image and upload results](#build-an-image-and-upload-results)\n* [JSON Output](#json-output)\n* [Blueprint Format](#blueprint-format)\n* [Package Sources](#package-sources)\n\n## Edit a Blueprint\n\nStart out by listing the available blueprints using `composer-cli blueprints\nlist`, pick one and save it to the local directory by running `composer-cli\nblueprints save http-server`. If there are no blueprints available you can copy\none of the examples from [here][examples].\n\nEdit the file (it will be saved with a .toml extension) and change the\ndescription, add a package to it. Send it back to the server by\nrunning `composer-cli blueprints push http-server.toml`. You can verify that it was\nsaved by viewing the changelog - `composer-cli blueprints changes http-server`.\n\nSee the [Blueprint Format](#blueprint-format) section for the details on how to\ncreate a blueprint.\n\n\n## Build an image\n\nBuild a `qcow2` disk image from this blueprint by running `composer-cli\ncompose start http-server qcow2`. It will print a UUID that you can use to\nkeep track of the build. You can also cancel the build if needed.\n\nThe available types of images is displayed by `composer-cli compose types`.\nCurrently this consists of: ami, fedora-iot-commit, openstack, qcow2, vhd, vmdk\n\nYou can optionally start an upload of the finished image, see\n[Image Uploads](#image-uploads) for more information.\n\n\n## Monitor the build status\n\nMonitor it using `composer-cli compose info UUID` where UUID is the UUID\nreturned by the start command. This will show the status of the build. You can\nview the build logs once it is in the `RUNNING` state using `composer-cli\ncompose log UUID`\n\nOnce the build is in the `FINISHED` state you can download the image.\n\n\n## Download the image\n\nDownloading the final image is done with `composer-cli compose image UUID` and\nit will save the qcow2 image as `UUID-disk.qcow2` which you can then use to\nboot a VM like this:\n\n```\nqemu-kvm --name test-image -m 1024 -hda ./UUID-disk.qcow2\n```\n\n## Image Uploads\n\n`composer-cli` can upload the images to a number of services, including AWS,\nAzure, and VMWare. The upload can be started when the build is finished by\npassing the service's profile.toml to the `compose start` command. For example:\n\n```\ncomposer-cli compose start http-server server aws.toml\n```\n\n### providers.toml\n\nEach provider requires it's own set of details in order to upload to it, this\nusually involves authentication information. Each provider has its own list of\nrequirements.\n\n#### AWS\n\nA `provider.toml` file for AWS looks like this:\n\n```\n[settings]\nbucket = \"AWS Bucket\"\nregion = \"AWS Region\"\nkey = \"AWS Key\"\naccessKeyID = \"AWS Access Key\"\nsecretAccessKey = \"AWS Secret Key\"\n```\n\nThe access key and secret key can be created by going to the\n`IAM-\u003eUsers-\u003eSecurity Credentials` section and creating a new access key. The\nsecret key will only be shown when it is first created so make sure to record\nit in a secure place. The region should be the region that you want to use the\nAMI in, and the bucket can be an existing bucket, or a new one, following the\nnormal AWS bucket naming rules. It will be created if it doesn't already exist.\n\nWhen uploading the image it is first uploaded to the s3 bucket, and then\nconverted to an AMI.  If the conversion is successful the s3 object will be\ndeleted. If it fails, re-trying after correcting the problem will re-use the\nobject if you have not deleted it in the meantime, speeding up the process.\n\n#### Azure\n\nFor Azure the `provider.toml` looks like:\n\n```\n[settings]\nstorageAccount = \"account\"\nstorageAccessKey = \"key\"\ncontainer = \"container\"\n```\n\n#### VMWare\n\nThe VMWare `provider.toml` uses this template:\n\n```\n[settings]\nhost =  \"Hostname\"\nusername =  \"Username\"\npassword = \"Password\"\ndatacenter = \"Datacenter\"\ncluster = \"Cluster\"\ndatastore = \"Datastore\"\n```\n\n## Build an image and upload results\n\nIf you have a profile named `test-uploads`:\n\n```\ncomposer-cli compose start example-http-server ami \"http image\" aws test-uploads\n```\n\nOr if you have the settings stored in a TOML file:\n\n```\ncomposer-cli compose start example-http-server ami \"http image\" aws-settings.toml\n```\n\nIt will return the UUID of the image build, and the UUID of the upload. Once\nthe build has finished successfully it will start the upload process, which you\ncan monitor with `composer-cli upload info \u003cUPLOAD-UUID\u003e`\n\nYou can also view the upload logs from the Ansible playbook with:\n\n```\ncomposer-cli upload log \u003cUPLOAD-UUID\u003e\n```\n\nThe type of the image must match the type supported by the provider.\n\n\n## JSON Output\n\n`composer-cli` can output the JSON data returned by the `osbuild-composer` API,\neither for debugging or testing purposes. The return format is a JSON 'object'\nthat contains 4 fields: `method` with the HTTP method used to make the request,\n`path` is the API path that was called, `status` is the HTTP return code from\nthe server, and `body` contains the raw JSON returned by the server.\n\nSome commands send 2 requests to the server in order to retrieve all the\nresults at once.  The API supports pagination and defaults to 20 items, so you\nneed to find the total and set the limit to that total in order to get all of\nthem.\n\nFor example, the JSON response from a `composer-cli blueprints list` looks like\nthis:\n\n```\n[{\n    \"method\": \"GET\",\n    \"path\": \"/blueprints/list?limit=0\",\n    \"status\": 200,\n    \"body\": {\n        \"blueprints\": [],\n        \"limit\": 0,\n        \"offset\": 0,\n        \"total\": 3\n    }\n},\n{\n    \"method\": \"GET\",\n    \"path\": \"/blueprints/list?limit=23\",\n    \"status\": 200,\n    \"body\": {\n        \"blueprints\": [\n            \"http-server-bp-1\"\n            \"database-bp-1\"\n            \"dev-bp-1\"\n        ],\n        \"limit\": 3,\n        \"offset\": 0,\n        \"total\": 3\n    }\n}]\n```\n\nNOTE: This output format changed in weldr-client v35.6, it used to be a stream of objectes and is\nnow a proper JSON list of objects, making it easier to parse.\n\n\n## Blueprint Format\n\nBlueprints are simple text files in [TOML](https://github.com/toml-lang/toml) format that describe\nwhich packages, and what versions, to install into the image. They can also define a limited set\nof customizations to make to the final image.\n\nExample blueprints can be found in [here][examples], with a simple one looking like this:\n\n```\nname = \"base\"\ndescription = \"A base system with bash\"\nversion = \"0.0.1\"\n\n[[packages]]\nname = \"bash\"\nversion = \"4.4.*\"\n```\n\nThe `name` field is the name of the blueprint. It can contain spaces, but they will be converted to `-`\nwhen it is written to disk. It should be short and descriptive.\n\n`description` can be a longer description of the blueprint, it is only used for display purposes.\n\n`version` is a [semver compatible](https://semver.org/) version number. If\na new blueprint is uploaded with the same `version` the server will\nautomatically bump the PATCH level of the `version`. If the `version`\ndoesn't match it will be used as is. eg. Uploading a blueprint with `version`\nset to `0.1.0` when the existing blueprint `version` is `0.0.1` will\nresult in the new blueprint being stored as `version 0.1.0`.\n\n### [[packages]] and [[modules]]\n\nThese entries describe the package names and matching version glob to be installed into the image.\n\nThe names must match the names exactly, and the versions can be an exact match\nor a filesystem-like glob of the version using `*` wildcards and `?`\ncharacter matching.\n\nNOTE: Currently there is no difference between `packages` and `modules`. In\nthe future the `modules` list may be used for module support, so it is best to\njust use `[[packages]]` for now.\n\nFor example, to install `tmux-2.9a` and `openssh-server-8.*`, you would add\nthis to your blueprint:\n\n```\n[[packages]]\nname = \"tmux\"\nversion = \"2.9a\"\n\n[[packages]]\nname = \"openssh-server\"\nversion = \"8.*\"\n```\n\n### [[groups]]\n\nThe `groups` entries describe a group of packages to be installed into the image.  Package groups are\ndefined in the repository metadata.  Each group has a descriptive name used primarily for display\nin user interfaces and an ID more commonly used in kickstart files.  Here, the ID is the expected\nway of listing a group.\n\nGroups have three different ways of categorizing their packages:  mandatory, default, and optional.\nFor purposes of blueprints, mandatory and default packages will be installed.  There is no mechanism\nfor selecting optional packages.\n\nFor example, if you want to install the `anaconda-tools` group you would add this to your\nblueprint:\n\n```\n[[groups]]\nname=\"anaconda-tools\"\n```\n\n`groups` is a TOML list, so each group needs to be listed separately, like `packages` but with\nno version number.\n\n\n### Customizations\n\nThe `[customizations]` section can be used to configure the hostname of the final image. eg.:\n\n```\n[customizations]\nhostname = \"baseimage\"\n```\n\nThis is optional and may be left out to use the defaults.\n\n\n#### [customizations.kernel]\n\nThis allows you to append arguments to the bootloader's kernel commandline. This will not have any\neffect on `tar` or `ext4-filesystem` images since they do not include a bootloader.\n\nFor example:\n\n```\n[customizations.kernel]\nappend = \"nosmt=force\"\n```\n\n#### [[customizations.sshkey]]\n\nSet an existing user's ssh key in the final image:\n\n```\n[[customizations.sshkey]]\nuser = \"root\"\nkey = \"PUBLIC SSH KEY\"\n```\n\nThe key will be added to the user's `authorized_keys` file.\n\n---\n**WARNING**\n\n`key` expects the entire content of `~/.ssh/id_rsa.pub`, make sure it is the public key.\n\n---\n\n\n#### [[customizations.user]]\n\nAdd a user to the image, and/or set their ssh key.\nAll fields for this section are optional except for the `name`, here is a complete example:\n\n```\n[[customizations.user]]\nname = \"admin\"\ndescription = \"Administrator account\"\npassword = \"$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L...\"\nkey = \"PUBLIC SSH KEY\"\nhome = \"/srv/widget/\"\nshell = \"/usr/bin/bash\"\ngroups = [\"widget\", \"users\", \"wheel\"]\nuid = 1200\ngid = 1200\n```\n\nIf the password starts with `$6$`, `$5$`, or `$2b$` it will be stored as\nan encrypted password. Otherwise it will be treated as a plain text password.\n\n---\n**WARNING**\n\n`key` expects the entire content of `~/.ssh/id_rsa.pub`, make sure it is the public key.\n\n---\n\n\n#### [[customizations.group]]\n\nAdd a new group to the image. `name` is required and `gid` is optional:\n\n```\n[[customizations.group]]\nname = \"widget\"\ngid = 1130\n```\n\n#### [customizations.timezone]\n\nCustomizing the timezone and the NTP servers to use for the system:\n\n```\n[customizations.timezone]\ntimezone = \"US/Eastern\"\nntpservers = [\"0.north-america.pool.ntp.org\", \"1.north-america.pool.ntp.org\"]\n```\n\nThe values supported by `timezone` can be listed by running `timedatectl list-timezones`.\n\nIf no timezone is setup the system will default to using `UTC`. The ntp servers are also\noptional and will default to using the distribution defaults which are fine for most uses.\n\nIn some image types there are already NTP servers setup, eg. Google cloud image, and they\ncannot be overridden because they are required to boot in the selected environment. But the\ntimezone will be updated to the one selected in the blueprint.\n\n\n#### [customizations.locale]\n\nCustomize the locale settings for the system:\n\n```\n[customizations.locale]\nlanguages = [\"en_US.UTF-8\"]\nkeyboard = \"us\"\n```\n\nThe values supported by `languages` can be listed by running `localectl list-locales` from\nthe command line.\n\nThe values supported by `keyboard` can be listed by running `localectl list-keymaps` from\nthe command line.\n\nMultiple languages can be added. The first one becomes the\nprimary, and the others are added as secondary. One or the other of `languages`\nor `keyboard` must be included (or both) in the section.\n\n\n#### [customizations.firewall]\n\nBy default the firewall blocks all access except for services that enable their ports explicitly,\nlike `sshd`. This command can be used to open other ports or services. Ports are configured using\nthe port:protocol format:\n\n```\n[customizations.firewall]\nports = [\"22:tcp\", \"80:tcp\", \"imap:tcp\", \"53:tcp\", \"53:udp\"]\n```\n\nNumeric ports, or their names from `/etc/services` can be used in the `ports` enabled/disabled lists.\n\nThe blueprint settings extend any existing settings in the image templates, so if `sshd` is\nalready enabled it will extend the list of ports with the ones listed by the blueprint.\n\nIf the distribution uses `firewalld` you can specify services listed by `firewall-cmd --get-services`\nin a `customizations.firewall.services` section:\n\n```\n[customizations.firewall.services]\nenabled = [\"ftp\", \"ntp\", \"dhcp\"]\ndisabled = [\"telnet\"]\n```\n\nRemember that the `firewall.services` are different from the names in `/etc/services`.\n\nBoth are optional, if they are not used leave them out or set them to an empty list `[]`. If you\nonly want the default firewall setup this section can be omitted from the blueprint.\n\nNOTE: Some compose types disable the firewall, this cannot be overridden by the blueprint.\n\n\n#### [customizations.services]\n\nThis section can be used to control which services are enabled at boot time.\nSome image types already have services enabled or disabled in order for the\nimage to work correctly, and cannot be overridden. eg. `ami` requires\n`sshd`, `chronyd`, and `cloud-init`. Without them the image will not\nboot. Blueprint services are added to, not replacing, the list already in the\ncompose type, if any.\n\nThe service names are systemd service units. You may specify any systemd unit\nfile accepted by `systemctl enable` eg. `cockpit.socket`:\n\n```\n[customizations.services]\nenabled = [\"sshd\", \"cockpit.socket\", \"httpd\"]\ndisabled = [\"postfix\", \"telnetd\"]\n```\n\n## Package Sources\n\nBy default osbuild-composer uses the host's configured repositories.\nThese are immutable system\nrepositories and cannot be deleted or changed. If you want to add additional\nrepos use the `composer-cli sources` command to create them.\n\nA new source repository can be added by creating a TOML file with the details\nof the repository and add it to the server with `composer-cli sources add\nnewrepo.toml`:\n\n```\nname = \"custom-source-1\"\nurl = \"https://url/path/to/repository/\"\ntype = \"yum-baseurl\"\nproxy = \"https://proxy-url/\"\ncheck_ssl = true\ncheck_gpg = true\ngpgkey_urls = [\"https://url/path/to/gpg-key\"]\n```\n\nThe `proxy` and `gpgkey_urls` entries are optional. All of the others are required. The supported\ntypes for the urls are:\n\n* `yum-baseurl` is a URL to a yum repository.\n* `yum-mirrorlist` is a URL for a mirrorlist.\n* `yum-metalink` is a URL for a metalink.\n\nIf `check_ssl` is true the https certificates must be valid. If they are\nself-signed you can either set this to false, or add your Certificate Authority\nto the host system.\n\nIf `check_gpg` is true the GPG key must either be installed on the host system, or `gpgkey_urls`\nshould point to it.\n\nYou can edit an existing source (other than system sources), by using `sources\nadd` or `sources change` with the new version of the source. It will overwrite\nthe previous one.\n\nA list of existing sources is available `composer-cli sources list`, and detailed info\non a source can be retrieved with `composer-cli sources info SOURCE-NAME`. Deleting a non-system source is done using `composer-cli sources delete SOURCE-NAME`.\n\nThe configured sources are used for all blueprint depsolve operations, and for composing images.\nWhen adding additional sources you must make sure that the packages in the source do not\nconflict with any other package sources, otherwise depsolving will fail.\n\n[examples]: https://github.com/osbuild/weldr-client/tree/main/examples\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosbuild%2Fweldr-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosbuild%2Fweldr-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosbuild%2Fweldr-client/lists"}