Each Axional Studio server will run on a Java VM 8 and it will load its configuration from a JAXB XML file, that describes it's boot configuration. After the startup, the server will load the configuration metadata from the central database dictionary, commonly known as wic_conf.

The following steps show how to setup the Axional Studio with an appropriate boot configuration.

 

1 Configuration file structure

The structure of the configuration file is shown below and it must be located inside the server tag with the rest of the configuration.

<server>
    <TAGS_FROM_AXIONAL_SERVER /> *
    <application
        xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
        xsi:type='studioConfig'
    > *
        <rootDir /> !
        <sessionCookieName /> ?
        <transport /> !
        <boot> *
            <database /> !
        </boot>
        <cluster> *
            <enabled /> !
            <nodeName /> !
            <scavengeInterval /> !
        </cluster>
        <services> !
            <http /> !
            <soap /> !
            <rest /> !
            <webSockets /> !
            <soapClasses> ?
                <class /> +
            </soapClasses>
        </services>
        <disableBeanLoadOptimization /> ?
    </application>
</server>

These parameters are part of the server node, so the form of the whole file config.xml is like:

Copy
<?xml version="1.0" encoding="UTF-8"?>
<server name="server1" engine="jetty">
   <realm info="Name of the server">Wellcome to server1</realm>
   <encoding info="Server encoding">UTF-8</encoding>
   <stop>
      <port>8777</port>
   	   <pass>abc</pass>
   </stop>
   <http info="Http parameters">
      <queueSize>-1</queueSize>
      <minThreads>-1</minThreads>
      <maxThreads>-1</maxThreads>
      <connectors>
         <connector>
            <scheme>http</scheme>
            <port>9090</port>
            <securePort>0</securePort>
            <acceptors>-1</acceptors>
            <selectors>-1</selectors>
            <acceptQueueSize>0</acceptQueueSize>
            <idleTimeout>60000</idleTimeout>
            <outputBufferSize>-1</outputBufferSize>
            <requestHeaderSize>-1</requestHeaderSize>
            <responseHeaderSize>-1</responseHeaderSize>
            <keystoreFile></keystoreFile>
            <keystorePassword>[changeit]</keystorePassword>
         </connector>
      </connectors>
   </http>
   <mail>
      <auth></auth>
      <host></host>
      <port>0</port>
      <starttls>false</starttls>
      <username>[changeit]</username>
      <password>[changeit]</password>
      <replyTo>no-reply@example.com</replyTo>
   </mail>
   <jdbc host="192.168.10.11" port="9088" service="ol_dbsrv1">
        <username>informix</username>
        <initSQL></initSQL>
        <password>CRYPT-AES128:EJ9cGH7Pnb+xFkGj0fzc5p7LvbWTzifU88R1khUaveYwNiw8YcsYAerU+GoxJ6tvGIAuB2o+uUQ0</password>
        <poolMaxSize>5</poolMaxSize>
        <poolExtraSize>0</poolExtraSize>
        <poolMaxIdle>300</poolMaxIdle>
        <poolMaxCheckOut>1000</poolMaxCheckOut>
        <poolAcquireTimeout>0</poolAcquireTimeout>
        <poolBornDieTimeout>0</poolBornDieTimeout>
        <queryTimeout>600</queryTimeout>
   </jdbc>   
   <console>
      <tcpPort>0</tcpPort>
      <enableWeb>false</enableWeb>
      <enableSwt>false</enableSwt>
      <username>admin</username>
      <password>[changeit]</password>
   </console>
   <logs>
      <accessLog>
         <days>0</days>
         <directory>logs</directory>
      </accessLog>
      <debugLog>
         <size>0</size>
         <directory>logs</directory>
         <default>CONFIG</default>
         <levels>
            <entry>
               <key>JAVA</key>
               <value>CONFIG</value>
            </entry>
            <entry>
               <key>REST</key>
               <value>CONFIG</value>
            </entry>
            <entry>
               <key>JDBC</key>
               <value>CONFIG</value>
            </entry>
            <entry>
               <key>HTTP</key>
               <value>CONFIG</value>
            </entry>
            <entry>
               <key>SOAP</key>
               <value>CONFIG</value>
            </entry>
         </levels>
      </debugLog>
   </logs>
   <fopConfigFile>conf/fop/userconfig.xml</fopConfigFile>
   <application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="studioConfig">
      <rootDir>webapp</rootDir>
      <transport>NONE</transport>
      <boot>
         <database wic='wic' admin='wic_admin'>wic_conf</database>
      </boot>
      <cluster>
         <enabled>false</enabled>
         <nodeName>PLUTON.deister.local</nodeName>
         <scavengeInterval>60</scavengeInterval>
      </cluster>
      <services>
        <http>true</http>
        <soap>false</soap>
        <rest>true</rest>
        <webSockets>true</webSockets>
        <!--
        <soapClasses>
            <class>deister.webstudio.core.services.soap.services.user.SOAPClassName</class>
        </soapClasses>
        -->
      </services>      
      <disableBeanLoadOptimization>false</disableBeanLoadOptimization>
   </application>
