Changes

Page history
complete the status site documentation authored by anarcat's avatar anarcat
Hide whitespace changes
Inline Side-by-side
service/status.md
View page @ d9b2a842
...@@ -8,13 +8,6 @@ but is documented separately. ...@@ -8,13 +8,6 @@ but is documented separately.
# Tutorial # 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 ## Local development environment
To install the development environment for the status site, you should 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: ...@@ -35,24 +28,10 @@ The content can also be built in the `public/` directory with, simply:
hugo hugo
Most configuration happens in `config.yaml`.
## Modifying the site ## Modifying the site
Issues are in `content/issues`. TODO: Expand. 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 ## Uploading site to the static mirror system
The `status.torproject.org` site currently lives in the [static mirror 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 ...@@ -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 with the `comms@` people before publishing big or sensitive
announcements. 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 ## Pager playbook
<!-- information about common errors from the monitoring system and --> The only Nagios warning that can come out of this service is if the
<!-- how to deal with them. this should be easy to follow: think of --> static synchronisation fails. See the [static site system](howto/static-component) for more
<!-- your future self, in a stressful situation, tired and hungry. --> information on diagnosing those.
## Disaster recovery ## Disaster recovery
...@@ -158,8 +151,8 @@ Then, of course, DNS needs to be updated to point there. ...@@ -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 A site could also be deployed on *another* GitLab server with "GitLab
pages" enabled. For example, if the repository is pushed to pages" enabled. For example, if the repository is pushed to
https://gitlab.com/, the GitLab CI/CD system there will automatically <https://gitlab.com/>, the GitLab CI/CD system there will
pick it up and publish it. automatically pick it up and publish it.
Then DNS needs to be tweaked to point there as well. 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 ...@@ -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. deploy it to a third-party provider.
## Design ## 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 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 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 ...@@ -218,18 +203,19 @@ Upstream issues can be found and filed in the [GitHub issue tracker](https://git
## Monitoring and testing ## Monitoring and testing
<!-- describe how this service is monitored and how it can be tested --> The site, like other static mirrors, is monitored by [Nagios](howto/nagios) with
<!-- after major changes like IP address changes or upgrades --> the `dsa_check_staticsync` check, which ensures all mirrors are up to
date.
## Logs and metrics ## Logs and metrics
<!-- where are the logs? how long are they kept? any PII? --> There are no logs or metrics specific to this service, see the [static
<!-- what about performance metrics? same questions --> site service](howto/static-component) for details.
## Backups ## Backups
<!-- does this service need anything special in terms of backups? --> Does not need special backups: backed up as part of the regular [static
<!-- e.g. locking a database? special recovery procedures? --> site](howto/static-component) and [git](howto/git) services.
## Other documentation ## Other documentation
... ...
......