Galette » Documentation

Galette installation is a web based process. :doc:`Once preparation steps are done <preparation/index>`, go to http://localhost/galette. :doc:`Update process <update>` is documented separately.

If all :ref:`the preparation steps <preparation>` have been properly followed, directories ACLs should be correct. Otherwise, please review the files ACLs section in the preparation steps before refreshing the page in your browser.

First of all, make sure the database exists, and you have all the required information you must have gathered during :doc:`the preparation steps <preparation/index>` :

* database host name

preparation/index.rst

.. include:: /globals.rst

.. _preparation:

***********

Preparation

***********

Before launching Galette installation, you have to follow some steps first, and gather the database settings that you will be asked for during the installation process.

Dependending wether you want to install Galette on a managed hosting, a dedicated server, a virtual private server (VPS), or "locally" on a computer, the commands or tools to use will differ.

But things to prepare are always the same, in the following order :

#. Setup the webserver

#. Create the database

#. Copy files and set permissions on the webserver

#. "Serve" Galette

#. Secure Galette

To achieve these preparation steps, instructions will be given for the following use cases.

+-------------------------------+----------------------------------------------------------------------------------------+

| Use case | Description |

+===============================+========================================================================================+

| On managed hostings | Most common use case to use your instance online with a public domain name. |

+-------------------------------+----------------------------------------------------------------------------------------+

| On self hostings | On a dedicated server, a VPS, or a computer running a Unix compatible operating system.|

| | If you are an advanced user, for a full control of an online instance, |

| | for testing and developping purposes, |

| | or if you want to use Galette locally) |

+-------------------------------+----------------------------------------------------------------------------------------+

| With XAMPP on Windows or OS X | Most often for testing purposes and developping purposes, |

| | or if you want to quickly setup and use Galette locally on these platforms. |

+-------------------------------+----------------------------------------------------------------------------------------+

Please choose one of the use case corresponding to your situation before proceeding with installation :

.. toctree::

:maxdepth: 2

managed_hosting.rst

self_hosting.rst

xampp_hosting.rst

.. _managed_hosting:

*****************************************

Prepare installation on a managed hosting

*****************************************

.. note::

**The following instructions target users who which install Galette on a managed hosting.**

If your are looking to install Galette on a managed hosting, please visit :ref:`managed_hosting`

If your are looking to install Galette with XAMPP, please visit :ref:`installationwindows`

Setup the webserver

===================

On managed hostings, no webserver setup is properly required. Everything has been managed by your hosting provider.

Just ensure that your offer fullfills :doc:`Galettes's requirements regarding PHP <../prerequis>`.

**Every hosting company allows to choose different versions of PHP to run on the server. If necessary, check and ajust PHP version from your customer account.**

.. note::

OVH hosting compay offers to `change the version of PHP from your customer account or by modifying the .ovhconfig file on your storage space <https://docs.ovh.com/gb/en/hosting/how_to_configure_php_on_your_ovh_web_hosting_package_2014/#step-2-change-the-php-version-on-your-web-hosting-plan>`_.

.. warning::

Many users reported to have display images or emargement list issues on OVH hosts (this is not true with their latest hosting plans). If you face this issue **after installation**, the solution is to edit/create the `.ovhconfig` file at the root of your storage space and edit/add the ``app.engine`` setting with the value ``phpcgi`` :

.. code-block:: shell

app.engine=phpcgi

Create the database

===================

If it is not already used, you hosting provider should already have created a database and given you its settings when you registered the hosting plan.

Otherwise, create a new one from your customer account following your hosting provider documentation.

Don't forget to note the settings of your database :

* database host name

* database user name

* database user password

* database name

* database type (MariaDB/MySQL or PostgreSQL)

Copy files and set permissions on the webserver

===============================================

Some Galette directories need specific rights. The application will need to write in some of them, you have to ensure it will be possible. Here are directories that need a write access:

