System Requirements

Java

The application is compiled and runs on Java version 17. You need to download and install JDK 17 (or later) from the official Oracle website: https://www.oracle.com/cis/java/technologies/javase/jdk17-archive-downloads.html

PHP

Only needed if you publish PHP scripts, php-fpm install is required.

Currently The PHP support was tested with the ORO, the Symfony based complex application, Wordpress CMS and Magento internetshop application.

php-fpm service should listen on localhost on any free port, default is 9000. Please, specify the php-fpm endpoint in your project's etc/server.properties file. Example: php.fpm.host=localhost:9000

Run Jaisocx Server

1. Go to "cmd-windows" folder
2. Double click on "server_run.cmd"

After successfully launching the application, you will see the Jaisocx icon in the system tray. Server management (start, stop, restart and exit) is carried out through the icon in the system tray by clicking the right mouse button.

System Requirements

Java

The application is compiled and runs on Java version 17. You need to download and install JDK 17 (or later) from the official Oracle website: https://www.oracle.com/cis/java/technologies/javase/jdk17-archive-downloads.html

PHP

Only needed if you publish PHP scripts, php-fpm install is required.

Currently The PHP support was tested with the ORO, the Symfony based complex application, Wordpress CMS and Magento internetshop application.

php-fpm service should listen on localhost on any free port, default is 9000. Please, specify the php-fpm endpoint in your project's etc/server.properties file. Example: php.fpm.host=localhost:9000

Run Jaisocx Server

1. Go to "cmd-macos" folder
2. Open Terminal app and cd to current folder
3. Run command in terminal

bash ./server-run.sh

After successfully launching the application, you will see the Jaisocx icon in the system tray. Server management (start, stop, restart and exit) is carried out through the icon in the system tray by clicking the right mouse button.

System Requirements

Java

The server was compiled with Amazon Coretto JDK 17. For running Jaisocx server you need any JDK 17 or later having installed on your machine.

For example, on Ubuntu, you can run in the terminal following commands:

sudo apt-get update
sudo apt-get install openjdk-17-jdk

PHP

Only needed if you publish PHP scripts, php-fpm install is required.

Currently The PHP support was tested with the ORO, the Symfony based complex application, Wordpress CMS and Magento internetshop application.

php-fpm service should listen on localhost on any free port, default is 9000. Please, specify the php-fpm endpoint in your project's etc/server.properties file. Example: php.fpm.host=localhost:9000

Run Jaisocx Server

Run in the Terminal window

cd to the folder, where you unpacked the Jaisocx application, cd to "cmd-linux" folder.

bash ./server-run.sh

You will see log output in the terminal window

===============================================
JAISOCX API Web Server 2021/5.5 (Java MVC, PHP,
SQL-to-JSON, JS Frameworks support) is active
===============================================

Now you can access Jaisocx default page under http://localhost/, or, if port 80 on your system is busy, at http://localhost:2288/

Press Ctrl-C to stop the server.

Run as a service

cd to "cmd-linux/service-template" folder, edit jaisocx.service file. You need to change "WorkingDirectory" parameter value to the absolute path to your cmd-linux folder on your machine.

Run following script in terminal, being in cmd-linux folder:

bash ./install.sh

The server should be running the default Jaisocx home page. Now you can manage your server with systemctl command to start, restart, stop the jaisocx service. For example:

sudo systemctl restart jaisocx
  or
sudo systemctl stop jaisocx
  or
sudo systemctl status jaisocx

System Requirements

Docker, docker-compose

e.g. under Windows, it is very hard to install all required php extensions .dlls for a php application. that is why a docker-compose setup is recommended. of course, you can use docker setup on any other OS, since you're ensured in docker usage advantages. Docker installation instructions can be found at docker official site at docker.com

Here is one more awesome posts at upwork: Install docker-compose

Use jaisocx with docker-compose

Jaisocx docker image on dockerhub

Please visit following link: jaisocx/webserver

Symfony app sceleton under Jaisocx webserver with docker-compose example

Feel free to use a sample setup on github: Symfony

Laravel app sceleton under Jaisocx webserver with docker-compose example

Feel free to use a sample setup on github: Laravel

Wordpress app under Jaisocx webserver with docker-compose example

