Changes

Jérôme Charaoui · d27d31c3
--- a/howto/lektor.md
+++ b/howto/lektor.md
@@ -74,9 +74,9 @@ the build artifacts are automatically unpublished.

 ## 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. -->
+See [#revert-a-deployment-mistake](service/static-shim#revert-a-deployment-mistake)
+for instruction on how to roll-back an environment to its previous state after
+an accidental deployment.

 # Reference

@@ -140,33 +140,113 @@ the template to use a different image, and set `GIT_STRATEGY` to `clone`.
 This is in addition to the ability to override the named job parameters
 directly in `.gitlab-ci.yml`.

-### CD pipelines
+### CD pipelines and environments
+
+The Tor Project Lektor websites are deployed automatically by GitLab by a process
+of continuous deployment (CD).
+
+#### Staging and production
+
+Deployments to staging and production environments are handled by the
+[static-shim-deploy.yml][] CI template. The [service/static-shim][] wiki page
+describes the prerequisites for GitLab to be able to upload websites to the
+[static mirror system][].
+
+A basic Lektor project that deploys to production would have a `.gitlab-ci.yml`
+set up like this:
+
+    ---
+    variables:
+      SITE_URL: example.torproject.org
+
+    include:
+      project: tpo/tpa/ci-templates
+      file:
+        - lektor.yml
+        - static-shim-deploy.yml
+
+See the [#template-variables](service/static-shim#template-variables)
+documentation for details about the variables involved in the deployment process.
+
+See the [#working-with-a-staging-environments](service/static-shim#working-with-a-staging-environment)
+documentation for details about adding a staging environment to a project's
+deployment workflow.
+
+[static-shim-deploy.yml]: https://gitlab.torproject.org/tpo/tpa/ci-templates/-/blob/main/static-shim-deploy.yml
+[service/static-shim]: https://gitlab.torproject.org/tpo/tpa/team/-/wikis/service/static-shim
+[static mirror system]: https://gitlab.torproject.org/tpo/tpa/team/-/wikis/howto/static-component

 ### Review apps

+Lektor projects which include `static-shim-deploy.yml` and have access to the
+`REVIEW_STATIC_GITLAB_SHIM_SSH_PRIVATE_KEY` CI variable (this includes all
+projects in the `tpo/web` namespace) have [Review apps][] automatically enabled.
+
+See the [#working-with-review-apps](service/static-shim#working-with-review-apps)
+documentation for details about how to use Review apps.
+
+[Review apps]: https://docs.gitlab.com/ee/ci/review_apps/
+
+### Localization staging
+
+To support the work of translation contributors who work on the Tor Project
+websites, we automatically build and deploy special localized versions of the
+projects to `reviews.torproject.net`.
+
+The workflow can be described as follows:
+
+  1. Translations are contributed on Transifex
+
+  2. Every 30 minutes, these changes are merged to the corresponding branches in
+     the translation repository and pushed to [tpo/translation][]
+
+  3. A project pipeline is triggered and runs the jobs from the
+     [l10n-staging-trigger.yml][] CI template
+
+  4. If the changed files include any `.po` which is >15% translated, a pipeline
+     will be triggered in the Lektor project with the special `L10N_STAGING`
+     variable added
+
+  5. In the Lektor project, the presence of the `L10N_STAGING` variable alters
+     the regular build job: all languages >15% translated are built instead of
+     only the officially supported languages for that project. The result is
+     deployed to `reviews.torproject.net/tpo/web/<project-name>/l10n`
+
+To enable localization staging for a Lektor project, it's sufficient to add this
+snippet in `.gitlab-ci.yml` in the relevant [tpo/translation][] branch
+
+    variables:
+      TRANSLATION_BRANCH : $CI_COMMIT_REF_NAME
+      LEKTOR_PROJECT: tpo/web/<project-name>
+
+    include:
+      - project: tpo/tpa/ci-templates
+        file: lektor-l10n-staging-trigger.yml
+
+Replace `<project-name>` with the name of the Lektor GitLab project.
+
+[tpo/translation]: https://gitlab.torproject.org/tpo/translation
+
 ## Issues

-<!-- such projects are never over. add a pointer to well-known issues -->
-<!-- and show how to report problems. usually a link to the bugtracker -->
+Lektor website projects on GitLab have individual issue trackers, so problems
+related to specific websites such as typos, bad links, missing content or
+build problems should be filed in the relevant tracker.

-There is no issue tracker specifically for this project, [File][] or
-[search][] for issues in the [team issue tracker][search].
+For problems related to deployments or CI templates specifically, [File][] or
+[search][] for issues in the [ci-templates issue tracker][search].

- [File]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/new
- [search]: https://gitlab.torproject.org/tpo/tpa/team/-/issues
+ [File]: https://gitlab.torproject.org/tpo/tpa/ci-templates/-/issues/new
+ [search]: https://gitlab.torproject.org/tpo/tpa/ci-templates/-/issues

 ## Maintainer, users, and upstream

-<!-- document who deployed and operates this service, who the users -->
-<!-- are, who the upstreams are, if they are still active, -->
-<!-- collaborative, how do we keep up to date, -->
+Lektor websites are maintained in collaboration by the Web team and TPA.

 ## Monitoring and testing

-<!-- describe how this service is monitored and how it can be tested -->
-<!-- after major changes like IP address changes or upgrades. describe -->
-<!-- CI, test suites, linting, how security issues and upgrades are -->
-<!-- tracked -->
+Currently there is no monitoring beyond the supporting infrastructure (eg. DNS,
+host servers, httpd, etc.).

 ## Logs and metrics

@@ -175,12 +255,15 @@ There is no issue tracker specifically for this project, [File][] or

 ## Backups

-<!-- does this service need anything special in terms of backups? -->
-<!-- e.g. locking a database? special recovery procedures? -->
+There are no backups specific to Lektor.
+
+Source code of our Lektor projects is backed up along with GitLab itself, and the
+production build artifacts themselves are picked up with those of the hosts
+comprising the static mirror system.

 ## Other documentation

-<!-- references to upstream documentation, if relevant -->
+ * [Lektor documentation](https://www.getlektor.com/docs/)

 # Discussion