From nobody Tue Apr 23 07:47:40 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=patchew-devel-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=patchew-devel-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 152087595205619.428022397768245; Mon, 12 Mar 2018 10:32:32 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id C039E85541; Mon, 12 Mar 2018 17:32:30 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B0962600C9; Mon, 12 Mar 2018 17:32:30 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id A2D6E181B9FB; Mon, 12 Mar 2018 17:32:30 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w2CHWTbN008498 for ; Mon, 12 Mar 2018 13:32:29 -0400 Received: by smtp.corp.redhat.com (Postfix) id 8811A215CDA7; Mon, 12 Mar 2018 17:32:29 +0000 (UTC) Received: from donizetti.redhat.com (ovpn-117-127.ams2.redhat.com [10.36.117.127]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0B5632166BB2 for ; Mon, 12 Mar 2018 17:32:28 +0000 (UTC) From: Paolo Bonzini To: patchew-devel@redhat.com Date: Mon, 12 Mar 2018 18:32:28 +0100 Message-Id: <20180312173228.23045-1-pbonzini@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 X-loop: patchew-devel@redhat.com Subject: [Patchew-devel] [PATCH] commit initial docs X-BeenThere: patchew-devel@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Patchew development and discussion list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: patchew-devel-bounces@redhat.com Errors-To: patchew-devel-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.28]); Mon, 12 Mar 2018 17:32:31 +0000 (UTC) X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" --- docs/patchew.rst | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 162 insertions(+) create mode 100644 docs/patchew.rst diff --git a/docs/patchew.rst b/docs/patchew.rst new file mode 100644 index 0000000..aa51c7f --- /dev/null +++ b/docs/patchew.rst @@ -0,0 +1,162 @@ +Patchew design and flow +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Patchew is designed around three components: + +- a web server, which hosts the Patchew user interface and also exposes + API endpoints for use from the other parts; + +- one or more *importers*, which read email from an IMAP server, send + them to the server, and pushes the messages to a git tree; + +- and a set of *testers*, which poll for git trees that have been + pushed and runs a shell script on the cloned tree. + +The data flow between the components can be represented as follows: + +:: + =20 + IMAP API + Mail ------> Importer -----> Patchew server + =20 + API git + Importer ----> Unapplied series (mbox) ----> Git Server + | + '-----> Patchew server + API + =20 + API git shell API + Tester -----> Untested series (tag) ----> Tree ----> Result -----> Pat= chew server + +While the importer's two tasks could in principle be split to two +separate components, usually a single person can be the point of contact +for both of them. One importer can handle one or more patchew projects, +and similarly for testers. However, while one project will typically get +email from one importer only, it can be served by multiple testers (for +example for different architectures or operating systems). + +Setting up patchew +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Deploying the server +-------------------- + +The server runs in a Docker container. You can deploy it using +``scripts/deploy``, which is a wrapper for Ansible:: + + ./scripts/deploy -s root@patchew.example.com + +All unrecognized options are passed directly to Ansible. For example, +if you do not have public key access configured on the host, add "-k". + +We suggest placing a proxy in front of the server. (why...) + +Creating users +-------------- + +- Create importer user + +- Create tester user + +- Create maintainer user + +Creating a project +------------------ + +(TODO) + +Configuring git plugin +---------------------- + +??? Can you configure the git plugin *after* the importer has been +created ??? + +Deploying the importer +---------------------- + +Like the server, the importer service runs in a Docker container. +You can deploy the importer using the same ``scripts/deploy`` wrapper +for Ansible:: + + ./scripts/deploy -i root@patchew.example.com + +As before, if you do not have public key access configured on the host, +add "-k". If the IMAP server uses TLS, you need to retrieve the +fingerprint for the IMAP server's certificate:: + + openssl s_client -connect imap.gmail.com:993 | \ + openssl x509 -fingerprint | \ + grep Fingerprint + +(you may need to add ``-starttls imap`` to the ``openssl s_client`` +command line). Note that the fingerprint format, as printed by +``openssl x509 -fingerprint``, looks like a sequence of hexadecimal +bytes separated by colons; offlineimap and thus ``scripts/deploy`` +do not use colons. + +You can also specify all the variables directly on the command line +using the ``-e`` option:: + + ./scripts/deploy -i root@patchew.example.com -e " + instance_name=3Dpatchew-importer-example + patchew_server=3Dhttp://patchew.example.com/ + importer_user=3Dimporter + importer_pass=3Dgotsomepatches + imap_server=3Dimap.example.com + imap_user=3Dusername@example.com + imap_pass=3Dhunter2 + imap_cert_fingerprint=3D00112233445566778899aabbccddeeff + imap_folders=3DINBOX + imap_delete_after_import=3Dn" + +Now you can check on the remote machine that the importer is running:: + + systemctl status patchew-importer-example.service + +The importer starts importing messages from the IMAP server to local +storage and from there to git repo. You can watch it with:: + + journalctl -f -u patchew-importer-example + +Deploying the tester +-------------------- + +Unlike the importer and server, the tester does not run in a container; +it is simply a cron job on one or more hosts. Like the importer and +server, however, testers are deployed via ``scripts/deploy`` and +Ansible:: + + ./scripts/deploy -t root@patchew-tester1.example.com -e " + instance_name=3Dpatchew-tester1 + patchew_server=3Dhttp://patchew.example.com/ + tester_user=3Dtester + tester_pass=3Dwantsomepatches + tester_project=3Dfrobnicator" + +The cron job runs as a user named "patchew". + +Continuous integration +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Testing +------- + +"More information about xxx..." -> Login -> ... + +Requirements +~~~~~~~~~~~~ + +(TODO) + +Email notifications +------------------- + +Events +~~~~~~ + +(TODO) + +Templates +~~~~~~~~~ + +(TODO) --=20 2.14.3 _______________________________________________ Patchew-devel mailing list Patchew-devel@redhat.com https://www.redhat.com/mailman/listinfo/patchew-devel