Feel free to use a sample setup on github: WordPress

Static web contents

In the "etc/" folder, the "server.properties" file contains path to server configuration file. Property is called "app.config.file". Set your own, if needed. Further readings show how to edit config file, in order to publish your contents.

Publish HTML app folder

Default app is stored in "apps/congratulations" folder, config is stored in "app/congratulations/conf/htp-conf.xml" file.

In order to publish your first site, the conf file should be configured as in this example:

<conf>
  <conf-idm
    path="apps/congratulations/conf/idm-conf.xml">
  </conf-idm>
  <conf-http>
    <servers>
      <server
          port="80"
          alternative-port="2288">
        <domain name="localhost">
          <alias
            art="folder"
            url="/"
            path="apps/congratulations/www/"
            cache="cache"
            list="false"
            each-folder-content-file-name="index.html"/>
        </domain>
      </server>
    </servers>
  </conf-http>
</conf>

Explaination: servers tag contains server tags, those define servers, listening on a specific port. Under each listening port, you can publish your domains. Just change <localhost> tag name to your domain, registered on DNS server, or specified in /etc/hosts file.

an <alias> tags are defining urls to publish contents under current domain, and paths to source files. alias can be of art folder or file. url attribute specifies the url to publish, and path atibute - the path to html/css/js contents.

During development, the cache attribute should be "update", and for publishing live, better speed is with cache="cache"

List attribute for aliases of art folder, specify whether to publish list of files in a folder, if no default html file for the folder specified.

each-folder-content-file-name shows the file, that will be shownon folder url. if omitted, the listing of directory will be shown, if attribute list="true"

Jaisocx server is equipped with a built-in resource caching mechanism. However, it is possible to set exceptions to prevent the server from caching these files.

Specifying exceptions

You can specify exceptions by adding the "cache-except" attribute to the "alias" tag of your configuration file. After the "=" sign, file extensions are indicated that the server should not cache. Extensions can be one or more. Multiple file extensions are separated by commas.

<conf>
  <conf-idm path="apps/congratulations/conf/idm-conf.xml">
  </conf-idm>
  <conf-http>
    <servers>
      <server
          port="80"
          alternative-port="2288">
        <domain name="localhost">
          <alias art="folder"
            ...
            cache-except="php, mp4"
            .../>
        </domain>
      </server>
    </servers>
  </conf-http>
</conf>

Jaisocx server supports 303 redirects. In the near future it will be possible to manually specify the desired redirect code.

Specifying a redirection

<conf>
  <conf-idm path="apps/congratulations/conf/idm-conf.xml">
  </conf-idm>
  <conf-http>
    <servers>
      <server
          port="80"
          alternative-port="2288">
        <domain name="localhost">
          <alias
            art="redirection"
            url="/redirect/"
            path="https://google.com/" />
        </domain>
      </server>
    </servers>
  </conf-http>
</conf>

Publishing charset

You can specify any charset name, supported by Java and all browsers, how the web contents will be encoded at sending to browsers. Attribute publish-charset="UTF-8" for example, must be set on an alias tag, domain tag, or server tag. if the alias doesn't have this attribute, the domain publish-charset attribute will be used, if omitted, then server tag attribute will be used.

Attribute source-charset="charset of your saved file", e.g. source-charset="UTF-8" must be set, if you're sure, the charset encoding, that your text files were saved.

If publish-charset and source-charset attributes have the same value, then no re-encoding will be performed, and the speed of server startup and response will be higher. It is recommended.

If you're not sure

If you aren't sure, what encoding has saved file, you can specify attribute language="language" and attribute source-charset="*", the language value should be equal to filename without .txt extension, from the alphabets folder in the jaisocx app root. e.g. language="german" source-charset="*" publish-charset="UTF-8"

You can add your own language file into alphabets folder, the file should contain all chars of your language, following each other, not separated by any char or whitespace, obligatory saved in UTF-8 encoding.

If Jaisocx package doesn't contain your language alphabet, feel free to support us with your language .txt file per email. We will provide it in later releases for your country citizens. Thank You.

Following example shows how to publish a Wordpress app under specific domain. url atribute with value ${any} is required for correct js framework routing. put this config part into a server tag, set path values to path to your wordpress root folder, where you'll see index.php root app file.

