sysadm docs: Move relevant and public doc from intranet to swh-docs

After discussion the following structure emerged as proposal for the sysadm pages. After the sprint, the arborescence evolved a bit but the gist of it remains. We want to migrate the existing intranet pages to the sphinx instance.

A new page [1] to add the documentation site. This could be publicly linked from the main page [2] (or not). This will be publicly exposed as other repositories already exposed the same kind of information anyway (source code repositories, puppet, ...).

• [1] https://docs.softwareheritage.org/sysadm/

• [2] https://docs.softwareheritage.org/

• Getting started

  • Puppet setup
    • Making my first change in puppet
    • How to manage third-party modules
    • How to deploy a puppet change
  • Check puppet manifests with vagranta
  • Provision new vms
  • Access to the Credential store
  • link to the phabricator tuto in devel doc
  • ...

• How to

  • Debian packaging (could be cross-linked maybe)
  • Database upgrade
  • Database deployment
  • Deploy a new swh module in staging/production
  • Upgrade swh service
  • Deploying a lister
  • Keycloak
  • Connect to a database
  • Onboarding
  • Outboarding
  • Configure the vpn

• Explanation

  • Infrastructure
    • Production
    • Staging environment
  • Network configuration
  • Source of truth -> Inventory

Pros/cons

pros

• code review ahead of time available (one could always skip it if they don't want to)
• tool unification (sphinx rst, git, ...)

cons

No cons that I can see (well the migration per say but that can be done incrementally :)

Remaining pages to redispatch eventually

• Backups
• Database inventory
• IDRAC (credentials moved to credential store first)
• Jenkins -> actually to devel docs
• IRC
• Pglogical replication
• ...

---

Migrated from T3154 (view on Phabricator)

marked this issue as related to swh/devel/swh-docs#3035

added Documentation System administration priority:Normal labels

changed the description

changed the description

changed the description

The sysadm team is ok on this [1]

And like i mention in the crash ticket [2], moving to this scheme brings another pros to the party, making the docs access more resilient.

• [1]

12:34 <+olasd> in any case, I think I've voiced my concerns already. I don't like the idea of moving away from the wiki(s) to something with a much higher barrier to contribution (sphinx + restructured text + code review + git), but the unification and restructuring of docs probably outweighs this concern
12:35 <+olasd> and in that sense I'me fine with the proposal
12:36 <+olasd> (and the thing I'd want us to move towards doesn't exist yet, so...)

(quoting here because as usual, the arguments were nicely put and worth mentioning)

• [2] #3444 (closed)

mentioned in commit swh/devel/swh-docs@8befc797

mentioned in commit swh/infra/ci-cd/swh-jenkins-jobs@e63a638a

mentioned in commit swh/devel/swh-docs@baf94ff6

mentioned in commit swh/devel/swh-docs@80c1b00e

mentioned in commit swh/devel/swh-docs@449f7ad4

@olasd , @ardumont and @vsellier : I think that we can gently resolve this task.

Thank you for a very fruitful sprint[1]!

• [1] https://hedgedoc.softwareheritage.org/2021-october-documentation-sprint?edit

mentioned in commit swh/devel/swh-docs@40e75f11

changed title from proposal: sysadm docs: Move relevant and public doc from intranet to swh-docs to sysadm docs: Move relevant and public doc from intranet to swh-docs

added state:wip label

We have followed the plan on the hedgedoc (in the last comment). Just realized we haven't decided if the support-tools should be in sys-admin dimension, so I'm adding this to this task to decide.

section: Support services

• Reference: Overview of support services
  • HedgeDoc from https://wiki.softwareheritage.org/wiki/HedgeDoc
  • IRC from https://wiki.softwareheritage.org/wiki/IRC -> user
  • Phabricator from https://wiki.softwareheritage.org/wiki/Phabricator
  • ? https://wiki.softwareheritage.org/wiki/Phabricator_callsign_naming_convention
  • new gitlab?
• Reference: Jenkins architecture
  • from https://wiki.softwareheritage.org/wiki/Jenkins

Makes sense to me to add them in sysadm. Also, jsyk, currently, the support-services stub files are already present in the sysadm instance, remains to to fill in the blank at some point.

mentioned in commit swh/devel/swh-docs@884a89a7

mentioned in commit swh/devel/swh-docs@50375fc1

2 more pages migrated (published and redirect installed in the intranet):

• https://docs.softwareheritage.org/sysadm/user-management/onboarding.html
• https://docs.softwareheritage.org/sysadm/user-management/outboarding.html

(which i used to outboard hakb \o/, i believe that's the first time I actually outboard someone, i usually do the onboarding ;)

mentioned in commit swh/devel/swh-docs@46e6ad33

mentioned in commit swh/devel/swh-docs@0bfb31c9

mentioned in commit swh/devel/swh-docs@efc4316b

mentioned in commit swh/devel/swh-docs@c4a1d1dc

changed the description

mentioned in commit swh/devel/swh-docs@4e9e5ce0

changed the description

mentioned in commit swh/devel/swh-docs@8ab8240d

marked the checklist item Database upgrade as completed

mentioned in commit swh/devel/swh-docs@76425302

mentioned in commit swh/devel/swh-docs@29eb1fb8

changed the description

mentioned in commit swh/devel/swh-docs@c7efdcff

marked the checklist item Jenkins -> actually to devel docs as completed

marked the checklist item Puppet setup as completed

changed the description

mentioned in commit swh/devel/swh-docs@e6b0c501

mentioned in commit swh/devel/swh-docs@7124c460

mentioned in commit swh/devel/swh-docs@a9918626

changed the description

marked the checklist item Configure the vpn as completed

All existing sysadm pages have been migration from the wiki and from the intranet to the docs.softwareheritage.org/sysadm pages. The redirection have also been configured to those pages.

So this can be closed now.

removed state:wip label

closed