* `config` [#configdirperms]_,

* `data/attachments`,

* `data/cache`,

* `data/exports`,

* `data/files`,

* `data/imports`,

* `data/logs`,

* `data/photos`,

* `data/tempimages`,

* `data/templates_c`

.. [#configdirperms] write access on ``config`` directory is only needed for Galette installation, we advice you to remove the write access once Galette has been installed :)

.. warning::

A commonly used hack is to give all rights to everyone recursively on the directory (``chmod 777``). This is a very very bad idea from a security point of view. Please do not use that hack, you've been warned ;)

.. warning::

Some archive or FTP softwares may corrupt files... It is strongly adviced if you use windows that you use `7zip <https://www.7-zip.fr>`_ to uncompress and `FileZilla <https://filezilla-project.org/>`_ for TFP transferts.

Once source code has been retrived locally, use :samp:`tar xjvf {galette.tar.bz2}` command under Linux/Unix/MacOS or a graphical tool under Windows.

Just copy the uncompressed directory obtained, and all its sub directories and files, with your FTP client.

.. image:: ../../_styles/static/images/installation/filezilla.jpg

:scale: 50 %

:align: center

Serve Galette to the web

========================

.. versionadded:: 0.9

A quick Galette installation consists in copying a complete directory in the release archive to a location the web server can read. Doing so without defining the right directory in the release archive the webserver must serve to the world, can expose to the web files and directories that should not be available this way.

To prevent that, it is strongly recommended to expose only the ``webroot`` directory. This way, directories outside ``webroot`` stay safe: it is not possible to reach them from the web!

.. note::

Exposing only ``webroot`` directory is the recommended way if you can create virtual hosts on your hosting solution.

And that will certainly not be possible with most of the *free* hosting providers on the market

On managed hostings, the most common thing to do is to use a subdomain for Galette.

If mywebsiteadress.org is your domain name, then www.mywebsiteadress.org is a subdomain.

Traditionaly, www.mywebsiteadress.org is the default URL of your organization's website.

If you don't already use it, then you should be able to reconfigure it from your customer account and set its directory on the server with the `webroot`` folder of Galette, following your hosting provider documentation.

Otherwise, you should be able to create other subdomains.

In order to do that, you need to use your customer account and follow your hosting provider documentation.

Generaly, during the process, you will be asked to choose the directory where to put your website. This is where you must select or give the full path to the ``webroot`` folder of Galette.

.. warning::

1&1 / Ionos users will also have to edit the ``.htaccess`` file in the ``webroot``, and uncomment the ``RewriteBase /`` directive.

Secure Galette

==============

TODO (SSL/HTTP Headers in .htaccess)

.. note::

Write access on ``config`` directory is only needed for Galette installation, we advice you to remove the write access once Galette has been installed :)

You should also delete the ``install`` directory.

.. _self_hosting:

**************************************

Prepare installation on a self hosting

**************************************

.. note::

**The following instructions target users who which to self host Galette on their own server.**

If your are looking to self host Galette on your own server, please visit :ref:`self_hosting`

If your are looking to install Galette with XAMPP, please visit :ref:`installationwindows`

Setup the webserver

===================

If you personaly manage a dedicated server or a VPS, or if you are an advanced Linux user, chances are you already know what you are doing ;)

If you are an average Linux user, here are the required steps to setup and run a local webserver (depending on your distribution, you might have to use the proper commands to install the required packages and (re)start your webserver ; the following commands are given for Debian based distributions).

* Install Apache webserver and PHP

.. code-block:: bash

$ sudo apt install apache2 apache2-utils openssl libapache2-mod-php php-cli php-gd php-curl php-intl php-tidy php-php-gettext php-mbstring php-zip php-xml php-pear php-bcmath

* Enable PHP modules

.. code-block:: bash

$ sudo a2enmod php7.* rewrite headers ssl

* Enable and (Re)start the webserver

.. code-block:: bash

$ sudo systemctl enable apache2

Create the database

===================

These are the settings that you will be asked during the installation of Galette.

* database host name

* database user name

* database user password

* database name

* database type (MariaDB/MySQL or PostgreSQL)

* Install MariaDB or PostgreSQL database

For MariaDB:

.. code-block:: bash

$ sudo apt install mariadb-server mariadb-client php-pdo php-mysql