</server>

Http service

Setting the property in application/services/http to false will prevent users from login in, as all http transit through the browser will be restricted.

If HTTP, SOAP and REST are set to false, the HTTP services will be automatically enabled.

Session cookie name

Setting the property in application/sessionCookieName to a non-empty string will change the name of the browser cookie used for session management.

So multiple Axional Server products can be running in the same host without cookie collision.

 

2 Setup tool

The setup tool is a command line console that extends the Axional Server console to add Axional Studio specific commands. This commands are oriented to allow a "cold" server setup and they include:

  • update configuration file parameters
  • check the system status by verifying the connection to the primary database server
  • check the license status
  • create and upgrade the wic_conf database

To run the setup tool type:

Copy
$ bin/studio.sh --setup
Axional Server Console (C) 1996, 2017 deister software
Connected to titan.local, 192.168.10.100

....

The commands in the setup tool are:

Command Feature Element in config.xml JDBC required
Basic commands (from server core)
help Show commands usage  
quit Exit console  
ansi Toggle ansi display  
debug Toggle debug  
history Show commands history  
version Show manifests artifacts of current product  
hardware Show the hardware information  
diskfree Show the file system disk free  
java Shows the java VM information  
mail Show / configure / use mail server/mail  
nexus Show / configure / user nexus server/nexus  
license Show / configure / axional licenses server/license  
config.xml setup
jdbc Shows / updates the jdbc configuration server/application/jdbc  
wic_conf database setup
status Shows the system connection status.  
init Performs a full initialization of the wic_conf database by creating tables, loading data, creating indexes and procedure compilation  
create Create database tables, indexes or procedures.  
drop Drop database indexes or procedures.  
load Load database table data for system styles or labels.  
insert Insert database objects like server, database, database user, group or user.  
update Update database objects like server, database, database user, group or user.  
sql Enter the SQL command mode. Commands end with ; character  
 

3 Server licensing

The first time the setup is executed the configuration file is created. Running the setup tool will generate a default config.xml file if it does not exists

Copy
$ bin/studio.sh --setup

First of all it is necessary to set the license server

Set the product for the license

Copy
$ license set product studio

and exit for the setup tool.

Your provider will supply you the license code. This code must be added on the configuration file. Please, edit the file %JETTYHOME/conf/config.xml and copy the license code between the XML tags license:

Copy
<?xml version="1.0" encoding="UTF-8"?>
<server name="axional" engine="jetty">
   <license product="studio">
-----BEGIN PGP MESSAGE-----
Version: BCPG v1.59

owJ4nJvAy8zAJbj7sYSQctq/PsbTO5IE0jJzUv0Sc1N1PdPz8otSU2KWbpPlKijK
TylNLrEtLilNycznyiwuLk1NcUksSbU1MjC01DUw0TUw5kqtKMgsqoSIGhoYQEVz
MpNT84pTPVNsU4ySzS2SUox1U01Tk3SNjS0NPDoeLDsie83Sjdo1SDQxNDYzSuPKL
0hPzApdo0Hty82xdUjOLS1KLuFJzEzNzbFMKijJTS/IdUiCieqnFXPkFIHXFtlwd
uSwMglwMuqxMIPeqyUDVKBTnp5WUJxalKthARZB02zFwcQrA/K7/nGHBvSXsc/bU
3//0X2NO/KRNjTFT0n40M8xTmPK3j3Vh6NTtXwNm72sP284W09UCAJjQcWA=
=heGi
-----END PGP MESSAGE-----      
   </license>
   <stop>
      <port>0</port>
   </stop>
   ...
 

