Changes
Page history
complete the status site documentation
authored
Jan 27, 2021
by
anarcat
Hide whitespace changes
Inline
Side-by-side
service/status.md
View page @
d9b2a842
...
...
@@ -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
<!-- w
here are
the
logs
? how long are they kept? any PII? -->
<!-- what about performance metrics? same questions -->
T
here 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
...
...
...
...
