mirror of
https://github.com/vagrant-libvirt/vagrant-libvirt.git
synced 2025-02-25 18:55:27 -06:00
82202945ce
Switch from having all documentation contained within the README to publishing a jekyll static site of documentation under github pages. This allows for configuration and installation guides to be handled separately to make for the relevant pieces to be in smaller chunks and therefore easier to follow for users. Additionally a table of contents can now be included in a left navigation section that ensures it should be possible to quickly jump from the start to any section and back again. Include support for publishing previews and releases under separate directories to allow for them to exist at the same time as the other latest version of the documents. The navigation section also includes support for accessing any of the other versions published so that it easier to see what configuration options exist for a given release. These will be published automatically when releases are added.
155 lines
5.5 KiB
Markdown
155 lines
5.5 KiB
Markdown
# Vagrant Libvirt Provider
|
|
|
|
|
|
|
|
[](https://gitter.im/vagrant-libvirt/vagrant-libvirt?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|
[](https://github.com/vagrant-libvirt/vagrant-libvirt/actions/workflows/unit-tests.yml)
|
|
[](https://coveralls.io/github/vagrant-libvirt/vagrant-libvirt?branch=master)
|
|
[](https://badge.fury.io/rb/vagrant-libvirt)
|
|
|
|
This is a [Vagrant](http://www.vagrantup.com) plugin that adds a
|
|
[Libvirt](http://libvirt.org) provider to Vagrant, allowing Vagrant to
|
|
control and provision machines via Libvirt toolkit.
|
|
|
|
**Note:** Actual version is still a development one. Feedback is welcome and
|
|
can help a lot :-)
|
|
|
|
Vagrant-libvirt Documentation is published at [https://vagrant-libvirt.github.io/vagrant-libvirt/](https://vagrant-libvirt.github.io/vagrant-libvirt/)
|
|
|
|
## Index
|
|
|
|
<!-- vim-markdown-toc GFM -->
|
|
|
|
* [Installing](#installing)
|
|
* [Running](#running)
|
|
* [Development](#development)
|
|
* [Contributing](#contributing)
|
|
|
|
<!-- vim-markdown-toc -->
|
|
|
|
## Installing
|
|
|
|
Installation typically involves a number of distribution package dependencies to ensure that Libvirt is available.
|
|
Recommend that you follow the [installation guide](https://vagrant-libvirt.github.io/vagrant-libvirt/installation.html).
|
|
|
|
## Running
|
|
|
|
Once installed, use vagrant-libvirt through vagrant.
|
|
|
|
Locate a vagrant box containing the distribution you want to use at
|
|
[Vagrant Cloud](https://app.vagrantup.com/boxes/search?provider=libvirt) and
|
|
initialize.
|
|
|
|
```shell
|
|
vagrant init fedora/32-cloud-base
|
|
```
|
|
|
|
Then run following command:
|
|
|
|
```shell
|
|
vagrant up --provider=libvirt
|
|
```
|
|
|
|
Vagrant needs to know that we want to use Libvirt and not default VirtualBox.
|
|
That's why there is `--provider=libvirt` option specified. Other way to tell
|
|
Vagrant to use Libvirt provider is to setup environment variable
|
|
|
|
```shell
|
|
export VAGRANT_DEFAULT_PROVIDER=libvirt
|
|
```
|
|
|
|
Afterwards to enter the VM simply use:
|
|
```shell
|
|
vagrant ssh
|
|
```
|
|
|
|
If you can't find a box that works as you need, have a look at our documentation
|
|
on [creating boxes](https://vagrant-libvirt.github.io/vagrant-libvirt/boxes.html#creating-boxes)
|
|
on how to take existing ones, customize them and repackage.
|
|
|
|
## Development
|
|
|
|
To work on the `vagrant-libvirt` plugin, clone this repository out, and use
|
|
[Bundler](http://gembundler.com) to get the dependencies:
|
|
|
|
```shell
|
|
git clone https://github.com/vagrant-libvirt/vagrant-libvirt.git
|
|
cd vagrant-libvirt
|
|
bundle install
|
|
```
|
|
|
|
Once you have the dependencies, verify the unit tests pass with `rspec`:
|
|
|
|
```shell
|
|
export VAGRANT_HOME=$(mktemp -d)
|
|
bundle exec rspec --fail-fast --color --format documentation
|
|
```
|
|
|
|
If those pass, you're ready to start developing the plugin.
|
|
|
|
Setting `VAGRANT_HOME` is to avoid issues with conflicting with other
|
|
plugins/gems or data already present under `~/.vagrant.d`.
|
|
|
|
Additionally if you wish to test against a specific version of vagrant you
|
|
can control the version using the following before running the tests:
|
|
|
|
```shell
|
|
export VAGRANT_VERSION=v2.2.14
|
|
bundle update && bundle exec rspec --fail-fast --color --format documentation
|
|
```
|
|
|
|
**Note** rvm is used by the maintainers to help provide an environment to test
|
|
against multiple ruby versions that align with the ones used by vagrant for
|
|
their embedded ruby depending on the release. You can see what version is used
|
|
by looking at the current [unit tests](.github/workflows/unit-tests.yml)
|
|
workflow. By default if you have rvm installed and enabled it this project looks
|
|
to use ruby 2.6.6 and configures a separate gemset, both of which will be switched
|
|
to each time you enter the project directory.
|
|
|
|
You can test the plugin without installing it into your Vagrant environment by
|
|
just creating a `Vagrantfile` in the top level of this directory (it is
|
|
gitignored) that uses it. You can add the following line to your Vagrantfile
|
|
while in development to ensure vagrant checks that the plugin is installed:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vagrant.plugins = "vagrant-libvirt"
|
|
end
|
|
```
|
|
Or add the following to the top of the file to ensure that any required plugins
|
|
are installed globally:
|
|
```ruby
|
|
REQUIRED_PLUGINS = %w(vagrant-libvirt)
|
|
exit unless REQUIRED_PLUGINS.all? do |plugin|
|
|
Vagrant.has_plugin?(plugin) || (
|
|
puts "The #{plugin} plugin is required. Please install it with:"
|
|
puts "$ vagrant plugin install #{plugin}"
|
|
false
|
|
)
|
|
end
|
|
```
|
|
|
|
Now you can use bundler to execute Vagrant:
|
|
|
|
```shell
|
|
$ bundle exec vagrant up --provider=libvirt
|
|
```
|
|
|
|
**IMPORTANT NOTE:** bundle is crucial. You need to use bundled Vagrant.
|
|
|
|
## Contributing
|
|
[](https://github.com/vagrant-libvirt/vagrant-libvirt/issues)
|
|
|
|
1. Fork it
|
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
|
4. Push to the branch (`git push origin my-new-feature`)
|
|
5. Create new Pull Request
|
|
|
|
For future work take a look at [open issues](https://github.com/vagrant-libvirt/vagrant-libvirt/issues?state=open).
|
|
|
|
<!--
|
|
# styling for TOC
|
|
vim: expandtab shiftwidth=2
|
|
-->
|