4 Setup bootstrap configuration database

If you have loaded both wic and wi_admin dictionary databases, you can setup the bootstrap url on application server to point to the boostrap server.

Required databases

If the required databases have not been installed, please go to this document before continue.

 

4.1 Create config.xml

Running the setup tool will generate a default config.xml file if it does not exists

Copy
$ bin/studio.sh --setup
Axional Server Console (C) 1996, 2016 deister software
Connected to titan.local, 192.168.10.100
+-----------------------+----------------------------------+--------+
 Configuration status
+-----------------------+----------------------------------+--------+
|key                    |value                             |state   |
+-----------------------+----------------------------------+--------+
|Config                 |/home/axs/studio/conf/config.xml  |OK      |
|Temp                   |/home/axs/studio/tmp/axional-19866|OK      |
|JDBC protocol          |jdbc:informix-sqli                |OK      |
|JDBC host              |unknown                           |OK      |
|JDBC port              |0                                 |NO      |
|JDBC service           |unknown                           |OK      |
|JDBC username          |informix                          |OK      |
|JDBC password          |[changeit]                        |Not safe|
|Dict wic database      |wic                               |FAILED  |
|Dict wic_admin database|wic_admin                         |FAILED  |
|Configuration database |wic_conf                          |FAILED  |
|Configuration tables   |0 of 0 tables                     |FAILED  |
|Configuration user     |manager                           |FAILED  |
+-----------------------+----------------------------------+--------+
Review config.xml boot section
Press ? for help
setup $>

The first time the setup is executed the configuration file is created and shows the next state errors:

key value state
JDBC password [changeit] Not safe
Dict wic database wic FAILED
Dict wic_admin database wic_admin FAILED
Configuration database wic_conf FAILED
Configuration tables 0 of 0 tables FAILED
Configuration user manager FAILED

In order to configure the correct data for your database server follow the next steps:

  1. The password to connect to the database server (informix as default user):
    Copy
    jdbc set password the_password
    as for example jdbc set password infpass
  2. The IP or DNSName of database server:
    Copy
    jdbc set host the_server_ip_or_dnsname
    as for example jdbc set host 192.168.1.99
  3. The informix service dbservername:
    Copy
    jdbc set service the_dbservername
    as for example jdbc set service ol_dbserver1
  4. The informix service port to the connect to the referended dbservername:
    Copy
    jdbc set port the_port
    as for example jdbc set port 9088

Check the new status

Copy
setup $> status
+-----------------------+-----------------------------------------------------------------------------------------+------+
 Configuration status
+-----------------------+-----------------------------------------------------------------------------------------+------+
|key                    |value                                                                                    |state |
+-----------------------+-----------------------------------------------------------------------------------------+------+
|Config                 |/home/axs/studio/conf/config.xml                                                         |OK    |
|Temp                   |/home/axs/studio/tmp/axional-19866                                                       |OK    |
|JDBC protocol          |jdbc:informix-sqli                                                                       |OK    |
|JDBC host              |pmahou                                                                                   |OK    |
|JDBC port              |9,088                                                                                    |OK    |
|JDBC service           |ol_pmahou                                                                                |OK    |
|JDBC username          |informix                                                                                 |OK    |
|JDBC password          |CRYPT-AES256:IJFb35SUp6iJy5Nomy/7nnIeBs4jNLZ/zQ9Nzd8VYggqzKA1jq+a7fYWkpRX5zSFfHiFYo30Elnb|OK    |
|Dict wic database      |wic                                                                                      |FAILED|
|Dict wic_admin database|wic_admin                                                                                |FAILED|
|Configuration database |wic_conf                                                                                 |FAILED|
|Configuration tables   |0 of 0 tables                                                                            |FAILED|
|Configuration user     |manager                                                                                  |FAILED|
+-----------------------+-----------------------------------------------------------------------------------------+------+

