service/static-shim.md

@@ -8,24 +8,30 @@ hosted in the static mirror infrastructure.
 <!-- simple, brainless step-by-step instructions requiring little or -->
 <!-- no technical background -->
 
-TODO
+TODO: "how do users add/remove sites"
 
 # How-to
 
 <!-- more in-depth procedure that may require interpretation -->
 
+TODO: review ticket for possible howtos
+
 ## Pager playbook
 
 <!-- information about common errors from the monitoring system and -->
 <!-- how to deal with them. this should be easy to follow: think of -->
 <!-- your future self, in a stressful situation, tired and hungry. -->
 
+TODO: pager?
+
 ## Disaster recovery
 
 <!-- what to do if all goes to hell. e.g. restore from backups? -->
 <!-- rebuild from scratch? not necessarily those procedures (e.g. see -->
 <!-- "Installation" below but some pointers. -->
 
+TODO: DR
+
 # Reference
 
 ## Installation
@@ -67,6 +73,8 @@ during downtimes, updates to websites are not possible.
 
 how is this thing built, basically? -->
 
+TODO: expand and review design.
+
 NOTE: this is worded as if this was already implement, but this
 implementation might be incomplete or even inexistent. See [ticket
 40364](https://gitlab.torproject.org/tpo/tpa/team/-/issues/40364) for more information on progress.
@@ -142,20 +150,40 @@ by all "critical" websites managed in GitLab.
 <!-- CI, test suites, linting, how security issues and upgrades are -->
 <!-- tracked -->
 
+TODO: write unit tests
+TODO: how is this monitored?
+
 ## Logs and metrics
 
 <!-- where are the logs? how long are they kept? any PII? -->
 <!-- what about performance metrics? same questions -->
 
+The webhook logs are available through `journalctl -u webhook` and in
+`/var/log/daemon.log`. They should not contain PII that is not already
+present in GitLab itself. Specifically, they might contain webhook
+payloads, artifacts URL and webpages contents.
+
+TODO: metrics?
+
 ## Backups
 
-<!-- does this service need anything special in terms of backups? -->
-<!-- e.g. locking a database? special recovery procedures? -->
+No specific backup procedure is necessary for this server, outside of
+the automated basics. In fact, data on this host is mostly ephemeral
+and could be reconstructed from pipelines in case of a total disaster.
 
 ## Other documentation
 
 <!-- references to upstream documentation, if relevant -->
 
+ * [Webhook homepage](https://github.com/adnanh/webhook)
+   * [hook definition documentation](https://github.com/adnanh/webhook/blob/master/docs/Hook-Definition.md)
+   * [hook examples](https://github.com/adnanh/webhook/blob/master/docs/Hook-Examples.md)
+   * [hook rules](https://github.com/adnanh/webhook/blob/master/docs/Hook-Rules.md)
+   * [how to refer to payload in hook configuration](https://github.com/adnanh/webhook/blob/master/docs/Referencing-Request-Values.md)
+   * [usage](https://github.com/adnanh/webhook/blob/master/docs/Webhook-Parameters.md)
+ * [GitLab webhook documentation](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html)
+ * [Design and launch ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/40364)
+
 # Discussion
 
 ## Overview