Fedora Infrastructure Best Practices Documentation Release 1.0.0
Total Page:16
File Type:pdf, Size:1020Kb
Fedora Infrastructure Best Practices Documentation Release 1.0.0 The Fedora Infrastructure Team Sep 09, 2021 Full Table of Contents: 1 Getting Started 3 1.1 Create a Fedora Account.........................................3 1.2 Subscribe to the Mailing List......................................3 1.3 Join IRC.................................................3 1.4 Next Steps................................................4 2 Full Table of Contents 5 2.1 Developer Guide.............................................5 2.2 System Administrator Guide....................................... 28 2.3 (Old) System Administrator Guides................................... 317 3 Indices and tables 335 i ii Fedora Infrastructure Best Practices Documentation, Release 1.0.0 This contains a development and system administration guide for the Fedora Infrastructure team. The development guide covers how to get started with application development as well as application best practices. You will also find several sample projects that serve as demonstrations of these best practices and as an excellent starting point for new projects. The system administration guide covers how to get involved in the system administration side of Fedora Infrastructure as well as the standard operating procedures (SOPs) we use. The source repository for this documentation is maintained here: https://pagure.io/infra-docs Full Table of Contents: 1 Fedora Infrastructure Best Practices Documentation, Release 1.0.0 2 Full Table of Contents: CHAPTER 1 Getting Started Fedora Infrastructure is full of projects that need help. In fact, there is so much work to do, it can be a little over- whelming. This document is intended to help you get ready to contribute to the Fedora Infrastructure. 1.1 Create a Fedora Account The first thing you should do is create a Fedora account. Your Fedora account will be used for nearly everything you do as a member of the Fedora community. Once you’ve created your Fedora account, you need to read and sign the Fedora Project Contributor Agreement (FPCA). 1.2 Subscribe to the Mailing List Next, you should join the Fedora Infrastructure mailing list. You will need to log into your new Fedora account to subscribe. The mailing list is the best way to have a discussion with the entire Fedora Infrastructure community. 1.3 Join IRC Join us on Internet Relay Chat (IRC) to chat in real time. For a more thorough introduction to IRC, check out the Fedora Magazine’s beginner’s guide to IRC. There are many Fedora IRC channels on libera. To start with, you should check out the #fedora-admin and #fedora-apps channels. These channels are for Fedora Infrastructure system administration and application development, respectively. 3 Fedora Infrastructure Best Practices Documentation, Release 1.0.0 1.4 Next Steps Congratulations, you are now ready to get involved in a project! If application development is what you’re interested in, check out our developer Getting Started guide. If system administration sounds more to your liking, see the system administrator Getting Started guide. 4 Chapter 1. Getting Started CHAPTER 2 Full Table of Contents 2.1 Developer Guide This is a complete guide to contributing to Fedora Infrastructure applications. It targets both new and experienced contributors, and is maintained by those contributors. If the documentation is in need of improvement, please file an issue or submit a pull request. 2.1.1 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 git version control system and the Python programming language. Development Environment The Fedora Infrastructure team uses Ansible and 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. 5 Fedora Infrastructure Best Practices Documentation, Release 1.0.0 Finding a Project Fedora Infrastructure applications are either on GitHub in the fedora-infra organization, or on Pagure. Check out the issues tagged with easyfix for an issue to fix. 2.1.2 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 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 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"\ (continues on next page) 6 Chapter 2. Full Table of Contents Fedora Infrastructure Best Practices Documentation, Release 1.0.0 (continued from previous page) "/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 (continues on next page) 2.1. Developer Guide 7 Fedora Infrastructure Best Practices Documentation, Release 1.0.0 (continued from previous page) # 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 2.1.3 Documentation Since Fedora contributors live around the world and don’t often have the opportunity to meet in person, it’s important to maintain up-to-date high quality documentation for all our projects. Our preferred documentation tool is Sphinx. In fact, this documentation is written using Sphinx! A project’s documentation should at a minimum contain: • An introduction to the project • A user guide • A contributor guide • API documentation.