After the configuration of parameters to connect to the database server you must close the current setup session and executes again:

Copy
Ctrl+C [to close the current execution]
bin/studio.sh --setup

Now the new status shows that the connections to the database wic and wic_admin are correctly stablished:

Copy
+-----------------------+-----------------------------------------------------------------------------------------+------+
 Configuration status
+-----------------------+-----------------------------------------------------------------------------------------+------+
|key                    |value                                                                                    |state |
+-----------------------+-----------------------------------------------------------------------------------------+------+
|Config                 |/home/axs/studio/conf/config.xml                                                         |OK    |
|Temp                   |/home/axs/studio/tmp/axional-24096                                                       |OK    |
|JDBC protocol          |jdbc:informix-sqli                                                                       |OK    |
|JDBC host              |pmahou                                                                                   |OK    |
|JDBC port              |9,088                                                                                    |OK    |
|JDBC service           |ol_pmahou                                                                                |OK    |
|JDBC username          |informix                                                                                 |OK    |
|JDBC password          |CRYPT-AES256:IJFb35SUp6iJy5Nomy/7nnIeBs4jNLZ/zQ9Nzd8VYggqzKA1jq+a7fYWkpRX5zSFfHiFYo30Elnb|OK    |
|Dict wic database      |wic                                                                                      |OK    |
|Dict wic_admin database|wic_admin                                                                                |OK    |
|Configuration database |wic_conf                                                                                 |FAILED|
|Configuration tables   |0 of 0 tables                                                                            |FAILED|
|Configuration user     |manager                                                                                  |FAILED|
+-----------------------+-----------------------------------------------------------------------------------------+------+
 

4.2 Create configuration database (wic_conf)

In order to create the configuration database you can use one of the following methods:

  • init command: running this command the system creates the database, creates tables, loads the configuration data, creates indexes and compile procedures and triggers in sequence.
  • step by step process: step by step process or something that needs to be revised executing each command separately.

Recommended mode

We recommended the execution of init command to make more easy the creaction of wic_conf database. You can use the individual commands to check or recreate shomething that failed in the init command.
 

4.2.1 init command

You can use the init command to run all set of initialization commands in sequence. The init command executes the create database, create tables, load data, create indexes and create procedures commands in sequence.

Copy
setup $> init
Creating DDL TABLE

Creating DDL TLOAD
....
The database will be created in the default root space instead of d_conf dbspace. It's better to create it manually on the appropriate dbspace and then command init.

To create the database on the d_conf dbspace, execute this command from dbaccess tool

Copy
create database wic_conf in d_conf

and execute then

Copy
setup $> init

to create the schema and load the default data.

Finally do an update statistics on wic_conf database from dbaccess tool

Copy
update statistics low drop distributions
 

4.2.2 Create configuration database step by step

If you prefer a step by step process or something that needs to be revised, use the following commands to create a configuration database.

 

Create database

If you have not created configuration database manually, you can do it by simply typing:

Copy
setup > create database
Database wic_conf created
 

Create tables

On first installation, you need to create the initial tables. Use the command create tables to deploy the wic_admin schema into configuration database.

Copy
setup $> create tables
+-----+--------+---------+------+---------+------------------------------+-----+-------+------------------------------------------------------------------------+------+
 Create TABLE
+-----+--------+---------+------+---------+------------------------------+-----+-------+------------------------------------------------------------------------+------+
|seqno|database|server   |schema|dict     |table_name                    |group|status |message                                                                 |source|
+-----+--------+---------+------+---------+------------------------------+-----+-------+------------------------------------------------------------------------+------+
|    1|wic_conf|bootstrap|      |wic_admin|web_os_lbldata                |1/1  |SUCCEED|TABLE web_os_lbldata created.                                           |n/a   |
|    2|wic_conf|bootstrap|      |wic_admin|web_os_lbldata                |1/1  |SUCCEED|TABLE web_os_lbldata altered, operation is LOCK MODE ROW                |n/a   |
|    3|wic_conf|bootstrap|      |wic_admin|wic_cal_invitation            |1/1  |SUCCEED|TABLE wic_cal_invitation created.                                       |n/a   |
|    4|wic_conf|bootstrap|      |wic_admin|wic_cal_invitation            |1/1  |SUCCEED|TABLE wic_cal_invitation altered, operation is LOCK MODE ROW            |n/a   |
|    5|wic_conf|bootstrap|      |wic_admin|wic_cal_sched_inv             |1/1  |SUCCEED|TABLE wic_cal_sched_inv created.                                        |n/a   |
...            