For PostgreSQL:

.. code-block:: bash

$ sudo apt install mariadb-server mariadb-client php-pdo php-mysql

.. note::

**Never use database root user!**

For security reasons, it is stongly advised to rely on a specific user for Galette database, and give this user only the required accesses on the single Galette database.

For the example, we will use a database named `mygalette` with a user `mygaletteuser` and `mypass` as password.

* MariaDB

.. code-block:: bash

$ mysql -u root -p

mysql> CREATE DATABASE mygalette;

mysql> GRANT ALL ON magalette.* to

->'mygaletteuser'@'localhost' IDENTIFIED BY 'mypass';

* PostgreSQL

.. code-block:: bash

$ su -

# su - postgres

$ createuser -P mygaletteuser

$ createdb -O mygaletteuser mygalette

Those commands may vary, please refer to `MariaDB <https://mariadb.com/kb/en/library/documentation/>`_ or `PostgreSQL <https://docs.postgresqlfr.org>`_ documentations, or use a graphical tool:

* `phpMyAdmin <https://www.phpmyadmin.net>`_ for MariaDB ;

* `phpPgAdmin <http://phppgadmin.sourceforge.net>`_ or `PgAdmin <https://www.pgadmin.org/download/?lang=fr_FR>`_ for PostgreSQL.

Copy files and set permissions on the webserver

===============================================

Some Galette directories need specific rights. The application will need to write in some of them, you have to ensure it will be possible. Here are directories that need a write access:

