From f8da4b9f27dfb7765728a797c770b7503c28fdf4 Mon Sep 17 00:00:00 2001 From: Jeremy Cline Date: Mar 17 2017 20:08:25 +0000 Subject: Start on a 'getting started' guide This adds some "getting started" documentation, based off of the wiki articles for getting started[0][1]. It's far from complete, but it's a nice place to start. [0] https://fedoraproject.org/wiki/Infrastructure/GettingStarted [1] https://fedoraproject.org/wiki/Infrastructure_Apprentice Signed-off-by: Jeremy Cline --- diff --git a/docs/dev-guide/getting-started.rst b/docs/dev-guide/getting-started.rst new file mode 100644 index 0000000..89c30bf --- /dev/null +++ b/docs/dev-guide/getting-started.rst @@ -0,0 +1,55 @@ + +.. _dev-getting-started: + +=============== +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. + + +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. + + +.. _git: https://git-scm.com/ +.. _Python: https://www.python.org/ +.. _Ansible: https://www.ansible.com/ +.. _Vagrant: https://vagrantup.com/ +.. _GitHub: https://github.com/ +.. _fedora-infra: https://github.com/fedora-infra +.. _Pagure: https://pagure.io/ +.. _easyfix: https://fedoraproject.org/easyfix/ diff --git a/docs/dev-guide/index.rst b/docs/dev-guide/index.rst index 49a47d2..0ea333b 100644 --- a/docs/dev-guide/index.rst +++ b/docs/dev-guide/index.rst @@ -18,6 +18,7 @@ issue `_ or submit a pull request. :maxdepth: 2 :caption: Contents: + getting-started dev-environment documentation writing-tests diff --git a/docs/index.rst b/docs/index.rst index 67da8a8..7d3952e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,15 +15,68 @@ 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. +.. _getting-started: + +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 overwhelming. This document is intended to +help you get ready to contribute to the Fedora Infrastructure. + + +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). + + +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. + + +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 `freenode`_. 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. + + +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 +:ref:`dev-getting-started` guide. + +If system administration sounds more to your liking, see the system administrator +:ref:`sysadmin-getting-started` guide. + + +Full Table of Contents +====================== + .. toctree:: - :maxdepth: 1 - :caption: Contents: + :maxdepth: 2 + :caption: Full Table of Contents: dev-guide/index sysadmin-guide/index @@ -33,5 +86,18 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` + + +.. _Fedora account: + https://admin.fedoraproject.org/accounts/ +.. _Fedora Project Contributor Agreement: + http://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement +.. _Fedora Infrastructure mailing list: + https://lists.fedoraproject.org/admin/lists/infrastructure.lists.fedoraproject.org/ +.. _Internet Relay Chat: + https://en.wikipedia.org/wiki/Internet_Relay_Chat +.. _beginner's guide to IRC: + https://fedoramagazine.org/beginners-guide-irc/ +.. _freenode: + https://freenode.net/ diff --git a/docs/sysadmin-guide/index.rst b/docs/sysadmin-guide/index.rst index 1ab853c..04e50eb 100644 --- a/docs/sysadmin-guide/index.rst +++ b/docs/sysadmin-guide/index.rst @@ -4,8 +4,71 @@ ========================== System Administrator Guide ========================== + Welcome to the Fedora Infrastructure system administration guide. + +.. _sysadmin-getting-started: + +Getting Started +=============== + +If you haven't already, you should complete the general :ref:`getting-started` +guide. Once you've completed that, you're ready to get involved in the +`Fedora Infrastructure Apprentice`_ group. + + +Fedora Infrastructure Apprentice +-------------------------------- + +The `Fedora Infrastructure Apprentice`_ group in the Fedora Account System is +one with a lot of read-only access to various Fedora infrastructure machines. +This group is used for new folks to look around at the infrastructure setup, +check machines and processes and see where they might like to contribute moving +forward. This also allows apprentices to examine and gather info on problems, +then propose solutions. + +.. note:: + This group will be pruned often of inactive folks who miss the monthly + email checkin on the `infrastructure mailing list`_. There's nothing + personal in this, and you're welcome to re-join later when you have more + time, we just want to make sure the group only has active members. + +Members of the `Fedora Infrastructure Apprentice`_ group have ssh/shell access +to many machines, but no sudo rights or ability to commit to the `Ansible +repository`_ (but they do have read-only access). Apprentice can however commit to +the infra-docs repository. Access is via the bastion.fedoraproject.org machine +and from there to each machine. See the :ref:`ssh-sop` for instructions on how +to set up SSH. You can see a list of hosts that allow apprentice access by +using:: + + $ ansible/scripts/hosts_with_var_set -o fas_client_groups=fi-apprentice' + +From a checkout of the `Ansible repository`_. The Ansible repository is hosted +on batcave01.phx2.fedoraproject.org in ``/git/ansible``. + + +Selecting a Ticket +------------------ + +Start by checking out the `easyfix tickets`_. Tickets marked with this tag are +a good place for apprentices to learn how things are setup, and also contribute +a fix. + +Since apprentices do not have commit access to the `Ansible repository`_, you +should make your change, produce a patch with ``git diff``, and attach it to +the infrastructure ticket you are working on. It will then be reviewed. + + +.. _sops: + +Standard Operating Procedures +============================= + +Below is a table of contents containing all the standard operating procedures +for Fedora Infrastructure applications. For information on how to write a new +standard operating procedure, consult the guide on :ref:`develop-sops`. + .. toctree:: :maxdepth: 2 :caption: Standard Operating Procedures: @@ -138,4 +201,11 @@ Welcome to the Fedora Infrastructure system administration guide. sops/zodbot - sops/index +.. _Fedora Infrastructure Apprentice: + https://admin.fedoraproject.org/accounts/group/view/fi-apprentice +.. _Ansible repository: + https://infrastructure.fedoraproject.org/infra/ansible/ +.. _infrastructure mailing list: + https://lists.fedoraproject.org/admin/lists/infrastructure.lists.fedoraproject.org/ +.. _easyfix tickets: + https://pagure.io/fedora-infrastructure/issues?status=Open&tags=easyfix diff --git a/docs/sysadmin-guide/sops/sshaccess.rst b/docs/sysadmin-guide/sops/sshaccess.rst index 053f2f6..df553b1 100644 --- a/docs/sysadmin-guide/sops/sshaccess.rst +++ b/docs/sysadmin-guide/sops/sshaccess.rst @@ -3,6 +3,8 @@ .. date: 2012-09-24 .. taxonomy: Contributors/Infrastructure +.. _ssh-sop: + ============================= SSH Access Infrastructure SOP =============================