infra-docs-fpo/modules/developer_guide/pages/dev-environment.adoc
Michal Konečný 6bd7ef5065 Update the developer guide
This commit is fixing all non-functional links and updates the content to more up to date state.

It also removes fedmsg from the guide.

Signed-off-by: Michal Konečný <mkonecny@redhat.com>
2022-04-14 17:29:46 +02:00

111 lines
4.4 KiB
Text

== Development Environment
In order to make contributing easy, all projects should have an
automated way to create a development environment. This might be as
simple as a Python virtual environment, or it could be a virtual machine
or container. This document provides guidelines for setting up
development environments.
=== Ansible
https://www.ansible.com/[Ansible] is used throughout Fedora Infrastructure to
automate tasks. If the project requires anything more than a Python
virtual environment to be set up, you should use Ansible to automate the
setup.
=== Vagrant
https://vagrantup.com/[Vagrant] is a tool to provision virtual machines. It
allows you to define a base image (called a "box"), virtual machine
resources, network configuration, directories to share between the host
and guest machine, and much more. It can be configured to use
https://libvirt.org/[libvirt] to provision the virtual machines.
You can install https://vagrantup.com/[Vagrant] on a Fedora host with:
....
$ sudo dnf install libvirt vagrant vagrant-libvirt vagrant-sshfs
....
You can combine your https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks[Ansible playbook]
with https://vagrantup.com/[Vagrant]
very easily. Simply point Vagrant to your Ansible playbook and it will
run it. Users who would prefer to provision their virtual machines in
some other way are free to do so and only need to run the Ansible
playbook on their host.
[NOTE]
====
How a project lays out its development-related content is up to the
individual project, but a good approach is to create a `devel`
directory. Within that directory you can create an `ansible` directory
and use the layout suggested in the
https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html[Ansible roles]
documentation.
====
Below is a Vagrantfile that provisions a Fedora 34 virtual machine, updates it,
mounts the current folder as `/home/vagrant/devel`, and runs an Ansible playbook
from `devel/ansible` on it. You can place it in the
root of your repository as `Vagrantfile.example` and instruct users to
copy it to `Vagrantfile` and customize as they wish.
[source,ruby]
----
# -*- mode: ruby -*-
# vi: set ft=ruby :
VAGRANTFILE_API_VERSION = "2"
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
config.vm.box = "fedora/34-cloud-base"
# Forward traffic on the host to the development server on the guest
# RabbitMQ
config.vm.network "forwarded_port", guest: 15672, host: 15672
# Vagrant can share the source directory using rsync, NFS, or SSHFS (with the vagrant-sshfs
# plugin). By default it rsyncs the current working directory to /vagrant.
#
# If you would prefer to use NFS to share the directory uncomment this and configure NFS
# config.vm.synced_folder ".", "/vagrant", type: "nfs", nfs_version: 4, nfs_udp: false
config.vm.synced_folder ".", "/home/vagrant/devel", type: "sshfs"
# To cache update packages (which is helpful if frequently doing `vagrant destroy && vagrant up`)
# you can create a local directory and share it to the guest's DNF cache. The directory needs to
# exist, so create it before you uncomment the line below.
#
# config.vm.synced_folder ".dnf-cache", "/var/cache/dnf", type: "sshfs", sshfs_opts_append: "-o nonempty"
# Comment this line if you would like to disable the automatic update during provisioning
config.vm.provision "shell", inline: "sudo dnf upgrade -y"
# bootstrap and run with ansible
config.vm.provision "ansible" do |ansible|
ansible.playbook = "devel/ansible/vagrant-playbook.yml"
ansible.raw_arguments = ["-e", "ansible_python_interpreter=/usr/bin/python3"]
end
# Create the "hotness" box
config.vm.define "hotness" do |hotness|
hotness.vm.host_name = "hotness-dev.example.com"
hotness.vm.provider :libvirt do |domain|
# Season to taste
domain.cpus = 4
domain.graphics_type = "spice"
domain.memory = 2048
domain.video_type = "qxl"
# Uncomment the following line if you would like to enable libvirt's unsafe cache
# mode. It is called unsafe for a reason, as it causes the virtual host to ignore all
# fsync() calls from the guest. Only do this if you are comfortable with the possibility of
# your development guest becoming corrupted (in which case you should only need to do a
# vagrant destroy and vagrant up to get a new one).
#
# domain.volume_cache = "unsafe"
end
end
end
----