Skip to content

Latest commit

 

History

History
193 lines (141 loc) · 8.84 KB

multi-instance_config.md

File metadata and controls

193 lines (141 loc) · 8.84 KB

Collec-science multi-instance config [CS-MI]

Proc steps

_____Note 0
___Create multi-instance tree structure
_____CS-MI tree example
____Extract keys and values
_____ini file structure
___Enable multi-instance mode
___Configure databases and credentials
____Start from scratch
____Duplicate existing database
___Configure multi-instance.conf
___Additional instances

Note 0

A working collec-science should be running on the system prior to creating a collec instance. For further information see the collec science install guide and the installation procedure. The mechanism of multi-instance functionality is presented in the chapter 2.2.5 Configurer le dossier d'installation.

Create multi-instance tree structure

CS-MI tree example
/
|-- var
|   |-- www
|   |   |-- collec-science
+   |   |   |-- collec ( -> /path/to/collec-lastver)
    +   |   |   |-- param
	+   |   |   |--param.inc.php
	    |   |   |
	    |   +   |
	    |       +
	    |
	    |-- bin* ( -> collec)
	    |
	    |-- first-instance
	    |   |-- bin* ( -> ../bin)
	    |   \-- param.ini
	    |
	    |-- second-instance
	    |   |-- bin* ( -> ../bin)
	    |   \-- param.ini
	    |
	    +

-> <symbolic link>
+ additional content

Create the structure

cd /path/to/collec-science
sudo ln -s /path/to/collec-lastver collec collec-lastver can reside in collec-science folder
sudo ln -s collec bin
sudo mkdir first-instance this is the instance folder (see the tree example)
sudo ln -s ../bin first-instance/bin

Extract keys and values

ini file structure

Comments should be prefixed with semicolon character
info @ php.net

Here below there are 4 variables. The value of #var is 222. Strings containing non-alphanumeric characters should be enclosed with double-quotes "".

;this is a comment
var = 1
#var = 222 ;https://en.wikipedia.org/wiki/INI_file#Comments_2  
string = this works
string_special = "that's special ;"

A typical minimal CS-MI param.ini file should contain

; First instance param
; Database management
BDD_login = username
BDD_passwd = password
BDD_dsn = "pgsql:host=localhost;dbname=dbname"

; Rights management, logins and log records
GACL_dblogin = username
GACL_dbpasswd = password
GACL_dsn = "pgsql:host=localhost;dbname=dbname"

You can create the first-instance/param.ini file using the above example and skip to the next chapter. However, verify that keys correspond with those in the param.inc.php.dist of the deployed application.

Use the default param.inc.php.dist or already configured param.inc.php file for the new instance. The Minimal configuration (A) option below will create the param.ini file. Choose the optional configuration (B) for more complex instance configuration.

  • Minimal configuration requirements (A)
    sudo sed -e 's/^\$//' -e 's/;$//' -ne '/titre =\|login =\|passwd =\|dsn =/p' -e '1i ; First instance config' collec/param/param.inc.php.dist > first-instance/param.ini

    • 's/^\$//' create keys - remove leading $ characters
    • 's/;$//' remove ending semicolons ;
    • -n '/titre =\|login =\|passwd =\|dsn =/p' keep the keys titre, login, passwd, dsn
    • '1i ; First instance config' add header

  • Including all variables in scope ( optional and instance specific configuration ) (B)
    sudo sed -e 's/^[^$].*$/;&/' -e 's/\$//g' -e 's/;$//' -e 's/^\(paramI\|SMARTY\)/;&/' collec/param/param.inc.php.dist > second-instance/param.ini

    • 's/^[^$].\+$/;&/' or 's/^[^$].*$/;&/' add ini comments
    • 's/\$//g' remove '$' character from variable names
    • 's/;$//' remove semicolons at the end of lines
    • 's/^\(paramI\|SMARTY\)/;&/' comment param.ini and smarty variables

  • Removing php comments - for complete clean-up run
    sudo sed -e 's/^[\*/<>? ][\*/<>? ]*/;/' -e 's/\$//g' -e 's/;$//' -e 's/^\(paramI\|SMARTY\)/;&/' collec/param/param.inc.php.dist > second-instance/param.ini

    • -r 's/^[\*/><? ]+/;/' extended regular expressions version or shorter 's/^[\*/><? ]\+/;/'

Enable multi-instance mode

  1. Change the login credentials in the new first-instance/param.ini.

  2. To enable the multi-instance 'mode' uncomment the lines 144 and 145 in /var/www/collec-science/collec/param/param.inc.php.

//$chemin = substr($_SERVER["DOCUMENT_ROOT"],0, strpos($_SERVER["DOCUMENT_ROOT"],"/bin"));
//$paramIniFile = "$chemin/param.ini";

Configure databases and credentials

Modify the connection details in the created param.ini file to match the configuration in pg_hba.conf and enable the DB access. You might need to change the access rights.

sudo chgrp www-data first-instance/param.ini
sudo chmod 750 first-instance/param.ini

Start from scratch

To start a fresh instance create a new database using the collec-science init script(1). Don't forget to chose a database name suiting the new instance and to configure its access in the postgresql pg_hba.conf

(1) https://github.com/Irstea/collec/blob/03dc3942bb46ddf5c37f114210dbffc641ff22e1/install/deploy_new_instance.sh#L40

Duplicate existing database

If the database contains data which can be used in the new instance :

sudo -u postgres pg_dump myhotdb > path/to/hotDBexport.sql export the existing DB
sudo -u postgres psql -c "CREATE DATABASE newinstancedb OWNER collec;" create a new empty DB

make sure the OWNER has been previously created

sudo -u postgres psql newinstancedb < path/to/hotDBimport.sql and reimport the exported DB

Consider reading the chapter about upgrading the database - 2.6.4 Mise à jour de la structure de la base de données if you're planning to set-up multiple instances based on an updated collec-science version or if the imported database version does not match with the one currently installed on the system.

Configure multi-instance.conf

Create a new first-instance.conf in /etc/apache2/sites-available/

sudo cp -a /etc/apache2/sites-available/collec-science.conf /etc/apache2/sites-available/first-instance.conf

Replace current domain name with the first-instance domain.

# you must change lines 9, 10, 12 and 15, 16 (replace collec.mysociety.com by your fqdn)
https://github.com/Irstea/collec/blob/8ecbf85f555f13fbcc61d8bd07d0d4b3c1692a23/install/apache2/collec-science.conf#L1

<Document root> and <Directory> have to be redefined as well. Modify paths on lines 37, 39 and 45 to
/var/www/collec-science/first-instance/bin.

Enable the new site and reload apache2

sudo a2ensite first-instance
sudo service apache2 reload

The new instance should be up. Check if the site title corresponds with the APPLI_titre set in the instance's param.ini. APPLI_titre is obsolette and has been managed as APPLI_title via database since version 2.1.

Additional instances

Refer to the Proc steps to properly configure all the instance elements.

  • Create a new database
  • Duplicate the instance folder and edit the param.ini according to the connection details
  • Recreate the bin link if necessary
  • Duplicate the first-instance.conf file and change the domain name details

The additional instance should be also up.