<domain name="wordpress-example.jaisocx.loc">
  <alias
    art="file"
    url="/${any}"
    path="Application Data/applications/default/www/applications/wordpress/index.php"
    cache="update"/>
  <alias
    art="folder"
    url="/"
    path="Application Data/applications/default/www/applications/wordpress/"
    cache="cache"
    cache-except="php"
    list="false"
    each-folder-content-file-name="index.php"/>
</domain>

You can also have a look on the ready config file and server.properties file for wordpress install on the github site: WordPress under Jaisocx Docker Setup, the server config.xml You'll find in the repo's folder docker/jaisocx-http/conf/http-conf.xml and the server.properties in docker/jaisocx-http folder. the most important for php-fpm is: php.fpm.host=localhost:9000 if having troubles with PHP install, feel free to use the ready for serve docker enabled repo.

Following example shows how to publish a build of an angular app under specific domain. url atribute with value ${any} is required for correct js framework routing. put this config part into a server tag, set path values to path to your angular built folder, where you'll see index.html root app file.

<domain name="angular-example.jaisocx.loc">
  <alias art="file"
    url="/${any}"
    path="Application Data/applications/default/www/applications/angular/index.html"
    cache="cache"/>
  <alias art="folder"
    url="/"
    path="Application Data/applications/default/www/applications/angular/"
    cache="cache"
    list="true"
    each-folder-content-file-name="index.html"/>
</domain>

Following example shows how to publish a build of an react app under specific domain. url atribute with value ${any} is required for correct js framework routing. put this config part into a server tag, set path values to path to your react built folder, where you'll see index.html root app file.

<domain name="react-example.jaisocx.loc">
  <alias art="file"
    url="/${any}"
    path="Application Data/applications/default/www/applications/reactjs/index.html"
    cache="cache"/>
  <alias art="folder"
    url="/"
    path="Application Data/applications/default/www/applications/reactjs/"
    cache="cache"
    list="true"
    each-folder-content-file-name="index.html"/>
</domain>

Following example shows how to publish a build of an VueJS app under specific domain. url atribute with value ${any} is required for correct js framework routing. put this config part into a server tag, set path values to path to your VueJS built folder, where you'll see index.html root app file.

<domain name="vue-example.jaisocx.loc">
  <alias
    art="file"
    url="/${any}"
    path="Application Data/applications/default/www/applications/vuejs/index.html"
    cache="cache"/>
  <alias
    art="folder"
    url="/"
    path="Application Data/applications/default/www/applications/vuejs/"
    cache="cache"
    list="true"
    each-folder-content-file-name="index.html"/>
</domain>

Jaisocx server uses JKS files to get certificates info for secure HTTPS connections.

There is a script for generation of a .jks file, using free certificates library certbot tool.

• First, edit file ssl/Linux/get-cert.sh. Put your email address, domain name and .jks password in the most upper block of the file.

#!/bin/bash

#=========== PLEASE, SET HERE YOUR PARAMS ==============================
export EMAIL="illia.polianskyi@jaisocx.com"
export DOMAIN="politest.fun"

# Specify the keystore password 
# that is used to protect the integrity of the keystore.
# Keystore password must be at least 6 characters.

JKS_PASSWORD=adminpass

#===============================================================

• Upload this file to Your host where the web server will be running.
• Get sure, this host's IP address is mapped at Your DNS provider to Your domain name, for that You wish to get the certificate.
• Get sure, the port 80 is free, otherwise please stop server running on port 80.
• Then, run the script as mentioned here:

cd ssl/Linux
./get-cert.sh

The generated free .jks file, secured with password, will be at

ssl/Linux/certs/<domain-name>/<domain-name>.jks        

Now You can use this .jks file for https, as described in section below: Config attrs for HTTPS.

Jaisocx server uses JKS files to get certificates info for secure HTTPS connections. to create a store, you need first buy a certificate at one of Certification authorities in the internet, or generate a self-signed one for free, for example with certbot tool.

As you got your cert private key and cert files, navigate to a folder in Jaisocx app root "ssl", and choose subfolder for your operating system, e.g. Linux. There you'll find generate-jks.sh file, where you have to edit parameters, pointing to your cert files. for example, CRT_FILE is a quoted-surrounded absolute path to your certificate text file, .crt or .pem or similar. PRIVATE_KEY - accordingly the path to private key file.

