# InstallS

## Installation Methods

Minimal system requirements for running a server with BGERP + MariaDB are as follows:

- An RPM-based Linux operating system, preferably CentOS or RHEL (used by samples), is recommended.

- CPU core equal to Intel x86 500MHz; 1GHz recommended;

- 512MB RAM; 1GB recommended.

We recommend that you install in a Docker container as the easiest way to get the system up and running for study. The data can be migrated after to Linux server(s) for regular operation under production load.

### Docker

Installation from a Docker image.

The Docker image uses approximately 1 GB of disk space and contains the latest published Stable Release will all the required components: MariaDB, Java.

| The actual Demo state is applied during the first run if that is not explicitly disabled.

This variant perfectly fits the following purposes:

- Having a first look and playing with the program;

- Running on Windows machines;

- Running in a different environment, e.g. with an already installed MariaDB but with a different/untested version.

Use the following command to remove container:

    docker rm -f bgerp

The running container is available via web-interface. Use NGINX for restricting access from an outside network.

#### Data volumes Inside the Container (Win and *NIX)

In this case all the required data volumes are hidden inside Docker container.

| All the related data is removed together with container upon deletion.

    docker pull bgerp/bgerp && docker run -d --name bgerp --restart unless-stopped -p 9088:9088 bgerp/bgerp && docker logs --follow bgerp

Make sure, that the container is running, wait the message:

    Running BGERP
    Server URL: 'http://localhost:9088', see logs in 'log' directory

#### Data volumes Outside the Container (*NIX only)

    docker pull bgerp/bgerp && docker run -d --name bgerp --restart unless-stopped \
        -v /srv/bgerp/data/mysql:/var/lib/mysql \
        -v /srv/bgerp/data/filestorage:/opt/bgerp/filestorage \
        -v /srv/bgerp/data/backup:/opt/bgerp/backup \
        -v /srv/bgerp/conf:/opt/bgerp/conf \
        -v /srv/bgerp/log:/opt/bgerp/log \
        -p 9088:9088 \
        bgerp/bgerp && docker logs --follow bgerp

| Completely remove all the related data.

    rm -rf /srv/bgerp

#### Run Arguments

By default a Docker container with BGERP has been updated to the latest Master Release and has Demo DB content applied. That might be avoided using arguments for docker run command -e MASTER=no and -e DEMO=no respectively.

#### Deployment Script

Distribution provides a Bash script that runs on Debian/CentOS and performs the following actions:

- Deploys a Docker container with a running instance pf BGERP;

- Configures NGINX reverse proxy with an SSL access.

Prerequisites;

- The following packages have to be pre-installed: docker-ce, nginx, certbot, curl.

- Script needs to be executed via sudo or root

Execution Steps: Step 1. Switch to a working directory, e.g:

    cd /tmp

Step 2. Download the script using curl:

    curl https://github.com/Pingvin235/bgerp/blob/master/srcx/deploy/deploy.sh --output bgerp_deploy.sh

Step 3. Execute the script:

    sudo bash bgerp_deploy.sh <NAME> <PORT>

Where:

- <NAME> - DNS server name used for the instance;

- <PORT> - HTTP port exposed on the localhost.

Example:

    sudo bash bgerp_deploy.sh test.bgerp.org 9001

### Linux

Installation on a Linux server.

#### MariaDB

Any Stable Release of MariaDB 11.4.7 or newer suits for installation.

The previously used Oracle MySQL version 8.0 is still supported for existing installations. But because of performance issues experienced with it, wir strongly recommend to you the Instruction for migration of your existing DB to MariaDB.

You can find MariaDB server in package manager of your Linux distributive, or take it here:

- MariaDB Server

- MariaDB in Docker - in case of simultaneous operation of two DBMS (e.g. during migration)

Once installed, check the mandatory options below in [mariadbd] section in DBMS configuration file (`/etc/my.cnf.d/mariadb-server.cnf` or `/etc/mysql/mariadb.conf.d/50-server.cnf` for Docker version):

    [mariadbd]
    sql-mode=
    innodb_file_per_table=1

| sql-mode must be set exactly to an empty string, as shown in the example above. Add this line if sql-mode option is not defined. In case this string is still missing, DB creation script will take care of correcting and adding it.

And restrict access to database server from different hosts, if you don’t need that:

    bind-address=127.0.0.1,::1

Some additional optimization options, you may need in the future. Please, check their intentions before.

    sort_buffer_size=200M
    innodb_flush_log_at_trx_commit=2
    innodb_buffer_pool_size=2G
    innodb_log_file_size=100M

You will also need the root access to the MariaDB Server at the time of installation (one time action).

#### Java

OpenJDK 21 version is required - is can be installed differently for distributions, as in the example below:

    sudo dnf update
    sudo dnf install -y java-21-openjdk-devel

| Confirm that java, javac and jstack commands are available after installation.

#### Application

All the operations require a root user.