Operation completed, 360 TABLE(s) created
 

Load basic data

Now you are ready to load basic data information like OS labels, available roles, application CSS style sheets, etc.

Copy
setup $> load
Operation completed with 0 error(s)
 

Create indexes

After data is loaded, you must create indexes and foreign keys.

Copy
setup $> create indexes
+-----+--------+---------+------+---------+----------------------------+-----+-------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+------+
 Create INDEX
+-----+--------+---------+------+---------+----------------------------+-----+-------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+------+
|seqno|database|server   |schema|dict     |table_name                  |group|status |message                                                                                                                                                       |source|
+-----+--------+---------+------+---------+----------------------------+-----+-------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+------+
|    1|wic_conf|bootstrap|      |wic_admin|wic_certificates            |1/1  |SUCCEED|UNIQUE INDEX i_wic_certificates1 created.                                                                                                                     |n/a   |
|    2|wic_conf|bootstrap|      |wic_admin|wic_customer                |1/1  |SUCCEED|UNIQUE INDEX i_wic_customer2 created.                                                                                                                         |n/a   |
|    3|wic_conf|bootstrap|      |wic_admin|wic_dbms_homeurls           |1/1  |SUCCEED|UNIQUE INDEX u_wic_dbms_homeurls created.                                                                                                                     |n/a   |
|    4|wic_conf|bootstrap|      |wic_admin|wic_dbms_pakgstamp          |1/1  |SUCCEED|UNIQUE INDEX u_wic_dbms_pakgstamp created.                                                                                                                    |n/a   |
|    5|wic_conf|bootstrap|      |wic_admin|wic_dbms_passwords          |1/1  |SUCCEED|UNIQUE INDEX i_wic_dbms_passwords created.                                                                                                                    |n/a   |
|    6|wic_conf|bootstrap|      |wic_admin|wic_dbms_procstamp          |1/1  |SUCCEED|UNIQUE INDEX u_wic_dbms_procstamp created.                                                                                                                    |n/a   |
...

Operation completed with 737 INDEX created(s)
 

Create procedures

The schema needs some business logic in form of stored procedures and triggers. The create procedures command will create all schema business logic.

Copy
setup $> create procedures
 

5 Verify configuration status

The command status can be used to verify the DDL & SPL status of configuration database.

Copy
setup $> status database

For an individual check of DDL or SPL you can run:

  • status tables - to check DDL table status
  • status checks - to check DDL table checks status
  • status indexes - to check DDL indexes status
  • status procedures - to check SPL compilation status
 

6 Other database settings

In order to start the server some other action should be taken on the DB.

 

6.1 Change the database-logging mode

The database wic_conf must be in unbuffered logging mode. On the database server use this command to change the logging mode of the database:

Copy
ontape -s -U wic_conf -t /dev/null
 

6.2 Set the connection timeout

The connections to the bootstrap DB (wic_conf) should be started with a non-null timeout time. Otherwise lock errors will happen when different users try to access to the same DB information. This setting can be changed using the tag initSQL in the jdbc section of the configuration file.

Copy
...
    <initSQL>SET LOCK MODE TO WAIT 5</initSQL>
...
 

7 Login page customization

 

7.1 Tunning the login page using server properties

Some changes can be made to the login page by using the server configuration file (conf/config.xml). Mainly color and logo image changes, including the possibility to set a "fullscreen" image or video as background.

The following sample properties tag can be included in a Axional Studio configuration file to customize the login page so it will have a lightgray backgound color, red buttons with green text, etc...