If you generated a cert with certbot, you won't have Root certifiacte authority file ROOT_CA, nor SUB_CA, used as chain in your certificate. then provide please only CRT_FILE and PRIVATE_KEY, not ROOT_CA nor SUB_CA, and edit script on line 54,

cat "$SUB_CA" "$ROOT_CA" "$CRT_FILE" > "$CHAIN_CA"

cat "$CRT_FILE" > "$CHAIN_CA"

You can watch in example-generate-jks.sh, how should params to be set. As you put all script params in the generate-jks.sh file, run command

bash ./generate-jks.sh

Now, as to script param TARGET_DIR, your .jks store file should be there. For each certificate chain / private key pair, please create a separate jks file. That's all about generating .jks.

To enable HTTPS on a server endpoint, default port 443, you need first create .jks file, as described in the previous chapter.

Then, you have to create a <server> tag for listening on port 443, specifying .jks params, exactly the same as in generate-jks.sh file.

<server
    port="443"
    alternative-port="8443"
    secure="true">
  <domain
    name="example.loc"
    jks-path="ssl/Linux/jaisocx.jks"
    jks-alias="jaisocx"
    jks-passphrase="adminpass"
    >
      <alias
        art="folder"
        url="/"
        ...
        ...

Domain tag param jks-path must contain path to stored .jks file.

jks-alias the JKS_ALIAS value in the generate-jks.sh file.

jks-pasfrase should contain the password, you've specified in generate-jks.sh file under param JKS_PASSWORD.

Please, notice, that you can create a secure conection with .jks, containing cert file for a specific domain, and exactly this domain should be published (change example.loc to your domain)

Save config, restart the server, open in browser at https://your-domain

Ready

With HTTPS enabled, <server port="443" secure="true"> in modern browsers, your website will be automatically published under HTTP/2, that is faster than HTTP/1.1

It's the matter of browser or any other HTTP client, what HTTP version to choose, to communicate with Jaisocx Web Server. The web server switches automatically to HTTP version supported by the client, e.g. Chrome, Safari, Edge, PostMan or Curl.

E.g. in Google Chrome browser, in the developer console Network tab, you can apply "Protocol" column, then you'll see after request in Protocol column, if value set to "h2", then the site is under HTTP/2.

HTTP/2 without TLS is not provided by Jaisocx, since browsers don't support HTTP/2 over plain unencrypted connection.

Jaisocx provides a way, to execute SQL queries and getting JSON response by navigating in browser to specified url. For this case, the art of the alias should be equal to "sql".

Here is the example of an SQL alias, and required for running SQL queries, jdbc connection to your database server for downloaded releases til 21th of October 2023:

<conf>
  <conf-idm path="apps/congratulations/conf/idm-conf.xml"/>
  <conf-jdbc>
    <jdbc-connections>
      <group-by-driver driver-id="MYSQL" driver-class="com.mysql.cj.jdbc.Driver" proto="jdbc:mysql://"
        port="3306">
        <group-by-url url="jdbc:mysql://localhost:3306/wp-vova">
          <jdbc-alias id="mysql" database-user-name="root" database-user-password="root"/>
        </group-by-url>
      </group-by-driver>
    </jdbc-connections>
  </conf-jdbc>
  <conf-http>
    <servers>
      <server port="80" alternative-port="2288">
        <domain
            name="localhost"
            document-root="../apps/congratulations/www"
        >
          <alias art="sql"
             url="/mysql-utf8/"
             title="MySQL"
             connection="mysql"
             transport="json"
             cache="update"
             authorization="DATABASE">
            <sql><![CDATA[
              SELECT option_id, option_name, autoload23 FROM wp_options;
            ]]></sql>
          </alias>
          ...

In the alias tag, conection attribute value should be equal to jdbc-alias tag id attribute.

Jaisocx supports currently only MySQL, Postgres, MS SQLServer, Oracle. Here are examples for jdbc connections specs for your database for downloaded releases til 21th of October 2023.

