Changes

Page history
docs for new static-shim staging CI workflow authored by Jérôme Charaoui's avatar Jérôme Charaoui 
This mainly adds the important bits for working with the new review apps
and staging environments in GitLab CI.

Details at tpo/web/team#15
Show whitespace changes
Inline Side-by-side
service/static-shim.md
View page @ ccbb4772
......@@ -8,9 +8,10 @@ hosted in the [static mirror system][].
## Deploying a static site from GitLab CI
First, make sure the site builds in [GitLab CI][]. A `build` stage
MUST be used. It should produce the artifacts used by the `deploy`
job, provided in the [`static-shim-deploy.yml` template][]. How to
build the website will vary according to the site, obviously. See the
MUST be used. It should produce the artifacts used by the jobs defined
in the `deploy` stage which are provided in the
[`static-shim-deploy.yml` template][]. How to build the website will
vary according to the site, obviously. See the
[Hugo build instructions below](#building-a-hugo-site) for that
specific generator.
......@@ -18,12 +19,14 @@ specific generator.
TODO: link to documentation on how to build Lektor sites in GitLab CI.
It is a good idea to also add a `pages` stage to preview the
build. The above template has an example `pages` stage, see also the
[publishing GitLab pages](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/howto/gitlab/#publishing-gitlab-pages) section our [GitLab documentation](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/howto/gitlab/).
A convenient way to preview website builds and ensure builds are working
correctly in GitLab CI is to deploy to GitLab Pages. See the
instructions on [publishing GitLab pages](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/howto/gitlab/#publishing-gitlab-pages)
within the [GitLab documentation](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/howto/gitlab/).
Then include the deploy job template in the `.gitlab-ci.yml` with a
snippet like this:
When the build stage is verified to work correctly, include the
`static-shim-deploy.yml` template in `.gitlab-ci.yml` with a snippet
like this:
```
variables:
......@@ -67,6 +70,7 @@ variable`, with the following parameters:
* Type: `file`
* Protect variable: checked
* Masked variable: unchecked
* Environment scope: `production`
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
......@@ -76,9 +80,64 @@ Once you have sent the public key to TPA, you MUST destroy your local
copy of the key, to avoid any possible future leaks.
You can commit the above changes to the `.gitlab-ci.yml` file, but
when pushed, the pipeline's `deploy` stage is normal, TPA needs to do
its magic for the deploy to work. Make sure the build works in GitLab
pages before requesting the deploy in the static mirror system.
TPA needs to do its magic for the deploy stage to work.
Once deployments to the static mirror system are working, the `pages`
job can be removed or disabled.
## Working with Review Apps
[Review Apps](https://docs.gitlab.com/ee/ci/review_apps/) is a GitLab
feature that facilitates previewing changes in project branches and
Merge Requests.
When a new branch is pushed to the project, GitLab will automatically
run the build process on that branch and deploy the result, if
successful, to a special URL under `review.torproject.net`. If a MR
exists for the branch, a link to that URL is displayed in the MR page
header.
If additional commits are pushed to that branch, GitLab will rerun the
build process and update the deployment at the corresponding
`review.torproject.net` URL. Once the branch is deleted, which happens
for example if the MR is merged, GitLab automatically runs a job to
cleanup the preview build from `review.torproject.net`.
This feature is automatically enabled when `static-shim-deploy.yml` is
used. To opt-out of Review Apps, define `SKIP_REVIEW_APPS: 1` in the
`variables` key of `.gitlab-ci.yml`.
The active environments linked to Review Apps can be listed by
navigating to the project page -> Deployments -> Environments.
## Working with a staging environment
Some projects such as `blog.torproject.org` have a specific staging area
that is separate from GitLab Pages and `review.torproject.net`.
Staging environments can be useful in various scenarios, such as when
the build job for the production environment is different than the one
for Review Apps, so a staging URL is useful to be able to preview a full
build before being deployed to production.
To enable a staging environment, first a new domain name must be
created and pointed to `static.torproject.org`. An example is
`blog-staging.torproject.org` for the blog. This step must be done by
TPA, so please [open a ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/new).
Then, a new SSH key must be added to Puppet, using the same procedure as
for the production environment (see [above](#deploying-a-static-site-from-gitlab-ci)).
Only in this case, when adding the private key to CI/CD variables, use
`staging` as Environment scope instead of `production`.
Lastly, a `STAGING_URL` variable must be added to `.gitlab-ci.yml` with
the staging domain name (eg. `blog-staging.torproject.org`) as its
value.
Once this is in place, commits added the the default (`main`) branch
will automatically trigger a deployment to the staging URL and a manual
job for deployment to production. **This manual job must then be
triggered by hand after the staging deployment is QA-cleared.**
# How-to
......@@ -299,6 +358,23 @@ should provide more information.
## Disaster recovery
### Revert a deployment mistake
It's possible to quickly revert to a previous version of a website via
GitLab Environments.
Simply navigate to the project page -> Deployments -> Environments ->
production. Shown here will be all past deployments to this
environment. To the left of each deployment is a Rollback environment
button. Clicking this button will redeploy this version of the website
to the static mirror system, overwriting the current version.
It's important to note that the rollback will only work as long as the
build artifacts are available in GitLab. By default, artifacts expire
after two weeks, so its possible to rollback to any version within two
weeks of the present day. Unfortunately, at the moment GitLab shows a
rollback button even if the artifacts are unavailable.
### Server lost
The service is "cattle" in that it can easily be rebuilt from scratch
......
......