... | ... | @@ -8,13 +8,6 @@ but is documented separately. |
|
|
|
|
|
# Tutorial
|
|
|
|
|
|
<!-- simple, brainless step-by-step instructions requiring little or -->
|
|
|
<!-- no technical background -->
|
|
|
|
|
|
# How-to
|
|
|
|
|
|
<!-- more in-depth procedure that may require interpretation -->
|
|
|
|
|
|
## Local development environment
|
|
|
|
|
|
To install the development environment for the status site, you should
|
... | ... | @@ -35,24 +28,10 @@ The content can also be built in the `public/` directory with, simply: |
|
|
|
|
|
hugo
|
|
|
|
|
|
Most configuration happens in `config.yaml`.
|
|
|
|
|
|
## Modifying the site
|
|
|
|
|
|
Issues are in `content/issues`. TODO: Expand.
|
|
|
|
|
|
## Changing categories
|
|
|
|
|
|
cState relies on "systems" which live inside a "category" For example,
|
|
|
the "v3 onion services" are in the "Tor network" category. Those are
|
|
|
defined in the `config.yml` file, and each issue (in `content/issues`)
|
|
|
refers to one or more "system" that is affected by it.
|
|
|
|
|
|
## Theming
|
|
|
|
|
|
The logo lives in `static/logo.png`. Some colors are defined in
|
|
|
`config.yml`, search for `Colors throughout cState`.
|
|
|
|
|
|
## Uploading site to the static mirror system
|
|
|
|
|
|
The `status.torproject.org` site currently lives in the [static mirror
|
... | ... | @@ -89,11 +68,25 @@ Keep in mind that this is a public website. You might want to talk |
|
|
with the `comms@` people before publishing big or sensitive
|
|
|
announcements.
|
|
|
|
|
|
# How-to
|
|
|
|
|
|
## Changing categories
|
|
|
|
|
|
cState relies on "systems" which live inside a "category" For example,
|
|
|
the "v3 onion services" are in the "Tor network" category. Those are
|
|
|
defined in the `config.yml` file, and each issue (in `content/issues`)
|
|
|
refers to one or more "system" that is affected by it.
|
|
|
|
|
|
## Theming
|
|
|
|
|
|
The logo lives in `static/logo.png`. Some colors are defined in
|
|
|
`config.yml`, search for `Colors throughout cState`.
|
|
|
|
|
|
## 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. -->
|
|
|
The only Nagios warning that can come out of this service is if the
|
|
|
static synchronisation fails. See the [static site system](howto/static-component) for more
|
|
|
information on diagnosing those.
|
|
|
|
|
|
## Disaster recovery
|
|
|
|
... | ... | @@ -158,8 +151,8 @@ Then, of course, DNS needs to be updated to point there. |
|
|
|
|
|
A site could also be deployed on *another* GitLab server with "GitLab
|
|
|
pages" enabled. For example, if the repository is pushed to
|
|
|
https://gitlab.com/, the GitLab CI/CD system there will automatically
|
|
|
pick it up and publish it.
|
|
|
<https://gitlab.com/>, the GitLab CI/CD system there will
|
|
|
automatically pick it up and publish it.
|
|
|
|
|
|
Then DNS needs to be tweaked to point there as well.
|
|
|
|
... | ... | @@ -178,14 +171,6 @@ from one or all point of presence: if all fail, it should be easy to |
|
|
deploy it to a third-party provider.
|
|
|
|
|
|
## Design
|
|
|
<!-- how this is built -->
|
|
|
<!-- should reuse and expand on the "proposed solution", it's a -->
|
|
|
<!-- "as-built" documented, whereas the "Proposed solution" is an -->
|
|
|
<!-- "architectural" document, which the final result might differ -->
|
|
|
<!-- from, sometimes significantly -->
|
|
|
|
|
|
<!-- 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
|
... | ... | @@ -218,18 +203,19 @@ Upstream issues can be found and filed in the [GitHub issue tracker](https://git |
|
|
|
|
|
## Monitoring and testing
|
|
|
|
|
|
<!-- describe how this service is monitored and how it can be tested -->
|
|
|
<!-- after major changes like IP address changes or upgrades -->
|
|
|
The site, like other static mirrors, is monitored by [Nagios](howto/nagios) with
|
|
|
the `dsa_check_staticsync` check, which ensures all mirrors are up to
|
|
|
date.
|
|
|
|
|
|
## Logs and metrics
|
|
|
|
|
|
<!-- where are the logs? how long are they kept? any PII? -->
|
|
|
<!-- what about performance metrics? same questions -->
|
|
|
There are no logs or metrics specific to this service, see the [static
|
|
|
site service](howto/static-component) for details.
|
|
|
|
|
|
## Backups
|
|
|
|
|
|
<!-- does this service need anything special in terms of backups? -->
|
|
|
<!-- e.g. locking a database? special recovery procedures? -->
|
|
|
Does not need special backups: backed up as part of the regular [static
|
|
|
site](howto/static-component) and [git](howto/git) services.
|
|
|
|
|
|
## Other documentation
|
|
|
|
... | ... | |