<conf>
  <conf-idm path="Application Data/applications/default/conf/idm-conf-default.xml">
  </conf-idm>
  <conf-jdbc>
    <!-- JDBC CONNECTIONS ALIASES -->
    <jdbc-connections>
      <group-by-driver driver-id="ORACLE" driver-class="oracle.jdbc.driver.OracleDriver"
           proto="jdbc:oracle:thin:@//" port="1521">
        <group-by-url url="jdbc:oracle:thin:@//127.0.0.1:1521/ORCLPDB1">
          <jdbc-alias id="orcl" database-user-name="SYSTEM" database-user-password="root"/>
        </group-by-url>
      </group-by-driver>
      <group-by-driver driver-id="MYSQL" driver-class="com.mysql.cj.jdbc.Driver" proto="jdbc:mysql://"
           port="3306">
        <group-by-url url="jdbc:mysql://localhost:3306/WpTest">
          <jdbc-alias id="mysql" database-user-name="root" database-user-password="root123"/>
        </group-by-url>
      </group-by-driver>
      <group-by-driver driver-id="MICRSOSFTSQLServer" driver-class="com.microsoft.sqlserver.jdbc.SQLServerDriver"
           proto="jdbc:sqlserver://" port="51570">
        <group-by-url url="jdbc:sqlserver://localhost:51570;databaseName=jaisocx-testing;encrypt=false;">
          <jdbc-alias id="mssql" database-user-name="root" database-user-password="root"/>
        </group-by-url>
      </group-by-driver>
      <group-by-driver driver-id="POSTRESQL" driver-class="org.postgresql.Driver"
           proto="jdbc:postgresql://" port="5432">
        <group-by-url url="jdbc:postgresql://localhost:5432/postgres">
          <jdbc-alias id="postgres" database-user-name="postgres" database-user-password="root"/>
        </group-by-url>
      </group-by-driver>
    </jdbc-connections>
  </conf-jdbc>
  <conf-http>
    <servers>
      ...
      ...

From 22th October 2023, Jaisocx supports also sqlite3 database. And here is the example of newer connection specification in the config.xml

The value of <connection driver="" should be one of the constants: mysql, oracle, sqlserver, postgresql, sqlite3.

<conf>
  <conf-idm
    path="Application Data/applications/default/conf/idm-conf-default.xml">
  </conf-idm>
  <conf-jdbc>
    <connection
      driver="mysql"
      url="jdbc:mysql://localhost:3306/cv"
      id="mysqlillia"
      user="root" password="root" />
    <connection
      driver="oracle"
      url="jdbc:oracle:thin:@localhost:1521:xe"
      id="orcl"
      user="system" password="oracle" />
    <connection
      driver="sqlserver"
      url="jdbc:sqlserver://localhost:51570;databaseName=jaisocx-testing;encrypt=false;"
      id="mssql"
      user="root" password="root" />
    <connection
      driver="postgresql"
      url="jdbc:postgresql://localhost:5432/postgres"
      id="postgres"
      user="postgres" password="root" />
    <connection
      driver="sqlite3"
      url="jdbc:sqlite:/home/illia/Documents/JAISOCX/WEB/jaisocx-current/sqlite3-dbs/jaisocx-test.db"
      id="sqlite3"
      user="" password="" />
  </conf-jdbc>
  <conf-http>
  <servers>
    ...
    ...

Jaisocx doesn't create cached JSON on server startup, that is why, if you'd like to have JSON in 3ms instead of 900ms, just use alias attribute cache="first-call". In such case, on first url call, the database query will be executed, and JSON result will be stored in cache, performing on further calls to this url very fast responses from cache.

Here is an example, how you can pass request parameters to sql statement.

Supposing, you access sql-to-json endooint in browser or js function with following url: "https://example.com/with-params?option1=siteurl&option2=whatever"

<alias
  url="/with-params"
  art="sql"
  connection="orcl"
  cache="update">
  <sql><![CDATA[SELECT * FROM wp_options
    where option_name like ? or option_name like ?;]]>
  </sql>
  <arg
    position="1"
    sql-type="VARCHAR"
    request-field-name="option1"/>
  <arg
    position="2"
    sql-type="VARCHAR"
    request-field-name="option2"/>
</alias>

with jwt payload and POST body json objects, you can use json paths for accessing json children like, e.g. request-field-name="$json.cities[0].name", to pass as parameter strigified JSON representation, you can write this: request-field-name="$json.{}" or request-field-name="$jwt.{}"

