Installation and Configuration Guide For Jboss Solução Fiscal Web

Installation and Configuration Guide for JBoss
Solução Fiscal Web
Installation and Configuration

Guide for JBoss
1
Copyright © 2017 Synchro Brazil Tax Solution
All Rights Reserved
Installation Index
1. Introduction ................................................................................................................................................... 4
1.1. Caution ................................................................................................................................................... 4
1.2. Checking the installation ........................................................................................................................ 4
2. Environment Configuration ........................................................................................................................... 5
3. Pre-Requirements for Running the Installer ................................................................................................. 6
3.1. JDK .......................................................................................................................................................... 6
3.2. Operational systems ............................................................................................................................... 6
3.3. Connection to the database server ........................................................................................................ 6
3.4. File permissions ...................................................................................................................................... 6
4. How to Create Artifacts for Deployment....................................................................................................... 6
4.1. Parameterization file .............................................................................................................................. 6
4.2. Application root directory ...................................................................................................................... 7
4.3. Parallel instances deployment................................................................................................................ 8
4.4. Notes ...................................................................................................................................................... 8
5. How to Run the Installer ................................................................................................................................ 9
6. How to Configure JBoss Application Server ................................................................................................ 12
6.1. Overview ............................................................................................................................................... 12
6.2. Requirements ....................................................................................................................................... 12
6.3. Creating the administrator user ........................................................................................................... 12
6.4. Configuring maximum Metaspace size................................................................................................. 12
6.5. Configuring Oracle JDBC driver............................................................................................................. 13
7. JBoss Configuration Example ....................................................................................................................... 13
7.1. JVM ....................................................................................................................................................... 13
7.2. Memory configuration.......................................................................................................................... 16
7.3. Configuring maximum post size ........................................................................................................... 17
8. Configure the Database Connection ........................................................................................................... 19
9. Configure the System log Mecanism ........................................................................................................... 24
10. Deploy .EAR ............................................................................................................................................... 29
11. Post-installation ......................................................................................................................................... 30
11.1. Environment validation ...................................................................................................................... 30
11.2. Administrator first login ..................................................................................................................... 31
11.3. Configuring the application ................................................................................................................ 32
2
All Rights Reserved
Welcome to the installation and configuration guide Solução Fiscal Web!
The main objective of this guide is to help with the configuration and installation process of
the Solução Fiscal Web. The configuration file and installation instructions may change
from version to version.
Important Changes:
From version 6.0.0 onwards:
 The client.properties file will be migrated to the database. All values you
have set in this file will no longer be retrieved from it, instead will be
retrieved from the database. But since the installation process requires a
database connection you will still need to configure the needed properties for
it, listed below:
o database.username
o database.password
o database.url
o database.tablespace
o database.indexspace
o database.lobspace
 Also there are another properties needed for the installation process and
needed to be in the client.properties:
o sufixo.url.ambiente
o sfw.web.root.dir
o sfw.batch.root.dir
 The client.properties will be replaced by another file in the installation

process.
 All other application configuration will be done from inside the SFW
application and stored in the database.
 The Solução Fiscal Web application will be unable to be accessed by
the users until an Administrator verify the properties migrated to the
database.
3
All Rights Reserved
Quick checklist of hardware and software pre-requirements:
 Dedicated User/Schema at a Oracle Database Server (Standard or Entreprise.

Express Edition are not supported )
 J2EE Aplication Server : WildFly 10, JBoss EAP 7, Weblogic 12.2.1.2.0 and
WebSphere 9.0.0.X (check AS versions and JVM versions supported)
 SMTP server (very important! Only with correctly smtp configuration it is possible
rescue admin password!).
 If you use proxy:
 Allow access to domains saas.synchro.com.br, sfw.synchro.com.br and

produtos.synchro.com.br (used to: access tutorial, download new installation
packages and user license validation).
1. Introduction
1.1. Caution
 Required to install on WINDOWS: Unzip sfw_installer.zip file, in root file

system (example C:\ or E:\), due to limitation in 256 characters on path
name.
 In the installation process there is the optional property
"sufixo.url.ambiente" in the properties file and if It is set, its value sets a
sufix for the application and the viewer context root.
For instance: sufixo.url.ambiente=_QA