* `config` [#configdirperms]_,

* `data/attachments`,

* `data/cache`,

* `data/exports`,

* `data/files`,

* `data/imports`,

* `data/logs`,

* `data/photos`,

* `data/tempimages`,

* `data/templates_c`

.. [#configdirperms] write access on ``config`` directory is only needed for Galette installation, we advice you to remove the write access once Galette has been installed :)

.. warning::

A commonly used hack is to give all rights to everyone recursively on the directory (``chmod 777``). This is a very very bad idea from a security point of view. Please do not use that hack, you've been warned ;)

.. _installationunix:

Linux/Unix

^^^^^^^^^^

Installing Galette on Linux implies you have an access to the terminal on the server and required ACLs on directories.

As an example, on `Fedora <https://fedora.org>`_, you will run (as root):

.. code-block:: bash

# cd /var/www/galette/

# chown -R apache:apache config data

Under `Debian <https://debian.org/>`_, we'll replace ``apache:apache`` with ``www-data:www-data``.

On SELinux enabled systems, we'll also add:

.. code-block:: bash

# semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/galette/config(/.*)?'

# semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/galette/data(/.*)?'

# restorecon -R -v /var/www/html/galette/

You will also have to authorize webserver to connect to the network, with a SELinux boolean:

.. code-block:: bash

# setsebool httpd_can_network_connect on

Nginx

^^^^^

`Nginx webserver <https://nginx.com>`_ configuration is different from Apache one (see `Nginx documentation for a more complete explanation <https://www.nginx.com/resources/wiki/start/topics/examples/likeapache-htaccess/>`_).

So you have to convert restriction access files in Nginx configuration, as for example:

.. code-block:: nginx

location ~ /(data|config|lib)/ {

deny all;

}

Serve Galette to the web or your local network

==============================================

.. versionadded:: 0.9

A quick Galette installation consists in copying a complete directory in the release archive to a location the web server can read. Doing so without defining the right directory in the release archive the webserver must serve to the world, can expose to the web files and directories that should not be available this way.

To prevent that, it is strongly recommended to expose only the ``webroot`` directory. This way, directories outside ``webroot`` stay safe: it is not possible to reach them from the web!

Here is a virtual host configuration example for Apache:

.. code-block:: apache

<VirtualHost *:80>

ServerName galette.localhost

DocumentRoot /var/www/galette/galette/webroot/

<Directory /var/www/galette/galette/webroot/>

RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-f

RewriteRule ^(.*)$ index.php [QSA,L]

</IfModule>

</Directory>

</VirtualHost>

For Nginx it would be:

.. code-block:: nginx

server {

listen 80;

listen [::]:80;

server_name galette.localhost;

root /var/www/galette/galette/webroot;

index index.html index.php;

location / {

try_files $uri $uri/ @galette;

}

location @galette {

rewrite ^(.*)$ /index.php last;

}

location ~ \.php$ {

include snippets/fastcgi-php.conf;

# You may have to adapt this path, depending on your distribution.

fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;

}

location ~ /(data|config|lib)/ {

deny all;

}

# Disable content sniffing.

add_header X-Content-Type-Options nosniff;

# Avoid click-jacking.

add_header X-Frame-Options "SAMEORIGIN";

}

Secure Galette

==============

TODO (SSL/HTTP Headers)

.. note::

Write access on ``config`` directory is only needed for Galette installation, we advice you to remove the write access once Galette has been installed :)

You should also delete the ``install`` directory.

.. _installationwindows:

*******************************

Prepare installation with XAMPP

*******************************

.. note::

**The following instructions target users who which to install Galette with XAMPP.**

If your are looking to install Galette on a managed hosting, please visit :ref:`managed_hosting`

If your are looking to self host Galette on your own server, please visit :ref:`self_hosting`

Setup the webserver

===================

Installation described here relies on `XAMPP <https://www.apachefriends.org/download.html>`_.

Screenshots were taken under windows, but things should look similar under OS X.

First of all, download and install the software.

Choose the right download for your operating system and the PHP version officially supported by Galette. During the install process, use the default install path proposed.

.. image:: ../../_styles/static/images/installation/windows/xampp_directory.jpg

:scale: 50 %

:align: center

.. note::

Enabling PHP modules under XAMPP is done in ``xampp/php/php.ini``. Most of the required extensions are already present, but commented (line begins with a ";"). Just edit the file and uncomment the required lines.

**IMPORTANT** : `openssl` extension is missing in the file. To activate it just add the following line to your `php.ini`: ``extension=php_openssl.dll``

Finally, (re)start XAMPP from ``xampp-control``.

Launch the ``xampp-control`` so you can start Apache and MySQL services.

.. image:: ../../_styles/static/images/installation/windows/xampp_control.jpg

:scale: 50 %

:align: center

Create the database

===================

.. note::

**Never use database root user!**

For security reasons, it is stongly advised to rely on a specific user for Galette database, and give this user only the required accesses on the single Galette database.

Default user has no password.

We recommend to use XAMPP shell [ADD SCREENSHOT] to run the following commands.

For the example, we will use a database named `mygalette` with a user `mygaletteuser` and `mypass` as password.

* MariaDB

.. code-block:: bash

$ mysql -u root -p

mysql> CREATE DATABASE mygalette;

mysql> GRANT ALL ON magalette.* to

->'mygaletteuser'@'localhost' IDENTIFIED BY 'mypass';

* PostgreSQL

.. code-block:: bash

$ su -

# su - postgres

$ createuser -P mygaletteuser

$ createdb -O mygaletteuser mygalette

Don't forget to note the settings of your database :

* database host name

* database user name

* database user password

* database name

* database type (MariaDB/MySQL or PostgreSQL)

Copy files and set permissions on the webserver

===============================================

Files must be copied in the htdocs directory.

That's all.

Serve Galette to your local network

===================================

.. versionadded:: 0.9

A quick Galette installation consists in copying a complete directory in the release archive to a location the web server can read. Doing so without defining the right directory in the release archive the webserver must serve to the world, can expose to the web files and directories that should not be available this way.

To prevent that, it is strongly recommended to expose only the ``webroot`` directory. This way, directories outside ``webroot`` stay safe: it is not possible to reach them from the web!

TODO (modifs xampp/apache/conf/extras/vhosts)

Secure Galette

==============

TODO (self signed SSL + general recommandations about security)

.. note::

Write access on ``config`` directory is only needed for Galette installation, we advice you to remove the write access once Galette has been installed :)

You should also delete the ``install`` directory.

Additional step : configure XAMPP to send emails

================================================

TODO (modifs php.ini + sendmail.ini)