Here is an example, how to pass as a sql query parameter, the POST request body JSON property, e.g. named "option_name", or Authorization http request header json web token payload property, e.g. named "user".

<alias
  url="/with-params"
  art="sql"
  connection="orcl"
  cache="update"
  authorization="jwt"
  jwt="jwt-by-idm-1">
  <sql><![CDATA[SELECT * FROM tb_example
    where user_name like ? and option_name like ?;]]>
  </sql>
  <arg
    position="1"
    sql-type="VARCHAR"
    request-field-name="$jwt.user"/>
  <arg
    position="2"
    sql-type="VARCHAR"
    request-field-name="$json.option_name"/>
</alias>

Jaisocx web server provides a way to secure an url with Basic authoriazation method. For securing an url, provide in according alias tag folowing atributes: authorization="basic"

The username and pass for accessing such resource, is specified in idm-conf.xml configuration file. Here is an example of an idm-conf.xml file, specifying user with username "admin" and password "adminpass", having access rights for example to secured url, located under localhost:80/

Please notice, that a granted alias url should contain the port number, always.

<conf-idm>
  <user
    id="admin"
    password="adminpass"
    granted-roles="auth1" />
  <role
      id="auth1">
    <granted-alias
      url="localhost:2288/" />
    <granted-alias
      url="localhost:80/" />
  </role>
</conf-idm>

Jaisocx web server provides an easy way to secure an url with JSON web token with minimum configuration needed by default, and wide range of customization possibilities. The example conf.xml configuration snippet is here:

<conf>
  <conf-idm
    path="Application Data/applications/default/conf/idm-conf-default.xml"/>
  <conf-jdbc>
    <connection
      driver="mysql"
      url="jdbc:mysql://localhost:3306/mydb"
      id="mysqlconn-1"
      user="root" password="root" />
  </conf-jdbc>
  <conf-jwt>
    <jwt
      id="jwt-config-1"/>
    <jwt
      id="jwt-database-1"
      users-storage="database"
      connection="mysqlconn-1"
      users-table="users"
      login-cols="email,username,phone"
      pass-col="password"
      pass-hash-alg="SHA-256"
      active-col="active"
      jwt-payload-cols="id,username,email,roles,country_code"
    />
  </conf-jwt>
  <conf-http>
    <servers>
      <server
        port="443"
        alternative-port="8443"
        secure="true">
        <domain
          name="example.com"
          jks-path="path-to-.jks-file"
          jks-alias="alias name in the .jks file"
          jks-passphrase="jksfilepassgoeshere"
        >
          <alias
            art="jwt-login"
            url="/login"
            jwt="jwt-config-1"
          />
          <alias
            art="sql"
            url="/api/setting"
            cache="update"
            publish-charset="UTF-8"
            authorization="jwt"
            jwt="jwt-config-1">
            <sql>
              <![CDATA[SELECT * FROM tb_settings where user=? and setting_name=?;]]>
            </sql>
            <arg
              position="1"
              sql-type="VARCHAR"
              request-field-name="$jwt.user" />
            <arg
              position="2"
              sql-type="VARCHAR"
              request-field-name="setting_name" />
          </alias>
        </domain>
      </server>
    </servers>
  </conf-http>
</conf>

How to apply JWT security

The Short Steps Summary

1. create <jwt ... /> node with jwt configuration attributes.
2. create <alias art="jwt-login" .../> for login.
3. secure desired URLs by aliases attributes <alias url="..." art="..." authorization="jwt" jwt="jwt-config-1" ...
4. grant access to desired roles and/or users to secured URLs in <conf-idm .../>

Step By Step

If You need to restrict access to a URL with sensitive information, for example JSON from a SQL query to Your database.

Let's do some steps in Your configuration .xml file:

1. First, create a JWT configuration node in Your conf.xml:

   <conf-jwt>
     <jwt id="jwt-config-1"/>
   </conf-jwt>    
               

2. Create URL, where Your web application can login, and get JSON Web Token in the response. We just need at some of Your domain node create an alias node for this:

   <alias
     url="/login"
     art="jwt-login"
     jwt="jwt-config-1"
   />
               

