service/static-shim.md

@@ -16,6 +16,149 @@ TODO: "how do users add/remove sites"
 
 TODO: review ticket for possible howtos
 
+## Deploying a Hugo site
+
+Normally, you should be able to deploy a hugo site by including the
+template and setting a few variables. This `.gitlab-ci.yml` file
+should be sufficient:
+
+```
+include:
+  project: tpo/tpa/status-site
+  file: .gitlab-ci.yml
+
+variables:
+  GIT_SUBMODULE_STRATEGY: recursive
+  SITE_URL: research.torproject.org
+  SUBDIR: public/
+```
+
+See below if this is an old hugo site, however.
+
+Then you also need to set an SSH key in the project. First, generate a
+password-less key locally:
+
+    ssh-keygen -f id_rsa -P "" -C "static-shim deploy key"
+
+Then in the project's Settings -> CI/CD -> Variables, pick `Add
+variable`, with the following parameters:
+
+ * Key: `STATIC_GITLAB_SHIM_SSH_PRIVATE_KEY`
+ * Value: the content of the `id_rsa` file, above (yes, it's the
+   private key)
+ * Type: `file`
+ * Protect variable: checked
+ * Masked variable: unchecked
+
+Then the *public* part of that key needs to be added in Puppet. This
+can only be done by TPA, so file a ticket there if you need
+assistance. The key should be added in the `tor-puppet.git`
+repository, in the `hiera/common.yaml` file, in the
+`staticsync::gitlab_shim::ssh::sites` hash, in which the site URL is
+the key and the public key (only the key part, no `ssh-rsa` prefix or
+comment suffix) is the value. For example, this is the entry for
+`status.torproject.org`:
+
+    staticsync::gitlab_shim::ssh::sites:
+      status.torproject.org: "AAAAB3NzaC1yc2EAAAADAQABAAABgQC3mXhQENCbOKgrhOWRGObcfqw7dUVkPlutzHpycRK9ixhaPQNkMvmWMDBIjBSviiu5mFrc6safk5wbOotQonqq2aVKulC4ygNWs0YtDgCtsm/4iJaMCNU9+/78TlrA0+Sp/jt67qrvi8WpLF/M8jwaAp78s+/5Zu2xD202Cqge/43AhKjH07TOMax4DcxjEzhF4rI19TjeqUTatIuK8BBWG5vSl2vqDz2drbsJvaLbjjrfbyoNGuK5YtvI/c5FkcW4gFuB/HhOK86OH3Vl9um5vwb3DM2HVMTiX15Hw67QBIRfRFhl0NlQD/bEKzL3PcejqL/IC4xIJK976gkZzA0wpKaE7IUZI5yEYX3lZJTTGMiZGT5YVGfIUFQBPseWTU+cGpNnB4yZZr4G4o/MfFws4mHyh4OAdsYiTI/BfICd3xIKhcj3CPITaKRf+jqPyyDJFjEZTK/+2y3NQNgmAjCZOrANdnu7GCSSz1qkHjA2RdSCx3F6WtMek3v2pbuGTns="
+
+Note that this will only allow GitLab CI to push to the shim, but will
+still fail to deploy because the static-component configuration does
+not match. Once you are satisfied your build works (try on a branch
+first to see if the GitLab pages version renders correctly), the
+static-component should be changed to point to the shim, with a commit
+like this:
+
+    modified   modules/roles/misc/static-components.yaml
+    @@ -99,7 +99,7 @@ components:
+         source: staticiforme.torproject.org:/srv/research.torproject.org/htdocs-staging
+       research.torproject.org:
+         master: static-master-fsn.torproject.org
+    -    source: staticiforme.torproject.org:/srv/research.torproject.org/htdocs
+    +    source: static-gitlab-shim.torproject.org:/srv/static-gitlab-shim/research.torproject.org/public
+       rpm.torproject.org:
+         master: static-master-fsn.torproject.org
+         source: staticiforme.torproject.org:/srv/rpm.torproject.org/htdocs
+
+After commit and push, Puppet needs to run on the shim and master, in
+the above case:
+
+    for host in static-gitlab-shim static-master-fsn ; do
+        ssh $host.torproject.org puppet agent --test
+    done
+
+The site should now be deployed from GitLab CI. 
+
+Make sure to [remove the old Jenkins job](service/jenkins#removing-a-job) and make sure the old
+site is cleared out from the previous static source:
+
+    ssh staticiforme.torproject.org rm -rf /srv/research.torproject.org/
+
+Typically, you will also want to [archive the git repository](howto/git#archiving-a-repository) if
+it hasn't already been [migrated to GitLab](howto/gitlab#how-to-migrate-a-git-repository-from-legacy-to-gitlab).
+
+### Deploying an old Hugo site
+
+Unfortunately, because `research.torproject.org` was built a long time
+ago, newer Hugo releases broke its theme and the newer versions
+(tested 0.65, 0.80, and 0.88) all fail in one way or another. In this
+case, you need to jump through some hoops to have the build work
+correctly. I did this for `research.tpo`, but you might need a
+different build system or Docker images:
+
+```
+# use an older version of hugo, newer versions fail to build on first
+# run
+#
+# gohugo.io does not maintain docker images and the one they do
+# recommend fail in GitLab CI. we do not use the GitLab registry
+# either because we couldn't figure out the right syntax to get the
+# old version from Debian stretch (0.54)
+image: registry.hub.docker.com/library/debian:buster
+
+include:
+  project: tpo/tpa/status-site
+  file: .gitlab-ci.yml
+
+variables:
+  GIT_SUBMODULE_STRATEGY: recursive
+  SITE_URL: research.torproject.org
+  SUBDIR: public/
+
+build:
+  before_script:
+    - apt update
+    - apt upgrade -yy
+    - apt install -yy hugo
+  stage: build
+  script:
+    - hugo
+  artifacts:
+    paths:
+      - public
+
+# we'd like to *not* rebuild hugo here, but pages fails with:
+#
+# jobs pages config should implement a script: or a trigger: keyword
+#
+# and even if we *do* put a dummy script (say "true"), this fails
+# because it runs in parallel with the build stage, and therefore
+# doesn't inherit artifacts the way a deploy stage normally would.
+pages:
+  stage: deploy
+  before_script:
+    - apt update
+    - apt upgrade -yy
+    - apt install -yy hugo
+  script:
+    - hugo
+  artifacts:
+    paths:
+      - public
+  only:
+    - merge_requests
+```
+
 ## Deploy artifacts manually
 
 If a site is not deploying normally, it's possible to deploy a site by