Copy
<properties>
    <entry><key>bgColor</key><value>lightgray</value></entry>
    <entry><key>boxBgColor</key><value>lightgoldenrodyellow</value></entry>
    <entry><key>buttonTextColor</key><value>green</value></entry>
    <entry><key>buttonBgColor</key><value>red</value></entry>
    <entry><key>bgImage</key><value>
        /studio/static/login/custom1/img/bg1.jpg,
        /studio/static/login/custom1/img/bg2.jpg
    </value></entry>
    <entry><key>bgVideo</key><value>
        /studio/static/login/custom1/video/vid1.mp4,
        /studio/static/login/custom1/video/vid2.mp4
    </value></entry>
    <entry><key>logoInside</key><value>/studio/static/login/custom1/img/deister-logo-light.png</value></entry>
    <entry><key>logoInsideLink</key><value>http://www.deister.net/</value></entry>
</properties>

Available properties:

  • boxBgColor: login form background color
  • boxTextColor: login form text color
  • buttonBgColor: buttons background color
  • buttonTextColor: buttons text color
  • logoInside: path to logo image file, relative to server root. For example, "/studio/static/login/custom1/img/deister-logo.png" if image is in "/home/studio/conf/static/assets/login/custom1/img/deister-logo.png"
  • logoInsideLink: link for the logo
  • bgColor: background color
  • bgImage: path to background image file
  • bgVideo: path to background video file (overrides previous property)

 

7.2 Creating a custom login page

In all the following example commands we assume that Axional Studio server is running in the path /home/axs/studio.

 

7.2.1 Preparation of the login page FreeMarker template

Create a new folder inside the configuration folder:

Copy
cd conf
mkdir -p static/login
unzip -j ../libs/axional.server.core-*.jar "deister/axional/server/resources/login/login.ftl" -d static/login
mkdir -p static/assets/login/css
touch static/assets/login/css/login.css

In the file static/login/login.ftl, after the line:

Copy
<#assign SERVER_STATIC = "/server/static">

add the following line:

Copy
<#assign STUDIO_STATIC = "/studio/static">

Again, in the file static/login/login.ftl, after the following line:

Copy
<link href="${SERVER_STATIC}/login/css/login.css?${VERSION_PARAM_NAME}=${vers}" type="text/css" rel="stylesheet">

add the following line:

Copy
<link href="${STUDIO_STATIC}/login/css/login.css?${VERSION_PARAM_NAME}=${vers}" type="text/css" rel="stylesheet">
 

7.2.2 Example 1: change background color

Create a custom CSS file in conf/static/assets/login/css/login.css with the following content:

Copy
body {
    background: none;
    background-color: blue;
}
 

7.2.3 Example 2: change image logo

To change the image logo create the directory

Copy
cd conf
mkdir static/assets/login/img

And put inside the image. Then edit the file static/assets/login/css/login.css and add the style:

Copy
.form-heading {
    margin-bottom: 15px;
    max-width: 100%;
    width: 370px;
    height: 66px;
    background: url(/studio/static/login/img/mycompany_logo.png) no-repeat;
    background-size: contain;
}
 

7.2.4 Example 3: change box login

Edit the file static/assets/login/css/login.css and add the style:

Copy
.form-signin {
    background-color: #FFE552;
    border-radius: 6px;
}
.btn-success {
    color: #fff;
    background-color: #9E9E9E;
}
 

7.3 Customizing the login page labels

In all the following example commands we assume that Axional Studio server is running in the path /home/axs/studio.

Create a new folder inside the configuration folder with the "label" files for the login page:

Copy
cd conf
mkdir -p static/login
unzip -j ../libs/axional.server.http-*.jar "deister/axional/server/http/resources/login/*.properties" -d static/login

All the labels defined in the "*.properties" files can be changed. This will take effect after restarting the server.

 

8 Security considerations

In installations exposed to the world wide web it's very important to take extra security precautions. By editing the config.xml file we can activate some HTTP filters to enable security measures recommended by The Open Web Application Security Project (OWASP).

For more information on the available filters and it's configuration options see the following document.