Project

General

Profile

Evolution #1571

Improve the "Preparation" page of the installation manual

Added by Guillaume Agnieray 29 days ago. Updated 26 days ago.

Status:
Commentaire
Priority:
Normal
Assignee:
-
Start date:
09/24/2021
Due date:
% Done:

0%

Estimated time:

Description

Instructions on this page are a bit confusing in my opinion.
I will propose a rewrite of the page with the following structure.
This modification will remove information about creating the database on the installation page to make it a preparation step.

  • Setup the webserver
    • On a managed server
    • On your own server
    • On Windows or OS X with XAMPP
  • Create the database
    • On a managed server
    • On your own server
    • On Windows or OS X with XAMPP
  • Copy files and set permissions on the webserver
    • On a managed server
    • On your own server
    • On Windows or OS X with XAMPP
  • Serve Galette to the web or your local network
    • On a managed server
    • On your own server
    • On Windows or OS X with XAMPP
  • Secure Galette
    • On a managed server
    • On your own server
    • On Windows or OS X with XAMPP

Files

#1

Updated by Johan Cwiklinski 28 days ago

I'm not against a rework of the page, and it's also OK to put creation database in preparation steps (keep a link from its original location).

But I do not agree with repetitive managed/own/windows entries: most of the steps are exactly the same on all platforms, and using XAMPP or not is just a detail.

What do you plan to can put in "Setup the webserver"?
Same question for "Secure Galette".

#2

Updated by Guillaume Agnieray 28 days ago

Johan Cwiklinski a écrit (#note-1):

I'm not against a rework of the page, and it's also OK to put creation database in preparation steps (keep a link from its original location).

But I do not agree with repetitive managed/own/windows entries: most of the steps are exactly the same on all platforms, and using XAMPP or not is just a detail.

I totally agree that the finality of the preparation steps are exactly the same on all platforms.
That is the starting point of my suggested modification :)

But the way to achieve them changes significantly from one use case to another.

I also totally agree that using XAMPP or not is just a detail.

But these are the points of views of the experienced and technical users that we are ! :)

From the point of view of an absolutly non technical user using a managed hosting for the first time, or using XAMPP without knowing what is a webserver or a database - and only because it is required to run galette offline on a windows machine (with all the habits that come along : using *.exe files, click and install, etc.) - I don't think these are just details.

The average reader must get lost with all the warnings, notes, references and configuration examples that generally only interest most advanced users in a self hosted configuration.

Otherwise, starting rewriting the page, I quickly realized that the repetitive entries are not very convenient either to follow the process step by step.
So I've splitted each use case on dedicated pages.
Please have a look at my first draw with the patch attached.

The new structure :

*Preparation
  • Prepare installation on a managed hosting
    • Setup the webserver
    • Create the database
    • Copy files and set permissions on the webserver
    • Serve Galette to the web
    • Secure Galette
  • Prepare installation on a self hosting
    • Setup the webserver
    • Create the database
    • Copy files and set permissions on the webserver
    • Serve Galette to the web or your local network
    • Secure Galette
  • Prepare installation on XAMPP
    • Setup the webserver
    • Create the database
    • Copy files and set permissions on the webserver
    • Serve Galette to your local network
    • Secure Galette
    • Additional step : configure XAMPP to send emails

What do you plan to can put in "Setup the webserver"?

  • managed hosting : mainly, I tell that this part is managed by the hosting providers, and that nothing needs to be done in this case except checking that the hosting plan fits the required PHP version for Galette (and tell the user that the version of PHP can generally be modified from the hosting customer account).
  • self hosting : commands to install webserver, database and php
  • XAMPP : install XAMPP

Same question for "Secure Galette".

I'll move there the recommandations about the config and install directories after install. And :

  • managed hosting : enable SSL certificate on the hosting provider customer account, enable https and set apache security headers in .htaccess.
  • self hosting : Let's encrypt, https by default and security headers in the vhost conf (apache and nginx).
  • XAMPP : use self signed certificate, and tell the readers it is not the most secured and convenient solution to put galette online. If used offline, nothing to be done really.
#3

Updated by Johan Cwiklinski 26 days ago

  • Status changed from Nouveau to Commentaire

I took a look at your patch, and I'm still not convinced by the TOC. I'd like to propose an alternative one; but this is not a priority for me right now - even if the doc is really perfectible, it does exists, and many users already have installed Galette using it ;)

Also, I'm going to officially release 0.9.5/0.9.5.1; that kind of rewrite will break all existing translations so it won't be merged to the develop branch before that.

So, I postpone that subject for now; and I'll try to propose an alternative solution.

#4

Updated by Guillaume Agnieray 26 days ago

Sure !
My proposal would have a significative impact on translations.
If it was accepted as is, I'd have provided the french translation as well ;)

#5

Updated by Johan Cwiklinski 26 days ago

Guillaume Agnieray a écrit (#note-4):

If it was accepted as is, I'd have provided the french translation as well ;)

Problem is not languages I can manage myself; but those I can't ;D

Also available in: Atom PDF