... | ... | @@ -15,10 +15,27 @@ but is documented separately. |
|
|
|
|
|
<!-- more in-depth procedure that may require interpretation -->
|
|
|
|
|
|
## Setting up a local development environment
|
|
|
## Local development environment
|
|
|
|
|
|
See the [installation](#installation) section below. Basically, you
|
|
|
need to install `hugo` and clone the repo (with submodules!).
|
|
|
To install the development environment for the status site, you should
|
|
|
have a copy of the [Hugo](https://gohugo.io/) static site generator
|
|
|
and the git repository:
|
|
|
|
|
|
sudo apt install hugo
|
|
|
git clone --recursive -b main git@git-rw.torproject.org:project/web/status-site
|
|
|
cd status-site
|
|
|
|
|
|
Then you can start a local development server to preview the site
|
|
|
with:
|
|
|
|
|
|
hugo serve --baseUrl=http://localhost/
|
|
|
firefox https://localhost:1313/
|
|
|
|
|
|
The content can also be built in the `public/` directory with, simply:
|
|
|
|
|
|
hugo
|
|
|
|
|
|
Most configuration happens in `config.yaml`.
|
|
|
|
|
|
## Modifying the site
|
|
|
|
... | ... | @@ -39,44 +56,38 @@ The logo lives in `static/logo.png`. Some colors are defined in |
|
|
## Uploading site to the static mirror system
|
|
|
|
|
|
The `status.torproject.org` site currently lives in the [static mirror
|
|
|
system](howto/static-component) and uses the [git-rw repository](https://gitweb.torproject.org/project/web/status-site.git/) which get built via Jenkins once you push to the repo.
|
|
|
|
|
|
You can preview changes by starting a local server:
|
|
|
|
|
|
hugo serve --baseUrl=http://localhost/
|
|
|
firefox https://localhost:1313/
|
|
|
system](howto/static-component) and uses the [git-rw repository](https://gitweb.torproject.org/project/web/status-site.git/) which get built via
|
|
|
Jenkins once you push to the repo.
|
|
|
|
|
|
To publish the website, it needs to be built locally, with this simple
|
|
|
command:
|
|
|
In other words, uploading the site is automated by continuous
|
|
|
integration. So you simply need to commit and push:
|
|
|
|
|
|
hugo
|
|
|
git commit -a -myolo
|
|
|
git push
|
|
|
|
|
|
That will create a bunch of (mostly plain HTML) files in
|
|
|
`public/`.
|
|
|
You will see progress of the Jenkins jobs:
|
|
|
|
|
|
* [hugo-website-status](https://jenkins.torproject.org/job/hugo-website-status/) (build job)
|
|
|
* [hugo-website-status-install](https://jenkins.torproject.org/job/hugo-website-status-install/) (install job)
|
|
|
|
|
|
If git-rw is down, you can login to staticiforme.torproject.org and upload the public folder content under /srv/status.torproject.org/htdocs.
|
|
|
If all goes well, the changes should propagate to the mirrors within
|
|
|
about 5 to 10 minutes, depending on how busy Jenkins is.
|
|
|
|
|
|
The canonical source for the static websites rotation is defined in Puppet, in `modules/roles/misc/static-components.yaml`). This `rsync` command should be enough:
|
|
|
Note that only the `webwml` group has access to the repository for
|
|
|
now. Merge requests may also be issued from the mirror of the
|
|
|
repository on GitLab:
|
|
|
|
|
|
rsync -rtP public/ anarcat@staticiforme.torproject.org:/srv/status.torproject.org/status-site/public/
|
|
|
<https://gitlab.torproject.org/tpo/tpa/status-site>
|
|
|
|
|
|
NOTE: there is a copy of the static site git repository there. Ignore
|
|
|
it, it's out of date but could be used to build the website in a pinch.
|
|
|
... but will need to be merged into the `git-rw` server by someone in
|
|
|
the above group to take effect. More people have access to the GitLab
|
|
|
repository and should therefore be able to collaborate there.
|
|
|
|
|
|
Then the new source material needs to be synchronized to the mirrors,
|
|
|
with:
|
|
|
See also the [disaster recovery](#disaster-recovery) options below.
|
|
|
|
|
|
sudo -u torwww static-update-component status.torproject.org
|
|
|
|
|
|
This requires membership to the `torwww` group.
|
|
|
|
|
|
Don't forget to push the changes to the git repository, even though
|
|
|
that doesn't actually trigger an update, it's important so that the
|
|
|
next people can start from your changes:
|
|
|
|
|
|
git commit -a -myolo
|
|
|
git push
|
|
|
Keep in mind that this is a public website. You might want to talk
|
|
|
with the `comms@` people before publishing big or sensitive
|
|
|
announcements.
|
|
|
|
|
|
## Pager playbook
|
|
|
|
... | ... | @@ -89,19 +100,46 @@ next people can start from your changes: |
|
|
It should be possible to deploy the static website anywhere that
|
|
|
supports plain HTML, assuming you have a copy of the git repository.
|
|
|
|
|
|
The instructions below asssume you have a copy of the git repository
|
|
|
(currently
|
|
|
<https://gitlab.torproject.org/tpo/tpa/status-site.git>). If not, you
|
|
|
could start from scratch using [the example
|
|
|
repository](https://github.com/cstate/example) as well. Make sure you
|
|
|
follow the [installation instructions](#installation) to also clone
|
|
|
the submodules!
|
|
|
The instructions below asssume you have a copy of the git
|
|
|
repository. Make sure you follow the [installation instructions](#local-development-environment) to
|
|
|
also clone the submodules! If the git repository is not available, you
|
|
|
could start from scratch using [the example repository](https://github.com/cstate/example) as well.
|
|
|
|
|
|
From here on, it is assumed you have a copy of the git repository (or
|
|
|
the example one).
|
|
|
|
|
|
Those procedures were not tested.
|
|
|
|
|
|
### Manual deployment to the static mirror system
|
|
|
|
|
|
If `git-rw` is down, you can upload the `public/` folder content under
|
|
|
`/srv/status.torproject.org/htdocs`.
|
|
|
|
|
|
The canonical source for the static websites rotation is defined in
|
|
|
Puppet (in `modules/roles/misc/static-components.yaml`) and is
|
|
|
currently set to `staticiforme.torproject.org`. This `rsync` command
|
|
|
should be enough:
|
|
|
|
|
|
rsync -rtP public/ anarcat@staticiforme.torproject.org:/srv/status.torproject.org/htdocs
|
|
|
|
|
|
NOTE: there is a copy of the git repository in `/status-site` as
|
|
|
well. Ignore it: it's out of date but could be used to build the
|
|
|
website in a pinch.
|
|
|
|
|
|
Then the new source material needs to be synchronized to the mirrors,
|
|
|
with:
|
|
|
|
|
|
sudo -u torwww static-update-component status.torproject.org
|
|
|
|
|
|
This requires membership to the `torwww` group.
|
|
|
|
|
|
Don't forget to push the changes to the git repository, once that is
|
|
|
available. It's important so that the next people can start from your
|
|
|
changes:
|
|
|
|
|
|
git commit -a -myolo
|
|
|
git push
|
|
|
|
|
|
### Netlify deployment
|
|
|
|
|
|
Upstream has instructions to [deploy to Netlify](https://github.com/cstate/cstate#-netlify-and-netlify-cms), which, in our
|
... | ... | @@ -129,24 +167,10 @@ Then DNS needs to be tweaked to point there as well. |
|
|
|
|
|
## Installation
|
|
|
|
|
|
The basic setup for cstate is:
|
|
|
See the instructions on how to [setup a local development
|
|
|
environment](#local-development-environment) and the [design section](#design) for more information on
|
|
|
how this is setup.
|
|
|
|
|
|
sudo apt install hugo
|
|
|
git clone --recursive -b main https://gitlab.torproject.org/tpo/tpa/status-site.git
|
|
|
cd status-site
|
|
|
hugo serve --baseUrl=http://localhost/
|
|
|
|
|
|
This start a local web server. To view it in your web browser, for
|
|
|
example:
|
|
|
|
|
|
firefox https://localhost:1313/
|
|
|
|
|
|
The content can be built in the `public/` directory with, simply:
|
|
|
|
|
|
hugo
|
|
|
|
|
|
Most configuration happens in `config.yaml`.
|
|
|
|
|
|
## SLA
|
|
|
|
|
|
This service should be highly available. It should support failure
|
... | ... | @@ -163,6 +187,25 @@ deploy it to a third-party provider. |
|
|
<!-- a good guide to "audit" an existing project's design: -->
|
|
|
<!-- https://bluesock.org/~willkg/blog/dev/auditing_projects.html -->
|
|
|
|
|
|
The status site is part of the [static mirror system](howto/static-component) and is built
|
|
|
with Jenkins jobs, from a git repository on the [git](howto/git) server. This
|
|
|
was setup this way because that is how every other static website is
|
|
|
currently built.
|
|
|
|
|
|
This involved:
|
|
|
|
|
|
* a new [static component](howto/static-component) owned by `torwww`
|
|
|
* a new [build script](https://gitweb.torproject.org/project/jenkins/tools.git/tree/slaves/linux/hugo-website-status?id=7fff67041e41206fef7d128ac60488db375652a1) in the [Jenkins tools repo](https://gitweb.torproject.org/project/jenkins/tools.git/),
|
|
|
* a [new entry](https://gitweb.torproject.org/admin/static-builds.git/commit/?id=b2344aa1d68f4f065764c6f23d14494020b81f86) in the [ssh wrapper](https://gitweb.torproject.org/admin/static-builds.git/tree/ssh-wrap?id=b2344aa1d68f4f065764c6f23d14494020b81f86)
|
|
|
* a new [build job](https://gitweb.torproject.org/project/jenkins/jobs.git/commit/?id=170fd9879ff0da65670aaa36c20e63c0db1ed039) in the [Jenkins jobs repo](https://gitweb.torproject.org/project/jenkins/jobs.git/)
|
|
|
* a new [git](howto/git) repository with hooks to ping the Jenkins server and
|
|
|
mirror to GitLab
|
|
|
|
|
|
We also considered using GitLab CI for deployment but (a) GitLab pages
|
|
|
is not yet setup and (b) it doesn't integrate well with the static
|
|
|
mirror system for now. See [the broader discussion of the static site
|
|
|
system improvements](howto/static-component#proposed-solution).
|
|
|
|
|
|
## Issues
|
|
|
|
|
|
There is no issue tracker specifically for this project, [File][] or
|
... | ... | |