Step 1. Check and install script dependencies:

    sudo dnf update
    sudo dnf install -y wget unzip pwgen

Step 2. Download archive and unpack it:

    wget https://bgerp.org/version/3.0/bgerp.zip -O /tmp/bgerp.zip &&
    unzip /tmp/bgerp.zip -d /opt &&
    chmod 744 /opt/bgerp/*.sh

Step 3. Generate DB password ant add it into files:

    ERP_DB_PWD=`pwgen -y -c 20` && export EPR_DB_PWD &&
    echo "Setting DB password: '$ERP_DB_PWD'" &&
    sed -i "s/GENERATED_PASSWORD/$ERP_DB_PWD/" /opt/bgerp/bgerp.properties &&
    sed -i "s/GENERATED_PASSWORD/'$ERP_DB_PWD'/" /opt/bgerp/db_create.sql

Step 4. Run a DB script to create DB structure:

    mariadb --default-character-set=utf8 -h127.0.0.1 -uroot -p < /opt/bgerp/db_create.sql
    mariadb --default-character-set=utf8 -h127.0.0.1 -ubgerp -p$ERP_DB_PWD bgerp < /opt/bgerp/db_init.sql

Step 5. Optionally apply data from the Demo:

    wget https://demo.bgerp.org/bgerp.sql -O /opt/bgerp/bgerp.sql
    mariadb --default-character-set=utf8 -h127.0.0.1 -uroot -p bgerp < /opt/bgerp/bgerp.sql && rm /opt/bgerp/bgerp.sql

    wget https://demo.bgerp.org/filestorage.zip -O /opt/bgerp/filestorage.zip
    unzip filestorage.zip -d /opt/bgerp/filestorage && rm /opt/bgerp/filestorage.zip

Step 6. If required, adapt the following values in in `bgerp.properties`: DB server host value, HTTP and management ports.

Step 7. If required, adapt JAVA_HOME variable in `setenv.sh`:

    JAVA_HOME=/opt/the_special_java

    # default value
    if [ -z "$JAVA_HOME" ]; then
        JAVA_HOME=/usr
    fi

`java` and `javac` will be expected in `$JAVA_HOME/bin`

Step 8. Use `erp_start.sh` and `erp_stop.sh` for application start and termination. `erp_status.sh` shows the current status of the application. Upon starting, check `log/bgerp.log` and `log/bgerp.out` for errors.

Once running, application will be available via web-interface.

#### Systemd

In order to enable application auto-start upon the system start, use the systemd script. Copy file `bgerp.service` to `/etc/systemd/system/` and execute:

    systemctl daemon-reload
    systemctl enable bgerp

#### NGINX

Typically the application is running in Intranet, access to restricted interfaces from outside as well as SSL may be organized using NGINX.

##### Example

The application is runnuning on internal host erp.int.bitel.ru. Outside on host erp.bitel.ru is available only open interface http://erp.bitel.ru/open The configuration may be typically placed in file `/etc/nginx/conf.d/erp.bitel.ru`

    server {
        server_name             erp.bitel.ru;
        server_name             crm.bitel.ru;
        access_log              /var/log/nginx/erp.bitel.ru.access.log;

        # optionally close access without interface
        #location = / {
        #    return 404;
        #}

        # for opening user interface - add admin|login.do|user
        # for opening user mobile interface - add usermob
        location / {
            client_max_body_size    100m;
            proxy_pass              http://erp.int.bitel.ru/;
            proxy_redirect          http:// https://;
            proxy_set_header        Host $host;
            proxy_set_header        Connection close;
            proxy_set_header        X-Real-IP $remote_addr;
            proxy_read_timeout      300;
            gzip_proxied            any;
        }

        # this part has to be generated first by CertBot:
        # certbot --nginx -d erp.bitel.ru -d crm.bitel.ru
        listen 443 ssl; # managed by Certbot
        listen [::]:443 ssl; # managed by Certbot
        ssl_certificate /etc/letsencrypt/live/erp.bitel.ru/fullchain.pem; # managed by Certbot
        ssl_certificate_key /etc/letsencrypt/live/erp.bitel.ru/privkey.pem; # managed by Certbot
        include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
        ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
    }

    # redirect HTTP to HTTPS
    server {
        listen        80;
        listen        [::]:80;
        server_name   erp.bitel.ru;
        server_name   crm.bitel.ru;
        return 301    https://$host$request_uri;
    }

#### Multiple Instances

In the case when you need to setup multiple app instances on a single server, recommendations is the following:

- create a separated Linux user for the instance, for example inst;

- place the app to the user’s home, `/home/inst/bgerp`;

- name the database as bgerp_inst;

- adjust server.port.http and server.port.admin by adding numeric prefixes, for the second server’s instance it would be 19088 and 12011 respectively;

- for running the instance on server start instead of systemd use cron:

    crontab -e
    # to the opened editor add record
    @reboot /home/inst/bgerp/erp_start.sh

## App

### Status

In menu Administration / App / Status you can see the current status of the running App, which includes on the first place the current version and used memory info.

After has shown DB connections state with a link trace for becoming Java stack traces of connection consumers.

Down on the page is placed App restart button and tables with logs.

In the bottom of the page are placed tools for updating.

#### Update

| If access to the default update server https://bgerp.org is restricted, it is possible to change the URL via configuration. For example in Russia you can use the mirror: https://bghelp.ru/bgerp

The product versioning system is described on our website. By following this guide you will install its current Master or Stable Release.

For subsequent use, it is recommended to update only when the next Stable Release is published, which the application informs you about by a notification in the interface.

| Prior to updating, make sure to examine Release Notes, as these may contain important information or update instructions.

Update section triggers update to the latest Stable Release if its number differs from the currently installed. The Force mode disable the check, update will be performed anyway.

Update on Change section updates to a Changes, identified by numeric <CHANGE_ID>. The Master Release is also available here, as the 0 change.

| Executing force Update after Update on Change operation will bring application server back to the latest Stable Release state.

##### Files' Replacement

| You can skip this section at first reading.

To preserve a changed configuration file like `log4j.properties` of being rewritten during updates, create in the same directory before a modification a copy of the original ones with .orig name’s ending, e.g. `log4j.properties.orig`. When such an original copy exist, the file will be replaced only if a new version of it differs from the original copy. The replaced file instead of real overwriting just renamed with .bak.<TIME_IN_SECONDS> suffix.

##### Console

| You can skip this section at first reading.

| Before installing an update, always make a backup copy of the program using the `backup.sh` script. If the db parameter is specified, the script will create a backup copy of the database, the data for connecting to the MariaDB server is taken from the `bgerp.properties` file. Backups are saved in the `backup` folder in files with the name format year-month-date-time(.db).zip, the presence of the db substring means that there is a database dump in the archive.

The update-related operations are performed by `installer.sh`. Running it without arguments prints the help:

    Commands for installer:
            update            - update to the actual builds if they differ from currents.
            updatef           - update to the actual builds without comparison.
            update <version>  - switch to another version (not build) of the program.
            killhash          - clear executed queries history.
            install <zip>     - install a module from the zip file.
            installc <change> - download update files from <change> and install them.

For your understanding, the Update in UI runs the following command:

    ./backup.sh && ./installer.sh update(f) && ./erp_restart.sh

And Update on Change this one:

    ./backup.sh && ./installer.sh installc <CHANGE_ID> && ./erp_restart.sh

###### Query History

For all the executed during update process SQL queries their hashes are stored in DB table db_update_log. This allows to prevent their re-execution. If you need to clear the history, use the command:

    ./installer.sh killhash

#### Errors

For better recognition of log with errors they are highlighted in UI.

#### Warn Log

Size of `bgerp.warn.log` must be zero, check messages there case and perform required fixes if its not.

Here is the list of typical issues there and ways to fix it.

Error’s Sample | Solution
--- | ---
Processor - Configuration key 'page' is no longer needed in processor definition: /WEB-INF/jspf/user/process/queue/default_marked_processor.jsp | Delete page key for processors configurations.
Bean class was found by an old name: ru.bgcrm.plugin.bgbilling.dao.MessageTypeSearchCall | Find the mentioned class key value in server configuration and replace it to MessageTypeSearchCall without package.
CommonObjectLink - Deprecated method 'getLinkedObjectId' was called. Use 'getLinkObjectId' instead. | Replace in process configurations getLinkedObjectId to getLinkObjectId
ParamExpressionObject - Deprecated method 'listValueTitles' was called. Use 'getValue' instead. | Replace in process configurations u.toString(processParam.listValueTitles(<ID>)) to processParam.getValue(<ID>)

#### Update Logs

In update logs can appear SQL errors and also REMOVE SOON messages about the files, must to be deleted from the application. Typically by moving to Custom area.

    07-03/09:05:09  INFO [main] Installer - Report:
    REPLACED:
    lib/app/bgerp.jar
    webapps/WEB-INF/jspf/user/plugin/bgbilling/search.jsp
    webapps/WEB-INF/jspf/user/plugin/bgbilling/search_contract_result.jsp
    REMOVE SOON:
    webapps/WEB-INF/custom

### Maintenance

Tool Administration / App / Maintenance allows to prevent data loss of working users during application restarts, required for updates and other procedures.

When the maintenance mode is started, none of users, except the started one is able to log in the system. For all the already logged in users logging in blocked after a some time, used for storing intermediate work results. To inform about maintenance begin and stop a popup news has been sent.

## Demo System

The Demo System is running on https://demo.bgerp.org with the latest Master Release of software and resets to initial state every 3rd hour. Since the system provides examples of the whole product functionality, it can be used to study the program with checking configurations.

| When searching for a needed process in a queue there, you might need first to increase the default page size.

In case of long-term experiments we recommend you to use Docker Container to avoid losing the changes made. A more detailed description of the Demo System is available in Workflow.