diff --git a/doc/source/admin/centos7_setup.rst b/doc/source/admin/centos7_setup.rst index b0321b7445..e5c3a28e4b 100644 --- a/doc/source/admin/centos7_setup.rst +++ b/doc/source/admin/centos7_setup.rst @@ -8,8 +8,8 @@ We're going to be using CentOS 7 on a cloud server for this installation. Prerequisites ------------- -- Port 9000 must be open and accessible from the internet so that - Github can communicate with the Zuul web service. +- Port 9000 must be open and accessible from the Internet so that + GitHub can communicate with the Zuul web service. Login to your environment ------------------------- @@ -35,6 +35,12 @@ The repositories and the packages installed from those are listed below. * ius-release: python35u, python35u-pip, python35u-devel * bigtop: zookeeper +First, make sure the system packages are up to date, and then install +some packages which will be required later. Most of Zuul's binary +dependencies are handled by the bindep program, but a few additional +dependencies are needed to install bindep, and for other commands +which we will use in these instructions. + .. code-block:: console $ sudo yum update -y @@ -48,6 +54,10 @@ The repositories and the packages installed from those are listed below. Install Zookeeper ----------------- +Nodepool uses Zookeeper to keep track of information about the +resources it manages, and it's also how Zuul makes requests to +Nodepool for nodes. + .. code-block:: console $ sudo bash -c "cat << EOF > /etc/yum.repos.d/bigtop.repo diff --git a/doc/source/admin/fedora27_setup.rst b/doc/source/admin/fedora27_setup.rst index 4408679b97..29fb940bd5 100644 --- a/doc/source/admin/fedora27_setup.rst +++ b/doc/source/admin/fedora27_setup.rst @@ -8,8 +8,8 @@ We're going to be using Fedora 27 on a cloud server for this installation. Prerequisites ------------- -- Port 9000 must be open and accessible from the internet so that - Github can communicate with the Zuul web service. +- Port 9000 must be open and accessible from the Internet so that + GitHub can communicate with the Zuul web service. Login to your environment ------------------------- @@ -25,6 +25,12 @@ To get started, ssh to your machine as the ``fedora`` user:: Environment Setup ----------------- +First, make sure the system packages are up to date, and then install +some packages which will be required later. Most of Zuul's binary +dependencies are handled by the bindep program, but a few additional +dependencies are needed to install bindep, and for other commands +which we will use in these instructions. + :: sudo dnf update -y @@ -35,6 +41,10 @@ Environment Setup Install Zookeeper ----------------- +Nodepool uses Zookeeper to keep track of information about the +resources it manages, and it's also how Zuul makes requests to +Nodepool for nodes. + :: sudo dnf install zookeeper -y diff --git a/doc/source/admin/gerrit_setup.rst b/doc/source/admin/gerrit_setup.rst index 1b141523c4..1928971c57 100644 --- a/doc/source/admin/gerrit_setup.rst +++ b/doc/source/admin/gerrit_setup.rst @@ -6,44 +6,52 @@ Gerrit Installation ------------ -Gerrit can be downloaded from the `Gerrit Code Review `_ web site, and also contains Gerrit documentation with -installation instructions. +Gerrit can be downloaded from the `Gerrit Code Review +`_ web site, and also contains +Gerrit documentation with installation instructions. Create a Zuul User ------------------ -The Gerrit documentation walks you through adding a first user, which will -end up being the admin user. Once the admin user is created, and SSH access -has been setup for that user, you can use that account to create a new 'zuul' -user. This user, which will be used by our Zuul installation, must have SSH -access to gerrit, and have the `stream-events `_ ACL enabled. +The Gerrit documentation walks you through adding a first user, which +will end up being the admin user. Once the admin user is created, and +SSH access has been setup for that user, you can use that account to +create a new ``zuul`` user. This user, which will be used by our Zuul +installation, must have SSH access to gerrit, and have the +`stream-events `_ +ACL enabled. -As the admin user, create the 'zuul' user, and import an SSH key for 'zuul':: +.. TODO: Instructions to create the ssh key used here + +As the admin user, create the ``zuul`` user, and import an SSH key for ``zuul``:: $ cat $PUBKEY | ssh -p 29418 $USER@localhost gerrit create-account \ --group "'Registered Users'" --ssh-key - zuul -`$PUBKEY` is the location of the SSH public key for the 'zuul' user. `$USER` is -the username for the admin user. +``$PUBKEY`` is the location of the SSH public key for the ``zuul`` +user. ``$USER`` is the username for the admin user. -The 'zuul' user should now be able to stream events:: +The ``zuul`` user should now be able to stream events:: $ ssh -p 29418 zuul@localhost gerrit stream-events Configure Gerrit ---------------- -The 'zuul' user (and any other users you may create, for that matter) will -need to be able to leave review votes on any project hosted in your Gerrit. -This is done with the use of Gerrit `Review Labels `_. -You may need to add the proper label permissions to the All-Projects project, -which defines ACLs that all other projects will inherit. +The ``zuul`` user (and any other users you may create, for that +matter) will need to be able to leave review votes on any project +hosted in your Gerrit. This is done with the use of Gerrit +`Review Labels `_. +You may need to add the proper label permissions to the ``All-Projects`` +project, which defines ACLs that all other projects will inherit. -Visting `Projects` -> `List` -> `All-Projects` -> `Access` in your Gerrit lets -you see the current access permissions. In the ``Reference: refs/heads/*`` -section, you will need to add a permisson for the `Label Code-Review` for -the `Registered Users` group (we added the 'zuul' user to this group when we -created it). +.. TODO: Instructions to create a Verified label? + +Visting `Projects` -> `List` -> `All-Projects` -> `Access` in your +Gerrit lets you see the current access permissions. In the +``Reference: refs/heads/*`` section, you will need to add a permisson +for the ``Label Code-Review`` for the ``Registered Users`` group (we +added the ``zuul`` user to this group when we created it). .. note:: The label you configure here must match the label referenced in your Zuul pipeline definitions. We've chosen the Code-Review label diff --git a/doc/source/admin/github_setup.rst b/doc/source/admin/github_setup.rst index c7e94de5f4..8268764d8a 100644 --- a/doc/source/admin/github_setup.rst +++ b/doc/source/admin/github_setup.rst @@ -6,8 +6,11 @@ GitHub Configure GitHub ---------------- -You'll need an organization in Github for this, so create one if you -haven't already. In this example we will use `my-org`. +The recommended way to use Zuul with GitHub is by creating a GitHub +App. This allows you to easily add it to GitHub projects, and reduces +the likelihood of running into GitHub rate limits. You'll need an +organization in Github for this, so create one if you haven't already. +In this example we will use `my-org`. .. NOTE Duplicate content here and in drivers/github.rst. Keep them in sync. @@ -83,8 +86,8 @@ configured. Create two new repositories in your org. One will hold the configuration for this tenant in Zuul, the other should be a normal -project repo to use for testing. We'll call them `zuul-test-config` -and `zuul-test`, respectively. +project repo to use for testing. We'll call them ``zuul-test-config`` +and ``zuul-test``, respectively. Visit the public app page on GitHub, https://github.com/apps/my-org-zuul, and install the app into your org. @@ -105,9 +108,9 @@ Edit ``/etc/zuul/main.yaml`` so that it looks like this:: untrusted-projects: - my-org/zuul-test -The first section, under 'zuul-git' imports the "standard library" of -Zuul jobs, a collection of jobs that can be used by any Zuul -installation. +The first section, under ``zuul-git`` imports the standard library of +Zuul jobs that we configured earlier. This adds a number of jobs that +you can immediately use in your Zuul installation. The second section is your GitHub configuration. diff --git a/doc/source/admin/nodepool_install.rst b/doc/source/admin/nodepool_install.rst index d2e7bb90b8..8866115783 100644 --- a/doc/source/admin/nodepool_install.rst +++ b/doc/source/admin/nodepool_install.rst @@ -6,6 +6,10 @@ Install Nodepool Initial Setup ------------- +First we'll create the nodepool user and set up some directories it +needs. We also need to create an SSH key for Zuul to use when it logs +into the nodes that Nodepool provides. + .. code-block:: console $ sudo adduser --system nodepool --home-dir /var/lib/nodepool --create-home @@ -18,6 +22,10 @@ Initial Setup Installation ------------ +Clone the Nodepool git repository and install it. The ``bindep`` +program is used to determine any additional binary dependencies which +are required. + .. code-block:: console $ git clone https://git.zuul-ci.org/nodepool diff --git a/doc/source/admin/nodepool_openstack.rst b/doc/source/admin/nodepool_openstack.rst index e784cc6c5a..a1e408a6b6 100644 --- a/doc/source/admin/nodepool_openstack.rst +++ b/doc/source/admin/nodepool_openstack.rst @@ -8,7 +8,7 @@ Setup Before starting on this, you need to download your `openrc` configuration from your OpenStack cloud. Put it on your server in the -fedora user's home directory. It should be called +staging user's home directory. It should be called ``-openrc.sh``. Once that is done, create a new keypair that will be installed when instantiating the servers:: @@ -41,7 +41,8 @@ have been filled out. Configuration ------------- -Inputs needed for this file: +You'll need the following information in order to create the Nodepool +configuration file: * cloud name / region name - from clouds.yaml * flavor-name diff --git a/doc/source/admin/nodepool_static.rst b/doc/source/admin/nodepool_static.rst index 8797eb8f3f..2bc19faafa 100644 --- a/doc/source/admin/nodepool_static.rst +++ b/doc/source/admin/nodepool_static.rst @@ -26,7 +26,10 @@ the command:: Nodepool Configuration ---------------------- -Below is a sample nodepool.yaml file that sets up static nodes:: +Below is a sample Nodepool configuration file that sets up static +nodes. Place this file in ``/etc/nodepool/nodepool.yaml``. + +:: zookeeper-servers: - host: localhost diff --git a/doc/source/admin/zuul-from-scratch.rst b/doc/source/admin/zuul-from-scratch.rst index ed414984f4..c9a32fd42f 100644 --- a/doc/source/admin/zuul-from-scratch.rst +++ b/doc/source/admin/zuul-from-scratch.rst @@ -88,6 +88,10 @@ start Nodepool and Zuul services with:: Use Zuul Jobs ------------- +Zuul provides a `standard library`_ of jobs and roles. To take advantage +of these jobs, add the ``zuul-jobs`` repo, which is hosted by the Zuul +project, to your system. + Add to ``/etc/zuul/zuul.conf``:: sudo bash -c "cat >> /etc/zuul/zuul.conf <