3. For getting a new JSON Web Token, Your web app should send POST request with JSON payload to jwt-login alias URL https://your-domain.com/login:

   {
     "login": "user's login", 
     "password": "user's password"
   }
               

4. For login and password values You can use the user's credentials stored in idm-conf.xml, as described in "Authorization Basic" section.
5. If You'd like to use users' credentials from Your database, refer to documentation section Config.xml -> jwt. Please read info on optional jwt node attributes, if is set <jwt users-storage=”database”.
6. Notice Never publish jwt-login URL with unencrypted plain HTTP server. Use only secured endpoint over HTTPS, otherwise the users' credentials then during login in the POST JSON request payload would be sent unencrypted over Internet.
7. Let's assume, Your web application made POST HTTP request with JSON payload as described above, and You have the JSON Web Token in the response from https://your-domain.com/login like this:

   {
     "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFuZDBMV2xrYlM1U1V6STFOaTR5T0RVNE1EY3dNQT09In0.eyJpc3MiOiJkZXYzLmphaXNvY3guY29tIiwiaWF0IjoiMTcxNDg0NDI4OCIsImV4cCI6IjE3MTQ4NDU0ODgiLCJyb2xlcyI6IlJFQURFUiIsInVzZXIiOiJpbHVzaGEifQ.rYLZ6S+mcnPYPT0VWR1CWT6pwWsxsABUp8xEUIHqSFZjtmq56Ap9EIj51uzGD331mb+KlBjLf8k1aryB7tKqnrvolpU7h5cYyv2XslgsoZRW27VDcbs09EYzXTyhWFYoRRHTf50OOCwHsFRy/UxXxhl5PEHdxb9TMbG16/LXEXe6KAtsi8ZG5OHj/503FqpSjx1/2bYG0kTsf+qSaFBfOpYhUuvSHBXdMmqx4RBI+Uc3Xit7GjNWRtLwcWAUQpQMWoL4ASluzG/dOrmy9Fyslv7xtxQNojJp0GHFNBpaFp8kX9cUd4AbADrAfNcQIXstT4Sr0GXzzpU6akXqUoA/cw",
     "expires": "1714845488"
   }

8. Now, Your web application can use this JSON Web Token to authorize at You secured endpoints. For this, Your web application in the requests to secured endpoints should pass request header like this: Authorization: Bearer <your-token>. On failure You get HTTP response status 401. On success response code 200 and the contents, published at the secured endpoint.
9. To secure Your endpoint, You should at any of Your web application aliases, set attributes authorization and jwt like this:

   <alias
     url="...
     path="...
     art="...
     authorization="jwt"
     jwt="jwt-config-1"        
   />
               

10. Don't forget, please, to grant access to this secured endpoint to the user in conf-idm. This will be explained in the next section "Users and Roles". A user with a valid JSON Web Token, but without granted access to an URL, will not get contents of the secured endpoint, and will get HTTP response status code 401.

In Your Jaisocx install, at path "apps/congratulations/conf/idm-conf.xml", You can define users with their credentials, and define roles hierarchy. "idm" stands for "Identity Management", and "conf" for "configuration" (or "confiserie"). A user can have granted roles list, and each role can have granted other roles list. Each role can have granted on your published domain url resource with optionally request http method allowed like only "GET" or "POST" and so. Here goes the example idm-conf.xml snippet, explained below.

<conf-idm>
  <user
    id="admin"
    password="strongadminpass"
    granted-roles="ADMIN" />
  <user
    id="reader"
    password="strongreaderpass"
    granted-roles="READER" />
  <role
    id="READER">
    <granted-alias
      url="dev.jaisocx.com:8443/api/${any}"
      methods="GET">
    </granted-alias>
  </role>
  <role
    id="ADD"
    granted-roles="READER">
    <granted-alias
      url="dev.jaisocx.com:8443/api/${any}"
      methods="POST">
    </granted-alias>
  </role>
  <role
    id="REMOVE"
    granted-roles="READER">
    <granted-alias
      url="dev.jaisocx.com:8443/api/${any}"
      methods="DELETE">
    </granted-alias>
  </role>
  <role
    id="EDITOR"
    granted-roles="ADD,REMOVE">
    <granted-alias
      url="dev.jaisocx.com:8443/api/${any}"
      methods="PUT,PATCH">
    </granted-alias>
  </role>
  <role
    id="ADMIN"
    granted-roles="EDITOR">
  </role>