Application context root: http://domain:8080/sfw_QA
Viewer context root: http://domain:8080/viewer-sfw_QA
The main objective of this guide is to help with the configuration and installation
process of the Solução Fiscal Web. The configuration file and installation
instructions may change from one version to another.
So if you are reinstalling or updating the product, please refer to new artifacts
version.
1.2. Checking the installation
Before unzipping the sfw_installer.zip, check the MD5 hash against the contents of
sfw_installer_md5.txt file.
To generate the file MD5 hash on the Linux operating system, use the following
command: md5sum sfw_installer.zip
4
All Rights Reserved
Example of an expected result:
[root@x tmp]# md5sum sfw_installer.zip

6d3b2c848abd116c1fb5e50d0631049d sfw_installer.zip
To generate the file md5 hash in the Windows operating system, you must
download the software MD5summer at: http://www.md5summer.org
2. Environment Configuration
Create Oracle User for application. See the sample create statement:
CREATE USER SFW_SAMPLE PROFILE default IDENTIFIED BY SFWPASSWORD DEFAULT TABLESPACE

USERS TEMPORARY TABLESPACE TEMP ACCOUNT UNLOCK;
GRANT CREATE VIEW TO SFW_SAMPLE;
GRANT "CONNECT" TO SFW_SAMPLE;
GRANT CREATE TABLE TO SFW_SAMPLE;
GRANT CREATE SEQUENCE TO SFW_SAMPLE;
GRANT CREATE PROCEDURE TO SFW_SAMPLE;
GRANT SELECT ANY DICTIONARY TO SFW_SAMPLE;
GRANT CREATE TYPE TO SFW_SAMPLE;
ALTER USER SFW_SAMPLE QUOTA 100000M ON TBS_DT_SFW;
ALTER USER SFW_SAMPLE QUOTA 100000M ON TBS_IX_SFW;
ALTER USER SFW_SAMPLE QUOTA 100000M ON TBS_LOB_SFW;
5
All Rights Reserved
3. Pre-Requirements for Running the Installer

From the workstation where the installer is going to be executed, the following items
must be configured in order to have a compatible environment for the installation
process:
3.1. JDK:
1.8.0 or higher in the version 1.8. Check with the Application Server vendor for
required versions.
3.2. Operational systems:

As specified by JBoss Vendor.
3.3. Connection to the database server
 From the workstation where the installer is going to be executed.

 Required database grants (specified on the "hardware and software pre-
requirements" document).
3.4. File permissions:
 Execution permission for the file "install.bat/install.sh".

 Read permission: the files inside the installation package need to have read
permission.
 Write permission: some installation artifacts are created when the installation
process is finished.
 At least 2 GB of RAM Memory to execute the installer.
4. How to Create Artifacts for Deployment
4.1. Parameterization file
Before the execution of the installer will need the configuration file. If it’s a new
installation, please use only the sfw.properties file for the installation process. If
you are updating from a previous version, use only the client.properties.
All required parameters must be set, as described in the text boxes on the file's
contents. Required parameters:
o database.username
o database.password
o database.url
o database.tablespace
o database.indexspace
o database.lobspace
o sufixo.url.ambiente
o sfw.web.root.dir
o sfw.batch.root.dir (only in a distributed installation)
6
All Rights Reserved
After editing all required parameters, save the file and close.
4.2. Application root directory
These directories will be used by the application and must be accessible

(read/write) to the application server instance user. This directory (<sfw.root.dir>)
will be used to set the property "sfw.web.root.dir"
Example:
7
All Rights Reserved
4.3. Parallel instances deployment
The SFW can be deployed in parallel batch instances, “standalone” instances of

the application server, making possible that two or more servers work together, in
order to increase the number of process that could be simultaneously executed.
These servers share among themselves the processing activities.
To publish parallel batch instances, simply fill in these properties:

i. The parameter "org.quartz.jobStore.isClustered" with the value "true";
ii. The parameter "org.quartz.scheduler.instanceId" with the value "AUTO";
iii. Use the same EAR BATCH in both JBoss "standalone" instances.
4.4. Notes:
In a Distributed Deploy: Define the directory structure in both instances (WEB and
BATCH). If both instances are running on the same machine, do not use the same
root dir for both. Create a separated root directory for each instance.
Example:
i. c:/synchro/web (web instance) >> content will be set in property

"sfw.web.root.dir".
ii. c:/synchro/batch (batch instance) >> content will be set in the property
"sfw.batch.root.dir".
iii. When configuring the paths on Windows Operational System, be aware to
use forward slash ("/") or double backward slash ("\\") as a folder separation
character. For instance: “C:/root/synchro/web” or "C:\\root\\synchro\\web".
iv. When configuring the paths on Linux Operational System, we must use
forward slash ("/") only. For instance: "/root/synchro/web".
8
All Rights Reserved
5. How to Run the Installer

Review client.properties file and run the "install/update command"
(windows: <install_path>/install.bat and linux/unix: <install_path>/install.sh).
Note: Linux: grant permission to run the file executing the command:
chmod +x install.sh
The installer will display a welcome screen with some information about the SFW
version you are installing.
The installer checks if the correct JDK is configured and checks the md5 of the
installation files. It also checks if the required parameters in the "client.properties" are
set, if any required property is empty, the installation will be aborted.
The properties set on properties file are logged into the installation log file
"install_log.txt" inside output folder, this feature is important to troubleshooting analysis
related to environment and installation problems.
After the validations the installer prompts to continue with the installation. Enter “ok” to
continue.
Inform the Application Server with one of the following options: jboss, wildfly,
weblogic, websphere:
The EAR file (Enterprise Archive) will be structured according to the chosen
application server.
9
All Rights Reserved
Inform whether to perform packaging for distributed deployment: y (yes) or n (no). If

so, two EAR’s will be generated (WEB / BATCH instance):
Inform the desired process with one of the following options: i (install) or u (update).
This information is used to identify which artifacts shall be generated:
If the selected option is n (no) and if this is the FIRST installation, you have to
manually create the “database version control” table of the application before continue
with the installation process.
To create the table, run the following script:

<install_path>/output/db/createSchemaVersionTable.ora.sql
After creating the table type "ok" (prompt) to proceed with the installation.
The installer checks if the required database privileges are granted to the database
user configured for installation. If some database required privilege are not granted to
the database user, the message below will be displayed.
10
All Rights Reserved
After check the required privileges, type "ok" (prompt) to proceed with the installation.
The final step of the installation process is the verification of the client.properties file
migration to the database in the case of an update. If it’s not migrated, the installer will
migrate it automatically and create a sfw.properties file.
11
All Rights Reserved
6. How to Configure JBoss Application Server
6.1. Overview
The purpose of this installation and configuration guide is to describe the

necessary configuration to deploy the Solução Fiscal Web in JBoss Application
Server, as well as the requirements for its execution. Here we will see how to set
the data source, update and install SFW.
6.2. Requirements
For JBoss configuration and the deploy of the Solução Fiscal Web, we have to
conform the following requirements:
JBoss and DBMS version compatible with the application as described in the
document of hardware and software available in the product website:
http://produtos.synchro.com.br
6.3. Creating the administrator user
To create the administrator user, go to <jboss_home>/bin directory and run the

command add-user.sh (Linux) or add-user.bat (Windows). Choose option “a”
and fill the user name and password.
6.4. Configuring maximum Metaspace size
To configure the maximum post size in order to enable large file uploads go to
<jboss_home>/bin directory and edit the standalone.conf.bat file. Locate the
properties below (JVM memory allocation pool parameter) and configure the
values -Xms2048m -Xmx6000m -XX:MetaspaceSize=64m -
XX:MaxMetaspaceSize=512m
12
All Rights Reserved
6.5. Configuring Oracle JDBC driver
Start the JBoss server. If the server started without errors go to <jboss_home>/bin
and execute the jboss-cli.sh (Linux) or jboss-cli.bat (Windows).
Type connect and click Enter.
Run the following command, where DRIVER_PATH is the location of the

ojdbc6.jar that come with the installer, usually in <installer_path>/resources:
module add --name=com.oracle --resources= DRIVER_PATH/ojdbc6.jar --

dependencies=javax.api,javax.transaction.api
Note: due to a bug in some consoles and editors instead of copy/pasting the command
above type it in the console.
Check if no error messages are displayed. Next enter the following command:
/subsystem=datasources/jdbc-driver=oracle:add(driver-name="oracle",driver-module-
name="com.oracle",driver-class-name=oracle.jdbc.driver.OracleDriver
Note: due to a bug in some consoles and editors instead of copy/pasting the command
above type it in the console.
If you see a message of the outcome as success everything is ok.
7. JBoss Configuration Example
7.1. JVM
Check if the JVM version is one supported version according to the Hardware and
Software Requirements. To check the JVM version, access the Administration
Console.
13
All Rights Reserved
From the menu navigate Runtime > Standalone Server > Log Files and click View.
Select server.log and click View.
14
All Rights Reserved
Search for java.runtime.version and check if the value is according tho the requirements.
15
All Rights Reserved
7.2. Memory configuration
From the menu navigate Runtime > Standalone Server > Log Files and click View.
Select server.log and click View.
Check if the Heap and Metaspace memory are set properly. We should set at least
the following parameters values:
16
All Rights Reserved
7.3. Configuring maximum post size
Select Configuration in the menu and navigate to Subsystems -> Web/HTTP –

Undertow -> HTTP and click View.
Select HTTP SERVER tab and select default-server. Click View
17
All Rights Reserved
Select HTTP Listener tab and click edit. Fill the Max post size property with
10737418240. Click Save.
18
All Rights Reserved
8. Configure the Database Connection

Select Configuration in the menu and navigate to Subsystems -> Datasources ->
Non-XA and click Add.
Select “Oracle Datasource” and click Next.
19
All Rights Reserved
Inform the value SFW_DS for the name and java:/SFW_DS for the JNDI name. Click
Next.
In the next screen select Detect Driver and select oracle. Click Next.
20
All Rights Reserved
In the next screen inform the connection properties as given by the customer and click
Next. Example:
21
All Rights Reserved
Review the settings and click Finish.
22
All Rights Reserved
Select the created datasource, click on the drop-down and select the option “Test
Connection”. Check if the connection was successful.
23
All Rights Reserved
9. Configure the System log Mecanism
From the mains menu, navigate to Configuration -> Subsystems -> Logging and
click View.
Navigate to Handler and select Size. Click Add. Inform the name SFW_LOGGER and click
Next.
24
All Rights Reserved
Inform the path of the log file server.log and relative to jboss.server.log.dir and click
Finish.
25
All Rights Reserved
Next select the SFW_LOGGER and click Edit in the Attributes tab. Fill the values like
below and click Save:
 Append: false;
 Autoflush: true;
 Enabled: true;
 Encoding: blank;
 Filter spec: blank;
 Formatter: %d %-5p [%c] %m%n
 Level: ERROR;
 Max backup index: 10;
 Named formatter: blank;
 Rotate on boot: false;
 Rotate size: 51200K
 Suffix: blank
26
All Rights Reserved
Next, select the Log Categories tab and add the following categories:
 Name: br.com.synchro, Category: br.com.synchro, Level: ERROR;

 Name: org.hibernate, Category: org.hibernate, Level: ERROR;
 Name: org.apache, Category: org.apache, Level: INFO;
 Name: org.jboss.serial, Category: org.jboss.serial, Level: INFO;
 Name: org.jgroups, Category: org.jgroups, Level: WARN;
 Name: jacorb, Category: jacorb, Level: WARN;
 Name: org.jboss.management, Category: org.jboss.management, Level:
INFO.
27
All Rights Reserved
Next select the Root Logger tab and click Edit. Add the SFW_LOGGER to the
Handlers list and remove the FILE handler, click Save.
28
All Rights Reserved
Navigate to Handler and select Periodic. Select the FILE handler and click Remove.
Restart the server for the changes to take effect.
10. Deploy .EAR
With the JBoss server started select Deployments in the menu and click Add. Select
“Upload a new deployment” and click Next. Select the file sfw-<versao>-
<app_server>.ear located in <installer_path>/output/ and click Next. Click Finish. Wait
for the deployment to finish and check if the deployment was successful.
29
All Rights Reserved
11. Post-installation
11.1. Environment validation
When starting the application server, the environment validator can stop SFW
Application if there is any issue about the environment.
The Environment Validator performs validation on the following items:
 The JVM perm memory: If the value is lower than the specified.
 The application directory structure: If they are not proper configured (See
item "Parameterization file client.properties: Application's root directory:").
 Validation scripts applied in data base: Check "User Name" created on data base,
to make sure that there is just one SFW EAR file in the deploy folder and Install
application again.
 The sample below shows the stacktrace that can exist in the server log file:
Note: So, if the SFW application is not up after start, look up in the application
server log files for the stacktrace shown below.
30
All Rights Reserved
11.2. Administrator first login
Access the application URL: http://<host-appserver>:<port-appserver>/sfw

Example: http://localhost:8080/sfw
Where:
 host-appserver = Server where JBoss is installed, this information is given by

the customer
 port-appserver = Application access port, this information also is given by the
customer.
Note about distributed deployment: the URL for accessing the application (HTTP) is that
deployed in the WEB instance.
If the installation was successful you should see the login screen:
Log in as admin password 12345. You will be asked to type in a new password.
31
All Rights Reserved
11.3. Configuring the application
After the first login, the Administrator needs to review and configure the application
properties in order to enable the other users to access the application. In the menu
select Configuração de Sistema > Configuração da Aplicação
Configure each individual group accordingly, and then click Gravar. Each group will be
validated and the properties values will be saved in the database. If the properties
values are valid the other users will be able to access the Solução Fiscal Web and the
application will be ready for use.
32
All Rights Reserved

Installation and Configuration Guide For Jboss Solução Fiscal Web

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Installation and Configuration Guide For Jboss Solução Fiscal Web

Uploaded by

Copyright:

Available Formats

Installation and Configuration Guide for JBoss

Solução Fiscal Web

Installation and Configuration

Welcome to the installation and configuration guide Solução Fiscal Web!

From version 6.0.0 onwards:

 The client.properties will be replaced by another file in the installation

Quick checklist of hardware and software pre-requirements:

 Dedicated User/Schema at a Oracle Database Server (Standard or Entreprise.

 Allow access to domains saas.synchro.com.br, sfw.synchro.com.br and

 Required to install on WINDOWS: Unzip sfw_installer.zip file, in root file

For instance: sufixo.url.ambiente=_QA

1.2. Checking the installation

Example of an expected result:

[root@x tmp]# md5sum sfw_installer.zip

CREATE USER SFW_SAMPLE PROFILE default IDENTIFIED BY SFWPASSWORD DEFAULT TABLESPACE

3. Pre-Requirements for Running the Installer

3.2. Operational systems:

3.3. Connection to the database server

 From the workstation where the installer is going to be executed.

3.4. File permissions:

 Execution permission for the file "install.bat/install.sh".

4. How to Create Artifacts for Deployment

4.1. Parameterization file

4.2. Application root directory

These directories will be used by the application and must be accessible

4.3. Parallel instances deployment

The SFW can be deployed in parallel batch instances, “standalone” instances of

To publish parallel batch instances, simply fill in these properties:

i. c:/synchro/web (web instance) >> content will be set in property

5. How to Run the Installer

Inform whether to perform packaging for distributed deployment: y (yes) or n (no). If

To create the table, run the following script:

6. How to Configure JBoss Application Server

The purpose of this installation and configuration guide is to describe the

6.3. Creating the administrator user

To create the administrator user, go to <jboss_home>/bin directory and run the

6.4. Configuring maximum Metaspace size

6.5. Configuring Oracle JDBC driver

Type connect and click Enter.

Run the following command, where DRIVER_PATH is the location of the

module add --name=com.oracle --resources= DRIVER_PATH/ojdbc6.jar --

If you see a message of the outcome as success everything is ok.

7. JBoss Configuration Example

7.2. Memory configuration

7.3. Configuring maximum post size

Select Configuration in the menu and navigate to Subsystems -> Web/HTTP –

Select HTTP SERVER tab and select default-server. Click View

8. Configure the Database Connection

Select “Oracle Datasource” and click Next.

Review the settings and click Finish.

9. Configure the System log Mecanism

 Name: br.com.synchro, Category: br.com.synchro, Level: ERROR;

10. Deploy .EAR

11.2. Administrator first login

Access the application URL: http://<host-appserver>:<port-appserver>/sfw

 host-appserver = Server where JBoss is installed, this information is given by

11.3. Configuring the application

You might also like