From c87997a89a7f686b220754e31c158d76b09bfc4f Mon Sep 17 00:00:00 2001 From: Peter Law Date: Wed, 23 Dec 2020 19:09:21 +0000 Subject: [PATCH 01/12] Add initial overview of our tech infrastructure --- docs/infrastructure/README.md | 45 +++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/infrastructure/README.md diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md new file mode 100644 index 00000000..214aa955 --- /dev/null +++ b/docs/infrastructure/README.md @@ -0,0 +1,45 @@ +# Overview + +Student Robotics has a variety of infrastrcture in order to support its mission. +This document aims to provide an outline of the general structure. + +Currently our infrastructure as a whole does not have a designed owner, instead +individual pieces are looked after by volunteer Teams or just by volunteers who +have historically maintained them. + +## Website + +Our website consists of a main public facing site at https://studentrobotics.org +as well as a collection of other sites which appear at various paths off the +root domain. This runbook is an example of such a sub-site, as are the +competitor-facing documentation which appears at [`/docs`][slash-docs]. + +These sub sites (and the main website itself) are hosted as GitHub Pages, with a +separate NGINX instance acting as a [reverse-proxy][reverse-proxy] to facade +these onto the root domain. Currently we use Digital Ocean for the hosting of +our [infrastructure](https://github.com/srobo/infrastructure) as well as for DNS +and TLS termination. Our domains are registered with Namecheap. + +[slash-docs]: https://studentrobotics.org/docs +[reverse-proxy]: https://github.com/srobo/reverse-proxy + +## Development: GitHub + +Our hardware and software development takes place on GitHub, within our +[`srobo`](https://github.com/srobo) organisation. + +We also have a separate [`srobo-legacy`](https://github.com/srobo-legacy) +organisation which contains some archived git repositories that pre-date our use +of GitHub. Moving these over to the main organisation and de-duplicating the +repositories is an [ongoing project][legacy-repository-migration]. + +[legacy-repository-migration]: https://github.com/srobo/tasks/issues/179 + +## Email, Documents: Google + +For our email (`@studentrobotics.org`) accounts as well as document sharing we +use Google's G-Suite. Google Groups are used for various mailing lists. + +## External mailing lists: Mailchimp + +For sending some batch emails we use Mailchimp. From 9c1c2c66cf7045b711d287b7a749ee920a939660 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Wed, 23 Dec 2020 19:12:34 +0000 Subject: [PATCH 02/12] Add notes on our competitor services --- docs/infrastructure/README.md | 6 ++++ docs/infrastructure/competitor-services.md | 35 ++++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 docs/infrastructure/competitor-services.md diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 214aa955..12fa396b 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -23,6 +23,12 @@ and TLS termination. Our domains are registered with Namecheap. [slash-docs]: https://studentrobotics.org/docs [reverse-proxy]: https://github.com/srobo/reverse-proxy +### Competitor Services + +During the competition, there are a number of [hosted services](./competitor-services.md) +which the competitors use. These have thier own managed configuration and are +typically hosted for the duration of the competition "year" only. + ## Development: GitHub Our hardware and software development takes place on GitHub, within our diff --git a/docs/infrastructure/competitor-services.md b/docs/infrastructure/competitor-services.md new file mode 100644 index 00000000..85dea35b --- /dev/null +++ b/docs/infrastructure/competitor-services.md @@ -0,0 +1,35 @@ +# Competitor Services + +During the competition season, there are a number of hosted services which the +competitors use. These are [managed using `puppet`][server-puppet] to configure +a "competitor services" VM, typically within Digital Ocean. + +[server-puppet]: https://github.com/srobo/server-puppet/ + +The services typically include: + +**Forums** +: A space which the competitors can use to chat with each other and with + mentors and to ask for help with developing their robots. + Historically we have used [PHPBB](https://phpbb.com), though for SR2021 we + have moved to using Discord with a bot to [gate entry](discord-gated-entry). + +**[IDE](https://github.com/srobo/srobo-ide/)** +: A hosted web-based environment which allows competitors to develop code for + their robots without needing to install anything on their own computers. + +**User accounts** +: User accounts are needed for access to the IDE and our self-hosted forums. + We also host a [management interface](https://github.com/srobo/nemesis/) so + that team-leaders can administer the user-accounts of their teams. + +**Ticket access** +: At the physical competition we gate entry through the use of tickets which + competitors download from the website ahead of time. + +**[Code submitter](https://github.com/PeterJCLaw/code-submitter/)** +: For the virtual competitions, this is a mechanism for competitors to submit + the code for their virtual robots. + + +[discord-gated-entry]: https://github.com/srobo/discord-gated-entry/ From 7d97142cf1313aa6283aa916bc39820d129009fc Mon Sep 17 00:00:00 2001 From: Peter Law Date: Wed, 23 Dec 2020 19:20:51 +0000 Subject: [PATCH 03/12] Add a brief mention of SRComp for during the competition events --- docs/infrastructure/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 12fa396b..05f8adf2 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -29,6 +29,14 @@ During the competition, there are a number of [hosted services](./competitor-ser which the competitors use. These have thier own managed configuration and are typically hosted for the duration of the competition "year" only. +### Competition Services + +During the competition event we use the [SRComp suite][srcomp-suite] of tools to +help run the matches, including a VM to host a public-facing copy of the HTTP +API for use on the website. + +[srcomp-suite]: https://github.com/PeterJCLaw/srcomp/wiki + ## Development: GitHub Our hardware and software development takes place on GitHub, within our From ce75d2f3f7caf3cacb6d0df46e874ab8c7f668a6 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 18:56:52 +0000 Subject: [PATCH 04/12] Clarify that NGINX proxies other services too --- docs/infrastructure/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 05f8adf2..84bd57c9 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -16,12 +16,13 @@ competitor-facing documentation which appears at [`/docs`][slash-docs]. These sub sites (and the main website itself) are hosted as GitHub Pages, with a separate NGINX instance acting as a [reverse-proxy][reverse-proxy] to facade -these onto the root domain. Currently we use Digital Ocean for the hosting of -our [infrastructure](https://github.com/srobo/infrastructure) as well as for DNS -and TLS termination. Our domains are registered with Namecheap. +these and other services onto the root domain. Currently we use Digital Ocean +for the hosting of our [infrastructure][infrastructure] as well as for DNS and +TLS termination. Our domains are registered with Namecheap. [slash-docs]: https://studentrobotics.org/docs [reverse-proxy]: https://github.com/srobo/reverse-proxy +[infrastructure]: https://github.com/srobo/infrastructure ### Competitor Services From 11ae1536319592634c1eb86069692bf3d39c2f5a Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 18:59:22 +0000 Subject: [PATCH 05/12] Clarify what happens on GitHub It's more than just {hard,soft}ware development. --- docs/infrastructure/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 84bd57c9..990bc2c0 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -40,7 +40,8 @@ API for use on the website. ## Development: GitHub -Our hardware and software development takes place on GitHub, within our +A lot of our collaborative work (including hardware and software development, as +well as general task management) takes place [on GitHub][git-and-github], within our [`srobo`](https://github.com/srobo) organisation. We also have a separate [`srobo-legacy`](https://github.com/srobo-legacy) @@ -48,6 +49,7 @@ organisation which contains some archived git repositories that pre-date our use of GitHub. Moving these over to the main organisation and de-duplicating the repositories is an [ongoing project][legacy-repository-migration]. +[git-and-github]: ../volunteering/git-and-github.md [legacy-repository-migration]: https://github.com/srobo/tasks/issues/179 ## Email, Documents: Google From 562bb9de57416300cf5122075093f05601d1f0c4 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 19:49:35 +0000 Subject: [PATCH 06/12] G-Suite has a new name now Co-authored-by: Dan Trickey --- docs/infrastructure/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 990bc2c0..4a4b315a 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -55,7 +55,7 @@ repositories is an [ongoing project][legacy-repository-migration]. ## Email, Documents: Google For our email (`@studentrobotics.org`) accounts as well as document sharing we -use Google's G-Suite. Google Groups are used for various mailing lists. +use Google Workspace. Google Groups are used for various mailing lists. ## External mailing lists: Mailchimp From 30a43012838813730a91a62d5c14c3af6b92e608 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 19:49:48 +0000 Subject: [PATCH 07/12] Fix typo Co-authored-by: Dan Trickey --- docs/infrastructure/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 4a4b315a..9e94a685 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -27,7 +27,7 @@ TLS termination. Our domains are registered with Namecheap. ### Competitor Services During the competition, there are a number of [hosted services](./competitor-services.md) -which the competitors use. These have thier own managed configuration and are +which the competitors use. These have their own managed configuration and are typically hosted for the duration of the competition "year" only. ### Competition Services From db3b5b3c07fd5933c2fc4040c8ba53b99ddea58c Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 19:51:28 +0000 Subject: [PATCH 08/12] Italicise term which is in our glossary Co-authored-by: Dan Trickey --- docs/infrastructure/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 9e94a685..13e8cbad 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -28,7 +28,7 @@ TLS termination. Our domains are registered with Namecheap. During the competition, there are a number of [hosted services](./competitor-services.md) which the competitors use. These have their own managed configuration and are -typically hosted for the duration of the competition "year" only. +typically hosted for the duration of the *competition year* only. ### Competition Services From 24fe613712cbad13a58da8fedcec70ab48797726 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 19:56:08 +0000 Subject: [PATCH 09/12] Fix typo --- docs/infrastructure/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 13e8cbad..d3633851 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -1,6 +1,6 @@ # Overview -Student Robotics has a variety of infrastrcture in order to support its mission. +Student Robotics has a variety of infrastructure in order to support its mission. This document aims to provide an outline of the general structure. Currently our infrastructure as a whole does not have a designed owner, instead From b27fb92c28382981b00d5c86cc2925d1debcd0b6 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 20:09:43 +0000 Subject: [PATCH 10/12] Tweak wording Co-authored-by: Dan Trickey --- docs/infrastructure/competitor-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/infrastructure/competitor-services.md b/docs/infrastructure/competitor-services.md index 85dea35b..2d225eba 100644 --- a/docs/infrastructure/competitor-services.md +++ b/docs/infrastructure/competitor-services.md @@ -11,7 +11,7 @@ The services typically include: **Forums** : A space which the competitors can use to chat with each other and with mentors and to ask for help with developing their robots. - Historically we have used [PHPBB](https://phpbb.com), though for SR2021 we + Historically we have used [PHPBB](https://phpbb.com), although for SR2021 we have moved to using Discord with a bot to [gate entry](discord-gated-entry). **[IDE](https://github.com/srobo/srobo-ide/)** From 247fd4e3923ce270a94ff6e51f74576dcabafd46 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 13 Feb 2021 20:27:10 +0000 Subject: [PATCH 11/12] Provide a bit more detail about our mailing lists This will need review as part of https://github.com/srobo/runbook/issues/71, though is hopefully useful enough for now. --- docs/infrastructure/README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index d3633851..9f530b96 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -57,6 +57,16 @@ repositories is an [ongoing project][legacy-repository-migration]. For our email (`@studentrobotics.org`) accounts as well as document sharing we use Google Workspace. Google Groups are used for various mailing lists. -## External mailing lists: Mailchimp +## Mailing lists -For sending some batch emails we use Mailchimp. +For sending some batch emails we use Mailchimp and Google Groups. + +For many of our mailing lists we compose the emails in the form of pull requests +to repositories on GitHub, enabling review & feedback before sending as well as +providing a history which acts as a wealth of templates for sending similar +emails in the future. + +Some such repositories are: + +* [team-emails](https://github.com/srobo/team-emails/): Emails to competitor teams +* [volunteer-emails](https://github.com/srobo/volunteer-emails/): Emails to volunteers from other volunteers From 1026b4d4501596a9071cfaecb4cdd8a8586b38c8 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 18 Sep 2021 11:11:01 +0100 Subject: [PATCH 12/12] Acknowledge the Infrastructure Team At some point we'll need to work out how & where to outline exactly who is responsible for what, but I'm opting not to do that for now. --- docs/infrastructure/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md index 9f530b96..16bbbcab 100644 --- a/docs/infrastructure/README.md +++ b/docs/infrastructure/README.md @@ -7,6 +7,11 @@ Currently our infrastructure as a whole does not have a designed owner, instead individual pieces are looked after by volunteer Teams or just by volunteers who have historically maintained them. +Since September 2021 SR has had an Infrastructure Team which is responsible for +maintaining the common aspects of the organisation's infrastructure. That team's +remit has signficant overlap with the services mentioned in this section, though +there are things mentioned here which other teams are responsible for. + ## Website Our website consists of a main public facing site at https://studentrobotics.org