Setup documentation incomplete

[dansan]

Bug:

When following the documentation on https://docs.schul-cloud.org/display/SCDOK/Setup I end up with an incomplete setup.

Reproduce:

I am installing this on a Debian Buster system but follow the instructions for Windows 10.

• The instructions in Server & Client → Variante 1: Windows 10 lokal are OK.
• The instructions in Kalender however are not. The Git repository doesn't even exist anymore. The missing calendar service leads to a HTTP 500 when creating a calendar entry ({ name: 'GeneralError', message: 'Error: connect ECONNREFUSED 127.0.0.1:3000', code: 500, ...} |POST /calendar/events/ 500 166.730 ms - -`).
• I haven't tested the file service yet, so I cannot comment on that.
• The section Content has a link Content Service which leads to https://docs.schul-cloud.org/display/SCDOK/Content+Service where the documentation doesn't fit the files in the git repositories. In section Content Server anpassen (sc-content ordner) it is said to adapt config\development.json, but there is no line 9 with mongodb in that file. There is also no file search.service.js in any of the previously referenced git repositories. The missing content service leads to an error on the landing page.
• The page https://schul-cloud.gitbook.io/web/quickstart ha a section Setup with two dead links.

Consequence 1 of this bug: problems for contributers

As a result of the incomplete or outdated documentation it's not possible to get a proper schul-cloud installation. Being able to setup a software project is however an important prerequisite for a successful open source software project. I cannot imagine contributing to this, if I cannot even get a working local setup. The Jira bug tracker doesn't let unregistered users create issues, or I would have reported this there. That is IMHO also a problem.

Consequence 2 of this bug: problems for schools / school träger

From the documentation I think the HPI Schul-Cloud is great software, and I recommended my school and school träger to use it, however the current phase is open only for MINT schools. So I'd setup it up on our own servers for now - but that's not possible with the broken documentation. This situation will inevitably lead us to use either Itslearning or Moodle, although I'd rather prefer the HPI Schul-Cloud.

Fix:

Make it be possible to create local, complete HPI schul-cloud installation, by following a step-by-step guide.

Hints:

• If there are legal issues with logos and other (creative) content, either make those CC or replace them in the public git repositories with dummies.
• It is not necessary to end up with a full blown Kubernetes installation. The instructions should only be enough to create a setup in a single (virtual) machine.
• To continuously check the documentation, create a CI/CD job that applies those instructions (in the form of a ... script) to create the complete installation and run a few simple integration tests.
  • I will gladly create this for you (for example as a Github action or in Travis CI), if the documentation is in a state that lets me do this.

[janrenz]

Hi, we are in the process of optimizing of updating our docs. However, the docs is meant for a local dev setup and not for production, where we prefer K8s. Are you aiming for a dev system a for a version to use in prod? PLease feel free to contact me directly at jan.renz@hpi.de

[dansan]

Hi, we are in the process of optimizing of updating our docs.

That's great!

However, the docs is meant for a local dev setup and not for production, where we prefer K8s. Are you aiming for a dev system a for a version to use in prod?

My original intention was to create an installation for interested members of the schools of my children, so their teachers can evaluate the software. If they reacted positively, we'd ask their schools → school träger to get a production instance in the HPI cloud. (As that process is somewhat slow, the test-instance would have been the faster test-solution.) The other reason is that the schools already have a production IDM (UCS@school), Nextcloud, OX etc. and we wanted to test the integration with the HPI-Schulcloud.