expand on the static mirror setup

howto/static-component.md

@@ -158,21 +158,82 @@ TODO: add a disaster recovery.
 
 ## Installation
 
-Servers are fully configured in [Puppet](puppet), although the `mirroradm`
-user comes from LDAP. See the [design section](#design) section below for
-details on the Puppet classes in use.
+Servers are mostly configured in [Puppet](puppet), with some
+exceptions. See the [design section](#design) section below for
+details on the Puppet classes in use. Typically, a web mirror will use
+`roles::static_mirror_web`, for example.
 
-TODO: that is incomplete. when `web-fsn-02` was setup, it was first
-setup with this in Hiera:
+### Web mirror setup
 
-    staticsync::static_mirror::get_triggered: false
+To setup a web mirror, create a new server with the following entries
+in LDAP:
+
+    allowedGroups: mirroradm
+    allowedGroups: weblogsync
+
+This will ensure the `mirroradm` user  is created on the host.
+
+Then the host needs the following Puppet configuration in Hiera:
+
+```
+classes:
+  - roles::static_mirror_web
+staticsync::static_mirror::get_triggered: false
+```
+
+The `get_triggered` parameter ensure the host will not block static
+site updates while it's doing its first sync.
+
+Then Puppet can be ran on the host, after `apache2` is installed to
+make sure the `apache2` puppet module picks it up:
+
+    apt install apache2
+    puppet agent -t
+
+You might need to reboot to get some firewall rules to load correctly:
+
+    reboot
+
+The server should start a sync after reboot. However, it's likely that
+the SSH keys it uses to sync have not been propagated to the master
+server. If the sync fails, you might receive an email with lots of
+lines like:
+
+    [MSM] STAGE1-START (2021-03-11 19:38:59+00:00 on web-chi-03.torproject.org)
+
+It might be worth running the sync by hand, with:
+
+    screen sudo -u mirroradm static-mirror-run-all
+
+The server may also need to be added to the static component
+configuration in `modules/roles/misc/static-components.yaml`, if it is
+to carry a full mirror, or exclude some components. For example,
+`web-fsn-01` and `web-chi-03` both carry all components, so they need
+to be added to all `limit-mirrors` statements, like this:
+
+```
+components:
+  # [...]
+  dist.torproject.org:
+    master: static-master-fsn.torproject.org
+    source: staticiforme.torproject.org:/srv/dist-master.torproject.org/htdocs
+    limit-mirrors:
+      - archive-01.torproject.org
+      - web-cymru-01.torproject.org
+      - web-fsn-01.torproject.org
+      - web-fsn-02.torproject.org
+      - web-chi-03.torproject.org
+```
+
+Once that is changed, the `static-mirror-run-all` command needs to be
+rerun (although it will also run on the next reboot).
 
 Then, when it was ready and added to Fastly, this was also added:
 
     roles::cdn_torproject_org::fastly_backend: true
 
-web-fsn-02 is also present in
-`modules/roles/misc/static-components.yaml` and `dns/auto-dns.git`.
+TODO: There might be some magic to happen on Fastly's side too?
+`web-fsn-02` is also present in `dns/auto-dns.git`.
 
 ## SLA