HyperLeda: Installation with a provided database server

By default Pleinpot will install the Postgres software (Database Management System), if the right version of the library or programs are not found on your platform (presently Postgres 7.4.2), and it will initialize a new database cluster, start the server (postmaster program), create a database and user, and load the data.

If a Postgres server is yet running on your machine, it would be an advantage to reuse it (reduce the load on the machine). If you still prefer to have a separate new server (this is the simplest) you may still have to instruct Pleinpot to use a free port for the connections with the server, because the default Postgres port may be yet used by the existing server.
Possibly you can also wish to use the HyperLeda database installed in another Pleinpot installation, on the local host or through IP connection (for example to save disk space)... In these cases you must read the following.

There are three levels to consider in what is installed in the current installation:

The postgres software (libraries, client and database backend).
The database server process (postmaster) and the database storage area.
The data stored in the database.

Software installation

Even if you do not install locally the database, the software is required to allow remote IP connections.
The default installation will automatically check if the software is present and decide to install it if it is not found, or if it has not the correct version number (presently 7.4.x). Use the configure program to see what Pleinpot see on your platform (please read the main instructions page to learn about the configure options and environment variables you have to set). You may type:

          cd ${PL_ROOT}
          unix/configure

The output of this program is not very easy to read if you are not used to this kind of procedures, here is what you should look for:

If Postgres is found on the platform:

          checking for psql... /usr/local/bin/psql
          checking for pg_config... pg_config

If Postgres is not found, or is not valid for Pleinpot:
```
          postgresSQL will be installed by Pleinpot
```
which would mean that Pleinpot will download and install Postgres. If Postgres is actually available but not found by Pleinpot, it may probably be that it is not installed in a standard place. Put the directory where the Postgres executables are installed on your PATH. (eg. setenv PATH "$PATH:/home/postgres/bin"). To make the diagnostics, Pleinpot is looking for the programs psql and pg_config, the latter is used to find where the libraries and includes are located. If finally Pleinpot refuses to find your version of Postgres, you may leave it install its own version. The configuration script also check if the Postgres version is compatible with the one used by Pleinpot: Since version 8.8 Pleinpot is using Postgres 7.4.2, it is compatible with 7.4 branch.

In addition, for the WEB interface, the perl scripts are using the modules DBI and DBD-Pg. The configuration program also check for them. If they are available on your machine, but not found by Pleinpot, you may try to understand why, or just leave Pleinpot install its own new version. (As long as Pleinpot is not installed in a standard location, but in a private location it should not be a source of version conflicts).

Server and database

By default Pleinpot will start the database server proccess (called postmaster) on the default port (5432). If this port is already occupied, you may choose another one with the configure option --with-postgres-port=nnnn (where nnn is the number you choosed).

To use a database and a server which is yet running outside of your new Pleinpot installation, you have to give the name of the database, and possibly the port, to the configure program. The following options must be used:

--with-db-external[=ip]
Indicates that the database is provided from another installation, either local (if ip is not given) or remote. If the database is to be accessed through TCP/IP connection, the parameter ip is the IP address of the distant host.
send a mail to leda@univ-lyon1.fr to ask for the IP number of an host you can use
If you use an external database, you must have initialized the database cluster (with the Postgres command initdb), created the database (with createdb) and the users for administration and consultation. Note that if you provide a database cluster, the routine maintenance procedure of Pleinpot will not VACUUM and REINDEX the system tables of the database, this is your responsibility of doing this (this may be critical for performances)
If this option is not given, or if --without-db-external[=ip] is given the database cluster will be owned and managed by Pleinpot.
Furthermore the database cluster is identified by its port number (see --with-postgres-port) and the database by its name (see --with-db-name).
--with-postgres-port=PORT By default Pleinpot will try to connect to the server on port 5432 (the Postgres default). If you provide a server already running on a different port or if you wish that Pleinpot starts a new server and the default port is occupied, you must tell the port number, for example:
```
        unix/configure --with-postgres-port=5433
```
You may see the postgres servers actually running as:
```
        netstat -an | grep PGSQL
```
If you do not know if this option is required, just proceed without. You may return to configure later, if the installation procedure tells you you have to choose a different port.
To change the port number after Pleinpot is installed, do: (i) make hlstop, (ii) unix/configure [options] --with-postgres-port=nnnn (where nnnn is the new port number), (iii) make hlstart.
--with-db-name=NAME Specifies the name NAME of the database. By default or if the option is not given, Pleinpot will assume the name hl.

There is a last option concerning the database cluster: --enable-postgres-ip-connect The database server will be started with the option to accept PCP/IP connections from clients. To allow connections from the outside world, your host must acccept connections on the Postgres port, and to control these connections you may edit the files pg_hba.conf and/or pg_ident.conf. To change this option after Pleinpot is installed, do: (i) make hlstop, (ii) unix/configure [options] --enable-postgres-ip-connect (or disable), (iii) make hlstart. This option is incompatible with --with-db-external[=ip]. Before you build Pleinpot with a provided database server, you must (1) start the postmaster and (2) create the database with granting the access right. Data administration If your current installation of Pleinpot starts the database server process and own the database, the administration of the HyperLeda database will be always automatically done. If instead you are using a provided server you may also choose to use the HyperLeda database administrated by another installation of Pleinpot. It may be particularly interesting when you are running different installations of Pleinpot in order to save disk space. The configure option to specify how data must be administrated and accessed are: --with-hyperleda-administrator=DBADMI The username DBADMI, or by default Phladmi will be used for administration requests. If you do not give this option, or give --without-hyperleda-administrator, the effect depends on whether Pleinpot owns the cluster or not (see option --with-db-external). If Pleinpot owns the database cluster, the user Phladmi will be assumed, otherwise Pleinpot will not administrate the data. This latter case, when Pleinpot does not administrate the data is the normal behaviour when using a remote database through IP access or when the current instance of Pleinpot re-use the database build by another instance running on the machine. --with-hyperleda-user If you do not give this option, Pleinpot will use the username Phypcat for consultation requests. HyperLeda Questions: leda@univ-lyon1.fr