</conf-idm>

Any role can inherit other roles, and the allowed for them urls and the request http methods. A role node can have multiple <granted-alias nodes. methods attribute is optional. If not set, then all http methods are allowed. The /${any} reserved key stands for any url. e.g. when a role "READER" has defined <granted-alias url="example.com:443/api/${any}"/>, then url https://example.com/api/settings will be also allowed for the successfully authorized user with role "READER" granted. Please note, that <granted-alias url starts with domain name, without https:// before, and should always have port specified, even if this is a default port.

Proxy is the bypassing endpoint. It just retransmits the requests from a browser to another server, and the domain name in the browser address bar is of the proxy endpoint.

Supposing, there is an endpoint at the domain example.com. Proxy endpoint is hosted at domain www.proxy.com. As an inet surfer accesses in the browser url https://www.proxy.com/, she/he sees the contents of the site, published on https://example.com/.

<domain name="www.proxy.com">
  <alias art="proxy"
    url="/${any}"
    path="https://example.com/"
  />
</domain>

If You'd like to proxy Your site, be sure, the site pages don't contain absolute links. E.g. on the webpage on https://example.com/ there styles, scripts and images referenced by relative urls, without domain name, like this:

<img src="/images/logos/company-logo.webp" />

Here you specify a jwt tokens generation and handling parameters. These parameters will be used for a secured with jwt token alias, if the alias has attribute set authorization="jwt" jwt="<id-of-jwt-node>". The most of attributes are optional, so you need only few minutes to get your endpoints be secured with jwt.

The server node is for defining servers, running on a single port. Here can be defined server port and secure encryption option.

Here you define properties of the domain, published at server's port.

Here you specify a resource that is published at a specific url.

{
  "login": "user's login", 
  "password": "user's password"
}

{
  "user": "user's login", 
  "password": "user's password"
}

{
  "login": "user's login", 
  "password": "user's password"
}

{
  "login": "user's login", 
  "secret": "user's password"
}

the file, located in the server installation root folder under etc/server.properties has the main server engine configuration options that can be configured. In this section You'll get explaination on the meaning of each server.properties file config line.

#with app.env=dev mode, the server issues more detailed logs.
app.env=dev
#app.env=prod
#app.env=test

# here is the path to http-conf.xml file, where the running server
# endpoints, domains and published resources are specified
app.config.file=apps/congratulations/conf/http-conf.xml


# this property sets timeout in seconds, after that the inactive connection will be colsed
keepalive.connection.timeout=60


# this property sets the maximal amount of active connections
keepalive.connectionspool.maxcount=10000


# this property sets the supposing slowest traffic speed in Kilo bits per second
# for calculations of avoiding being closed connections on timeout, if a heavy load is in progress
keepalive.slowest.load.kbits=50


# it's the seconds timeout for the initial reading operations on socket.
# if the socket is waiting longer, the socket will be closed.
so.timeout.initial=15

# after starting successfull http connection,
# each single connection will live maximum this number of seconds.
# after this timeout, any hanging or live connection
# from any browser will be killed.
# so, if a larger downloads are provided, then increase
# this value to allow a connection to live longer,
# but then you can have more hanging connections,
# wasting server's memory usage.
# 300 stands here for 5 minutes connection life time.
so.timeout.http2=300

# PHP-FPM settings
# address, where php-fpm service is listening
php.fpm.host=localhost:9000

# php-fpm output charset, is like source-charset for the jaisocx
php.charset=UTF-8

# php scripts running timeout
php.so.timeout=30000

# whether to display php errors in the http content or not
php.errors=true

# maximal number of post parameters in your php application
post.params.max=1000

# default size of a video content block, asked by browser
# during playing video. can be set higher,
# if your internet bandwidth is high,
# it'll be then better for performance
# and the server will have more time
# betwen video blocks sending to serve other clients.
# lower block size suits at low internet bandwidth,
# and causes the more often
# requests to server for video blocks sending.
# size dimensions constants can be B, K, M or G
# for bytes, kilobytes, megabytes, gigabytes.
video.block.size=1.4M