Table of content:

• Introduction
  • Issues & error reporting
• Installation
  • Bare-metal installation
    • Installation on CentOS
  • Installation using Docker
  • Setup postgres and extensions
  • Networking using docker
  • Create and update functionality on production DB
    • Populate DB with user data
    • Update

Introduction

nFIESTA system is server-side database application intended to be run on Linux and PostgreSQL. Assistance of server / database administrator may be necessary during the installation.

Many ways how to install nFIESTA exist, optimal solution may depends on factors like: server admin preferences, OS, HW, network, virtualization, security. For server admin, it is either necessary to get familiar with used technologies (PostgreSQL, extensions, permissions / access control) and once get oriented, preferred way how to arrange things will emerge.

Users can interact with the system with client e.g. QGIS (install-able on Windows, macOS or Linux). See Minimal Working Example.

Issues & error reporting

In case of troubles, please see a list of issues with label Installation. If your are facing new issue, please do not hesitate to create new one.

Installation

For production, it is recommended to use Linux bare-metal installation. For development / testing environment, it is also possible to use Windows 10 or Linux with virtualization – preferable Docker or WSL (Windows Subsystem for Linux). CI/CD pipelines are running on Docker container, so this way is proven any time automated tests are triggered.

graph TD;
  S{"What is my <br> use-case?"}
  S --> |produciton<br>server | Production[Installation on<br>bare-metal]
  S --> |development<br>environment| devenv[Installation using<br>Docker]
  Production --> Linux[Linux running]
  devenv --> Linux
  Linux --> PG_pro["setup postgres and extensions<br>setup production DB"]
  Linux --> PG_dev["setup postgres and extensions<br>run automated tests"]
  PG_pro --> ETL["ETL: populate DB with data"]
  ETL --> NET["configure network<br>on server"]
  PG_dev --> NET_dev["configure network<br>in dev. env. (docker)"]
  NET --> nFIESTA["use nFIESTA!"]
  NET_dev --> nFIESTA_dev["run Minimal Working Example <br> improve nFIESTA!"]
  click nFIESTA_dev "https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/Minimal-Working-Example"
  click devenv "https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/Installation#installation-using-docker"
  click NET_dev "https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/Installation#networking-using-docker"
  click Production "https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/Installation#installation-on-bare-metal"
  click PG_pro "https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/Installation#create-and-update-functionality-on-production-db"
  click PG_dev "https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/Installation#setup-postgres-and-extensions"
  click ETL "https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/Installation#populate-db-with-user-data"

Bare-metal installation

WARNING: nFIESTA is working only with PostgreSQL 12 or later.

Following general instructions for manual installation (bare-metal) should be similar for any Linux. Please, see specific commands used for automatic installation on Debian Buster using Docker. You can find corresponding comments in Dockerfile:

# fully upgrade system
# set locales to be able to use UTF-8
# create your linux user (we will use user vagrant) and set password
# set up sudo, add your user to sudoers group and allow to act as root and postgres user without asking password
# install: make, gcc, git, wget, gnupg, ca-certificates
# add [pgdg](https://www.postgresql.org/download/linux/debian/) repository
# install latest postgres & postgis, corresponding postgresql-server-dev, plpython3 and python3-numpy

Installation on CentOS

See page Installation on CentOS.

Installation using Docker

Install Docker on your computer:

• Windows 10 build 18917 or higher (not tested): WSL2 (see https://devblogs.microsoft.com/commandline/announcing-wsl-2/)
• Windows 10 other: WSL1 or Docker for windows – see https://docs.docker.com/docker-for-windows/install/ (Linux containers)
• Linux: see https://docs.docker.com/install/linux/docker-ce/ubuntu/

Instructions for using Docker can be found in README.md in repository nfiesta_devenv.

Setup postgres and extensions

Folow .gitlab-ci.yml:

# turn off JIT
# start postgres
# create DB user (preferably with same name as Linux user to bypass password provision)
# build install and test extension [htc](https://gitlab.com/nfiesta/nfiesta_htc)
# run automated tests
# install and test extension [nfiesta](https://gitlab.com/nfiesta/nfiesta_pg)
# run automated tests

WARNING: it is necessary to distiguish well commands with and without sudo. Specially running automated tests should be done without sudo:

make installcheck

in other case workaround might be necessary (see #35 (comment 286013526)).

REMARKS:

• build extension – means compile shared objects
• install extensin – means copy extension files (.control file and updatescripts) to PostgreSQL system directory.
• create extension – SQL command "CREATE EXTENSION ... ;" will run updatescripts from previous step and register objects belonging to the extensionj in DB
• run automated tests – optional step, it will create DB contrib_regression, run tests from sql directory and compare results with expected directory. Command needs to be run with PostgreSQL superuser (to be able to drop and recreate contrib_regression database).

Networking using docker

If you would like to connect from outside of container (e.g. with QGIS) to database inside container, it is necessary to do some additional steps:

Install your favorite editor (vim for example):

sudo apt update
sudo apt install vim

Open /etc/postgresql/12/main/postgresql.conf and set

listen_addresses = '*'

Open /etc/postgresql/12/main/pg_hba.conf and add line

host	all	all	172.17.0.1/32 (may be different IP depending on Docker networking)	md5

Rstart server with

sudo service postgresql restart.

Set our user password (for md5 authentication)

alter user vagrant with encrypted password 'vagrant';

Create and update functionality on production DB

You can create special new DB for nFIESTA (necessary to connect to postgresql DB and create DB from there)

CREATE DATABASE nfiesta;

or you can use some existing DB.

Last step is to create DB objects inside you running (production) DB. You can do it by commands:

CREATE EXTENSION postgis;
CREATE EXTENSION plpython3u;
CREATE EXTENSION htc;
CREATE SCHEMA analytical;
CREATE EXTENSION nfiesta SCHEMA analytical;

This will create schema 'analytical' (you can choose any other schema name to meet your needs) where all nFIESTA objects will be created. Purpose of using special schema (namespace) is isolating nFIESTA objects.

Populate DB with user data

In previous steps you created functionality and schema (DB) in your desired database and schema (namespace). There will be no data except three tables (c_estimate_type, c_phase_estimate_type, c_aux_phase_type) which are so called "static" or "configuration" and goes with extension itself.

Next you would like to fill your production with your data (not testing data). You have to do that with ETL: https://gitlab.com/nfiesta/nfiesta_pg/-/wikis/ETL

Update

Update functionality to newer version on production DB with:

# get fresh source code (new update-scripts)
git pull
sudo make install

ALTER EXTENSION nfiesta UPDATE TO ...;