{"id":26243566,"url":"https://github.com/teemtee/testcloud","last_synced_at":"2025-04-23T14:11:27.375Z","repository":{"id":259323402,"uuid":"873444223","full_name":"teemtee/testcloud","owner":"teemtee","description":"A small helper script to download and boot cloud images locally","archived":false,"fork":false,"pushed_at":"2025-04-15T18:11:10.000Z","size":507,"stargazers_count":4,"open_issues_count":2,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-20T04:15:24.698Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teemtee.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}},"created_at":"2024-10-16T07:18:55.000Z","updated_at":"2025-04-15T22:04:02.000Z","dependencies_parsed_at":"2025-03-13T13:45:37.869Z","dependency_job_id":null,"html_url":"https://github.com/teemtee/testcloud","commit_stats":null,"previous_names":["teemtee/testcloud"],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teemtee%2Ftestcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teemtee%2Ftestcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teemtee%2Ftestcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teemtee%2Ftestcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teemtee","download_url":"https://codeload.github.com/teemtee/testcloud/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249845568,"owners_count":21333736,"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-13T10:28:43.145Z","updated_at":"2025-04-23T14:11:27.327Z","avatar_url":"https://github.com/teemtee.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# testcloud\n\n**testcloud** is a small helper script to download and boot cloud/coreos VM images\nlocally. Testcloud supports wide range of distributions, namely Fedora, Fedora CoreOS,\nCentOS, CentOS Stream, Red Hat Enterprise Linux, Debian and Ubuntu.\n\n**testcloud** can run either in system mode or in constrained user session mode,\nwhich is useful for running testcloud and its VMs in unprivileged containers.\n\n## Installation\n\nThe following procedure should only be used to install **testcloud** on\na production system. For developing purposes, you need a different kind\nof installation which is described in the **Testcloud Development**\nsection below.\n\nTo use **testcloud** on a production system:\n\n1. Install the **testcloud**.\n\n       ```\n       $ sudo dnf install testcloud\n       ```\n\n2. Add yourself to the `testcloud group`.\n\n      ```\n      $ sudo usermod -a -G testcloud $USER\n      ```\n\n3. Restart your user session to update the group privileges, or use\n   `su -` to get a login shell for that particular user where the group\n   settings will be updated.\n\n      ```\n      $ su -i $USER\n      ```\n\n4. Now, you are ready to use **testcloud**.\n\n## Using testcloud\n\n### Creating a new instance\n\nTo create a new instance, you will need to provide distribution and version you wish to use or the url of some cloud\nimage in the *qcow2* format. If you do not have an image location of\nyour own, you can use the image from the **Fedora Cloud** download pages\n(\u003chttps://alt.fedoraproject.org/cloud/\u003e).\n\nTo create a new instance with the cloud image, run:\n\n```\n$ testcloud create \u003curl for qcow2 image\u003e or \u003cdistro:version\u003e\n```\n\nSome examples how to create an instance with distribution:version shortcut:\n\n```\n# Latest Fedora Release\n$ testcloud create fedora\n```\n\n```\n# Fedora Rawhide (latest Nightly Compose)\n$ testcloud create fedora:rawhide\n```\n\n```\n# CentOS Stream 8\n$ testcloud create centos-stream:8\n```\n\n```\n# Ubuntu Hirsute (21.04)\n$ testcloud create ubuntu:hirsute\n```\n\n```\n# Debian 11\n$ testcloud create debian:11\n```\n\nSupported distributions with shortcuts are: Fedora, CentOS, CentOS Stream, Ubuntu, Debian, Alma, Rocky, and Oracle.\nFor other distributions, you can provide link to basically any qcow2 image which has the cloud-init package included.\n\nTestcloud supports also Vagrant .box files, in a limited manner and currently only for Fedora and CentOS.\n\n**testcloud** will download the *qcow2* image and save it in the\n`/var/lib/testcloud/backingstores/\u003cqcow2-filename\u003e`. It will use this\nimage a backing store for the newly created instance in\n`/var/tmp/instances/\u003cinstance-name\u003e`. When the image has been already\ndownloaded, **testcloud** will use the previously download image to\ncreate the instance.\n\nTo create a new instance with the coreos image, run:\n\n```\n$ testcloud create fedora-coreos:\u003cstream\u003e or \u003curl for qcow2 image\u003e\n\n```\n\nYou will be able to see the instance using the `list` command.\n\n```\n$ testcloud list\n```\n\nAlternatively, the instances can also be viewed and manipulated using\nthe **virt-manager** tool.\n\n### Creating an instance with specific architecture\n\nInstances can be created with a different architecture than the host architecture. You'll need to have a proper\nqemu binary installed for this to work (eg. qemu-system-aarch64-core for aarch64 on x86_64 on Fedora). Supported\narchitectures in testcloud are: x86_64, aarch64, ppc64le, and s390x. Any combinations of these are supported.\n\nSome examples:\n\n```\n# Fedora aarch64 on x86_64 (or any other)\n$ testcloud create fedora --arch aarch64\n```\n\n```\n# CentOS Stream x86_64 on aarch64 (or any other)\n$ testcloud create centos-stream --arch x86_64\n```\n\n```\n# Fedora Rawhide ppc64le on aarch64 (or any other)\n$ testcloud create fedora:rawhide --arch ppc64le\n```\n\n### Starting, stopping, and removing an instance\n\nInstances can be started and stopped using the `instance` interface of\nthe **testcloud**, too:\n\n1. List all instances to see the correct name of the instance:\n\n       ```\n       $ testcloud list\n       ```\n\n2. Start the instance:\n\n       ```\n       $ testcloud start \u003cinstance-name\u003e\n       ```\n\n3. Stop the instance:\n\n       ```\n       $ testcloud stop \u003cinstance-name\u003e\n       ```\n\n4. Remove the instance:\n\n       ```\n       $ testcloud remove \u003cinstance-name\u003e\n       ```\n\nRemoving the instance only succeeds when the appropriate instance has\nbeen **stopped** before. However, you can use the `-f` option to force\nremoving the instance.\n\n### Other instance operations\n\n1. Reboot the instance:\n\n       ```\n       $ testcloud reboot \u003cinstance-name\u003e\n       ```\n\n2. Remove non-existing libvirt VMs from testcloud:\n\n       ```\n       $ testcloud clean\n       ```\n\n### Logging into the instance\n\nWhen the cloud/coreos instance is created, **testcloud** will return its IP address\nthat you can use to access the running instance via `ssh`. The default *login\nname* is `cloud-user` and the *password* is `passw0rd`. Testcloud will output info how you can connect to any of the Supported Distributions.\n\n```\nssh cloud-user@\u003cinstance-IP\u003e\n```\n\nThe IP address of an instance is also shown when you list the instance\nusing the `testcloud list` command. You can also control the\ninstance using the **virt-manager** , **GNOME Boxes** or any other tool to manage libvirt VMs.\n\n### Available options to create an instance\n\nThere are several options (all optional) that can be used to create a\nnew instance using **testcloud**.\n\n-c, \\--connection QEMU_URI\n\n: You can specify uri to qemu you wish to use. For limited environments, you might wish to use *qemu:///session*. Remote connections other than *qemu:///session* and *qemu:///system* (like qemu+ssh,...) are known to be problematic.\n\n\\--arch ARCH\n\n: To request a speciffic architecture for the guest. The default\n|    is the architecture of the host system.\n\n\\--ram RAM\n\n: To set the amount of RAM that will be available to the virtual\n    machine (in MiB).\n\n\\--vcpus VCPUS\n\n: To set the amount of VCPUS that will be available to the virtual\n    machine.\n\n\\--no-graphic\n\n: This turns off the graphical display of the virtual machine.\n\n\\--vnc\n\n: To open a VNC connection at the `:1` display of the instance.\n\n-n, \\--name NAME\n\n: To specify a custom name for you instance.\n\n\\--timeout TIMEOUT\n\n: A time (in seconds) to wait for boot to complete. Setting to 0\n    (default) will disable this functionality.\n\n\\--disksize DISKSIZE\n\n: To set the disk size of the virtual machine (in GiB)\n\n\\--disk_number\n\n: To provide disk number you want\n\n\\--nic_number\n\n: To provide nic number you want\n\n\\--virtiofs\n: To specify a local directory to mount and mount target like \u003chost path\u003e:\u003cguest path\u003e\n\n\\--iommu\n\n: To provide virtual iommu device\n\nThere are several additional options that can be used to create a\nnew Coreos instance using **testcloud**.\n\n\\--bu_file BU_FILE\n\n: To provide a bu_file you want to use\n\n\\--ign_file IGN_FILE\n\n: To provide an ign_file you want to use\n\n\\--ssh_path\n\n: To provide ssh pubkey path\n\n### Configuration\n\nThe default configuration should work for many people but those defaults\ncan be overridden through the use of a `settings.py` file containing the\nvalues to use when overriding default settings. The example file in\n`conf/settings-example.py` shows the possible configuration values which\ncan be changed.\n\nNote that in order for those new values to be picked up, the filename\nmust be `settings.py` and that file must live in one of the following\nlocations:\n\n* `conf/settings.py` in the git checkout\n* `~/.config/testcloud/settings.py`\n* `/etc/testcloud/settings.py`\n\nFor example, if you wanted to set up an ssh accessible root account that\nuses an ssh key as the authentification method, you could provide the\nfollowing to the `~/.config/testcloud/settings.py`:\n\n```yaml\nUSER_DATA = \"\"\"#cloud-config\nusers:\n    - default\n    - name: root\n      password: %s\n      chpasswd: { expire: False }\n      ssh-authorized-keys:\n      - \u003cmy ssh pub key\u003e\n\"\"\"\n```\n\n## Testcloud Development\n\nTo develop **testcloud**, you need to perform a more complicated process\nto install all its dependencies, download the source code and perform a\nset-up.\n\nTo install **testcloud** for development purposes:\n\n### Prerequisites\n\n1. Install the dependencies for **testcloud**.\n\n       ```\n       $ sudo dnf builddep testcloud\n       ```\n\n2. Start **libvirtd**.\n\n       ```\n       $ sudo systemctl start libvirtd\n       ```\n\n3. Add the `testcloud` group to the system.\n\n       ```\n       $ sudo groupadd testcloud\n       ```\n\n4. Add a user into the `testcloud` group.\n\n       ```\n       $ sudo usermod -a -G testcloud $USER\n       ```\n\n5. Log out of the system and log in again to update the group\n   information on your user or use a login shell on a different\n   terminal.\n\n       ```\n       $ su - $USER\n       ```\n\n### Installation\n\n1. Clone the **testcloud** repository.\n\n       ```\n       $ git clone https://pagure.io/testcloud.git\n       ```\n\n2. Create the application directories.\n\n       ```\n       $ sudo mkdir -p -m 775 /var/lib/testcloud\n       ```\n\n       ```\n       $ sudo mkdir -p -m 775 /var/lib/testcloud/instances\n       ```\n\n       ```\n       $ sudo mkdir -p -m 775 /var/lib/testcloud/backingstores\n       ```\n\n3. Change ownership on these directories to enable their use with\n   **testcloud**.\n\n       ```\n       $ sudo chown qemu:testcloud /var/lib/testcloud\n       ```\n\n       ```\n       $ sudo chown qemu:testcloud /var/lib/testcloud/instances\n       ```\n\n       ```\n       $ sudo chown qemu:testcloud /var/lib/testcloud/backingstores\n       ```\n\n4. Copy the `.rules` file to the **polkit** rules.\n\n       ```\n       $ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/\n       ```\n\n### Running testcloud\n\n1. Navigate to your **testcloud** git repository.\n\n       ```\n       $ cd testcloud\n       ```\n\n2. Execute the `run_testcloud.py` script to run the **testcloud**. You\n   can use any options as with the regular installation, for example:\n\n       ```\n           $ ./run_testcloud.py instance create ...\n       ```\n\n3. Alternatively, you can use **pip** to install **testcloud** onto the\n   system and then use it like it has been installed normally.\n\n       ```\n       $ pip3 install -e . --user\n       ```\n\n### Testing\n\nThere is a small testsuite you can run with:\n\n```\ntox\n```\n\nThis is a good place to contribute if you\\'re looking to help out.\n\n### Releasing\n\nTestcloud is being released to all stable Fedora releases, EPEL branches, and PyPi.\nThe release process can be summed up to these steps:\n\n1. A batch of changes has accumulated\n2. Testsuite sanity is verified (via either tox or pytest)\n3. Documentation is verified up-to-date (README.md, docs/, manpages/)\n4. Compatibility with tmt is verified\n5. `__version__` is updated in `testcloud/__init__.py`, `version` is updated in `docs/source/conf.py`\n6. Version bumps are commited, pushed, a new tag is pushed to this repository\n7. A new version is uploaded on PyPi:\n       ```\n       python3 setup.py sdist bdist_wheel \u0026\u0026 twine upload dist/*\n       ```\n8. Resulting .tar.gz is copied to the dist-git, and build are submitted to all of the stable Fedoras and EPELs\n9. New bodhi builds are queued into the -testing repositories\n\n### Issue Tracking and Roadmap\n\nOur project tracker is on the teemtee\n[GitHub](https://github.com/teemtee/testcloud) instance.\n\n### Credit\n\nThanks to [Oddshocks](https://github.com/oddshocks) for the koji\ndownloader code :)\n\n### License\n\nThis code is licensed GPLv2+. See the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteemtee%2Ftestcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteemtee%2Ftestcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteemtee%2Ftestcloud/lists"}