Methods

Minimal system requirements for running a server with BGERP + MySQL 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.

Мы рекомендуем вам установку в Docker контейнер, как наиболее простой способ запустить систему для изучения. В дальнейшем данные могут быть перенесены на Linux сервер для полноценной эксплуатации.

Docker

Installation from a Docker image.

The Docker image uses approximately 1 GB of disk space and contains the latest published build will all the required components: MySQL, Java. The actual Demo state is also applied during first run.

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 MySQL 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

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.

MySQL

The Original MySQL DB Server version 8.0 or newer has to be used for installation.

Different forks of MySQL (Maria, Percona) do not fit because of missing fulltext index support. Below is the test query you can use to verify compatibility:

// PzdcDoc snippet of: 'src/ru/bgcrm/plugin/fulltext/db.sql', lines: 1 - 9

CREATE TABLE IF NOT EXISTS fulltext_data (
        object_type VARCHAR(100) NOT NULL,
        object_id INT NOT NULL,
        scheduled_dt DATETIME,
        data TEXT NOT NULL,
        FULLTEXT (data) WITH PARSER ngram,
        KEY scheduled_dt (scheduled_dt),
        UNIQUE KEY type_id (object_type, object_id)
);

You can use the instruction for converting existing MySQL-like DB to the supported version.

Install

Once installed, check the mandatory options below in [mysqld] section in my.cnf file:

[mysqld]
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.

Optionally you can disable mysqlx protocol:

mysqlx=OFF

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 a root access to the MySQL 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 epel-release
sudo dnf install -y zip pwgen wget mysql-community-client unzip

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:

mysql --default-character-set=utf8 -h127.0.0.1 -uroot -p < /opt/bgerp/db_create.sql
mysql --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
mysql --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 a setenv.sh :

JAVA_HOME=/usr
if [ -z "$JAVA_HOME" ]; then
    echo "The JAVA_HOME environment variable is not defined"
    echo "This environment variable is needed to run this program"
    exit 1
fi

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

Step 8. Use erp_start.sh/erp_stop.sh for application start and termination. erp_status.sh will show 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 a systemd script. Systemd script is located in scripts/bgerp.service - copy it to /etc/systemd/system/ and then execute the following commands:

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

Update

Version

Система версионирования продукта описана на нашем веб-сайте. Следуя данному руководству, вы установите его актуальный Stable Release. При последующей эксплуатации рекомендуется обновляться только при выпуске очередного подобного релиза, о чём приложение информирует уведомлением в интерфейсе. Однако в момент первоначального запуска системы предпочтительно использовать Master Release для получения наиболее свежей функциональности.

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

Interface

You can use Admin / Application / Status tool to retrieve application’s current version and the list of available releases. All operations are implicitly using console utility described below.

app status update

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. The following command is executed:

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

Update on change section - updates to a Change package identified by CHANGE_ID. The following command is executed:

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

Executing Update after Update on change operation will bring application server to a latest Stable Release state.

Console

Перед установкой обновления всегда делайте резервную копию программы при помощи скрипта backup.sh

  • При указании параметра db скрипт создаст резервную копию БД, данные для подключения к серверу MySQL берутся из файла bgerp.properties

  • Резервные копии сохраняются в папке backup в файлах с форматом имени год-месяц-дата-время(.db).zip, наличие подстроки db означает, что в архиве есть дамп БД

Для обновления вызовите команду:

./installer.sh update

Для обновления системы на иную версию (не 3.0) вызовите команду:

./installer.sh update <version>

например:

./installer.sh update 3.0

Running 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.

Recommended command for updating (argument 'db' can be excluded for speeding up and used only periodically):

./backup.sh db && ./installer.sh update && ./erp_restart.sh

Update files are taken from version-containing URL, for example for version 3.0: https://bgerp.org/version/3.0/

Errors

After performing an update created a log file log/update_yyyy-MM-dd_HH:mm:ss.log that has to be checked on errors after that. For example there might be the DB permission issue.

04-07/19:53:25 ERROR [main] ExecuteSQL - Access denied; you need (at least one of) the SYSTEM_USER privilege(s) for this operation

It has to be fixed using the queries to MySQL executed with root user.

GRANT ALTER ROUTINE ON bgerp.* TO 'bgerp'@'%';
GRANT ALL PRIVILEGES ON bgerp.* TO 'bgerp'@'%';

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

Files' Replacement

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.<TimeInSeconds> suffix.

Maintenance

The tool Admin / Application / Maintainence allows to prevent data loss of working users during application restarts, required for updates and other procedures.

maintanence

When the maintanence 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 maintanence beginnging and cancelling popup news are 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. Поскольку в системе приведены примеры всего функционала продукта, она может использоваться для изучения программы с проверкой конфигураций. В случае длительных экспериментов для избежания потери сделанных изменений мы рекомендуем вам использовать Docker Container. Более подробное описание Demo System доступно в Workflow.