[Documentation] Rework Upgrade Guide and add Section "Upgrade from LanSuite v4.2 to v5.0"

[andygrunwald]

What is this PR doing?

I recently upgraded an older LanSuite instance.

For this, I had first-hand experience on what steps are necessary to upgrade.

This Pull Request reworks the Upgrade Guide a bit:

• Add specific instructions on v4.2 to v5.0
• Made it a bit more concise (e.g. i think it is not our responsibility to inform the admin if he/she should inform their users)
• Removed the git master option - IMO, this should only be done by users who know what they are doing

Which issue(s) this PR fixes:

None

Checklist

• CHANGELOG.md entry - Not needed
• Documentation update

[M4LuZ]

@mrflobow contacted me because he apparently had issues in updating his dev environment while following the guide.
(which indicates that some more work is apparently needed)
I've asked him to post the issues and questions here, so it can be added.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[M4LuZ]

While we wait:

Made it a bit more concise (e.g. i think it is not our responsibility to inform the admin if he/she should inform their users)

The guide lists all steps that should be done to avoid issues before/during/after the upgrade.
And lack of communication / planning is one very often seen.

So I would leave it in.
I'm confident that readers can figure out for themselves if they need to do that or not

[mrflobow]

Hello Andy and Maluz

I would like to get the DevSetup running I tried the steps on the offical instructions but I'm not able to get it running.

My comments

DEV Setup?

git clone https://github.com/lansuite/lansuite.git
cd lansuite
# Erstelle eine Konfigurations Datei in ./inc/base/config.php , eine Beispiel Konfiguration kannst du unten entnehmen
touch ./inc/base/config.php
# > Not sure if applicable for dev setup
chmod 0777 ./inc/base/config.php
# > Would case 10000 commit files.
chmod -R 0777 ./ext_inc/
# Added step to get mysql setting
cp docker/mysql.env.dist docker/mysql.env
#> Image must be build otherwise its taking an image 3years old with php7.x
docker build . -t lansuite/lansuite --platform linux/amd64
#> Add -d for background
docker-compose up -d
docker-compose run php composer install

# Add
# Page is reachable add http://localhost:8080 

Sample should match with mysql.env for lazy devs :D

[lansuite]
version=Nightly
default_design=simple
chmod_dir=777
chmod_file=666
debugmode=0

[database]
server=mysql
user=lansuite
passwd=dev1234
database=lansuite
prefix=ls_
charset=utf8

Not sure what todo next.

[sonarcloud]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[M4LuZ]

What is the rationale of removing this?
Unless file operations are done in scope of the webserver user, ownership may be wrong, so may be access rights

[andygrunwald]

The installation script checks the file permission and warns the user. Thats why I don't think it should be a manual step. On top of this it doesn't say

• which file permission to check
• what are the required file permission

Hence it is providing limited value.

[M4LuZ]

The installation script is not executed as part of the instructions.
So that does not help.
If I remember correctly it also does not tell what should be set, just that permissions are not sufficient.

I do agree with you that it would be better to detail what permissions should be set.
But that does not mean that the information that this may need to be done should be removed alltogether.

[M4LuZ]

Now looking deeper at the old upgrade instructions:

In der Datei inc/base/config.php den Wert von Configured auf 0 zurücksetzen
Nun die Webseite aufrufen. Es erscheint die Installation. Diese ganz normal durchklicken und die Datenbank Zugangsdaten eingeben jedcoh NICHT DAS HÄCKCHEN setzen, dass die DB löscht. Die Installation sollte nun automatisch updaten.

Huh. If that works it covers most of what is needed.

[M4LuZ]

Do we need to provide a conversion logic for existing DB entries in IPv4?

[andygrunwald]

This part is removed. As far a I know this is not needed anymore. I have updated my system already and never did such a conversion

[M4LuZ]

Had a look. It appears that old column values are dropped with the related column change.
So there is nothing to convert once the DB update is done.
Not sure if feature or bug :/

[andygrunwald]

Storing the ipv4 addresses without a proper reason is not gdpr confirm either. In this case, I don't think we need to fix this.

On top of this, people have a database backup. If they really need the IPv4 addresses, there is a possibility to add those.

[M4LuZ]

I would suggest to add a note that this happens and leave it with that.
log is (supposed to be) cleaned up regularly via cron2, so these should disappear in reasonable time anyways.

Ad GDPR:
The proper reason is legimimate interest and is actually fine as long as it is disclosed transparently (where we fail at the moment).
(Apparently there are also some court cases in DE/AU where dynamic IPs were not considered personal information, but as so often it is not clear-cut)

[andygrunwald]

Done in 929e27a

[andygrunwald]

@mrflobow I had a quick check on your journey. It seem to be relate to the MySQL database.
You start your docker setup in background via

#> Add -d for background
docker-compose up -d

Can we verify that MySQL was booted up successfully?
Or that the user

user=lansuite
passwd=dev1234

has permission to create a database?

@M4LuZ The comment by @mrflobow is related to a development installation, not on how to upgrade an existing LanSuite installation. Hence, I would suggest to open up a new ticket on this.

[M4LuZ]

@M4LuZ The comment by @mrflobow is related to a development installation, not on how to upgrade an existing LanSuite installation. Hence, I would suggest to open up a new ticket on this.

That's fine by me.

@mrflobow: That issue looks very much like what I noticed with #871 / #872
So maybe the fix is just a git pull away... ;)

[andygrunwald]

@M4LuZ Which items are missing in this PR?

[M4LuZ]

I've resolved the conversations finished and have only these two remaining:

• Suggestion: Add a note that IP entries are removed from logs
• Test if menu-writing and permissions are checked / fixed when setting configured=0 as suggested in legacy upgrade guide. But this can be done within [Upgrade docs] Re-Run menu generation #893 to get this closed

[sonarcloud]

Quality Gate passed

Issues
0 New issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[mrflobow]

@andygrunwald related to install, tried it also in a vm with all service installed . The issue is the use of old db class and new which leads to fail in the wizard . Maybe also due to some config bug Maluz fixed. Yes this is unrelated to upgrade , the inital install fails neither its docker or vm.

I believe it's worth to look in a separate bug into it.
At the moment have not the time to invest further.