From b241b567cc71fe054b13d040004c43e3d4fb22cf Mon Sep 17 00:00:00 2001 From: siddharthvipul Date: Sep 07 2020 16:20:45 +0000 Subject: [PATCH 1/2] add getting started to developer guide Signed-off-by: siddharthvipul --- diff --git a/modules/developer_guide/nav.adoc b/modules/developer_guide/nav.adoc index 622192e..2ec313a 100644 --- a/modules/developer_guide/nav.adoc +++ b/modules/developer_guide/nav.adoc @@ -1 +1,2 @@ * link:https://fedora-infra-docs.readthedocs.io/en/latest/dev-guide/index.html[Developer's Guide] +** xref:getting_started.adoc[Getting Started] diff --git a/modules/developer_guide/pages/getting_started.adoc b/modules/developer_guide/pages/getting_started.adoc new file mode 100644 index 0000000..d61b9b0 --- /dev/null +++ b/modules/developer_guide/pages/getting_started.adoc @@ -0,0 +1,41 @@ += Getting Started + +This document is intended to guide you through your first contribution to a +Fedora Infrastructure project. It assumes you are already familiar with the +link:https://git-scm.com/[git] version control system and the +link:https://www.python.org/[Python] programming language. + + +== Development Environment + +The Fedora Infrastructure team uses link:https://www.ansible.com[Ansible] and +link:https://vagrantup.com/[Vagrant] to set up +development environments for the majority of our projects. It's recommended +that you develop on a Fedora host, but that is not strictly required. + +To install Ansible and Vagrant on Fedora, run: + + $ sudo dnf install vagrant libvirt vagrant-libvirt vagrant-sshfs ansible + +Projects will provide a ``Vagrantfile.example`` file in the root of their +repository if they support using Vagrant. Copy this to ``Vagrantfile``, +adjust it as you see fit, and then run: + + $ vagrant up + $ vagrant reload + $ vagrant ssh + +This will create a new virtual machine, configure it with Ansible, restart +it to ensure you're running the latest updates, and then SSH into the virtual +machine. + +Individual projects will provide detailed instructions for their particular +setup. + + +== Finding a Project + +Fedora Infrastructure applications are either on link:github.com[GitHub] in the +link:https://github.com/fedora-infra[fedora-infra] organization, or on +link:pagure.io[Pagure]. Check out the issues tagged with +link:https://fedoraproject.org/easyfix/[easyfix] for an issue to fix. From 4afae101718ac8bf94644095582e767b25b276ae Mon Sep 17 00:00:00 2001 From: siddharthvipul Date: Sep 08 2020 07:14:03 +0000 Subject: [PATCH 2/2] add development environment page Signed-off-by: siddharthvipul --- diff --git a/modules/developer_guide/nav.adoc b/modules/developer_guide/nav.adoc index 2ec313a..a33534f 100644 --- a/modules/developer_guide/nav.adoc +++ b/modules/developer_guide/nav.adoc @@ -1,2 +1,3 @@ * link:https://fedora-infra-docs.readthedocs.io/en/latest/dev-guide/index.html[Developer's Guide] ** xref:getting_started.adoc[Getting Started] +** xref:developement_env.adoc[Developement Environment] diff --git a/modules/developer_guide/pages/developement_env.adoc b/modules/developer_guide/pages/developement_env.adoc new file mode 100644 index 0000000..8d8e475 --- /dev/null +++ b/modules/developer_guide/pages/developement_env.adoc @@ -0,0 +1,118 @@ +== 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 + +link: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 + +link: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 libvirt to provision +the virtual machines. + +You can install Vagrant on a Fedora host with: + + $ sudo dnf install libvirt vagrant vagrant-libvirt vagrant-sshfs + +You can combine your Ansible playbook with 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 Ansible roles documentation. + +Below is a Vagrantfile that provisions a Fedora 25 virtual machine, updates it, +and runs an Ansible playbook 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. + +``` +# -*- mode: ruby -*- +# vi: set ft=ruby : +# +# Copy this file to ``Vagrantfile`` and customize it as you see fit. + +VAGRANTFILE_API_VERSION = "2" + +Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| + # If you'd prefer to pull your boxes from Hashicorp's repository, you can + # replace the config.vm.box and config.vm.box_url declarations with the line below. + # + # config.vm.box = "fedora/25-cloud-base" + config.vm.box = "f25-cloud-libvirt" + config.vm.box_url = "https://download.fedoraproject.org/pub/fedora/linux/releases"\ + "/25/CloudImages/x86_64/images/Fedora-Cloud-Base-Vagrant-25-1"\ + ".3.x86_64.vagrant-libvirt.box" + + # Forward traffic on the host to the development server on the guest. + # You can change the host port that is forwarded to 5000 on the guest + # if you have other services listening on your host's port 80. + config.vm.network "forwarded_port", guest: 5000, host: 80 + + # This is an optional plugin that, if installed, updates the host's /etc/hosts + # file with the hostname of the guest VM. In Fedora it is packaged as + # ``vagrant-hostmanager`` + if Vagrant.has_plugin?("vagrant-hostmanager") + config.hostmanager.enabled = true + config.hostmanager.manage_host = true + end + + # Vagrant can share the source directory using rsync, NFS, or SSHFS (with the vagrant-sshfs + # plugin). Consult the Vagrant documentation if you do not want to use SSHFS. + config.vm.synced_folder ".", "/vagrant", disabled: true + config.vm.synced_folder ".", "/home/vagrant/devel", type: "sshfs", sshfs_opts_append: "-o nonempty" + + # 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. Uncomment the lines below + # to create and use a dnf cache directory + # + # Dir.mkdir('.dnf-cache') unless File.exists?('.dnf-cache') + # 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 "shell", inline: "sudo dnf -y install python2-dnf libselinux-python" + config.vm.provision "ansible" do |ansible| + ansible.playbook = "devel/ansible/vagrant-playbook.yml" + end + + # Create the "myproject" box + config.vm.define "myproject" do |myproject| + myproject.vm.host_name = "myproject.example.com" + + myproject.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 +``` + +