images/download/attachments/13272721/db3-module-webhosting.PNG

Content

Introduction

With the Webhosting module you can host your website at ApiOmat. Starting from a simple static landing page for your product to a full-featured web frontend of your app – everything is possible. You can use HTML, CSS, Javascript files, images, and of course all sorts of binary data. PHP and CGI scripts are not supported.

Key Capabilities

Capability	Description
Provide Web Hosting Space	Provides web hosting space on your ApiOmat instance for publishing web pages and files
Upload File	Provides an interface to upload files to your web hosting space
Upload and unpack ZIP archive	Provides an interface to upload and unpack zip archives to your web hosting space
Copy SDK	Provides an interface to copy the your SDK to the web hosting file system
Read File / Directory	Provides an interface to read a specific file or directory on your web hosting file system
Read File / Directory by Session Token	Provides an interface to read a specific file or directory on your web hosting file system authenticated for specific user by session token
Delete File	Provides an interface to delete a specific file from your web hosting file system
Delete Directory	Provides an interface to delete a specific directory from your web hosting file system

Module Setup & Configuration

In order to have access to files that were uploaded to the web hosting module you need to configure the Read Role:

Config name	Config value
Read Role	Possible values: `Guest,User,` or `AppAdmin` (Default: `Guest`)

The Read Role is configurable via Dashboard since ApiOmat 2.5.

Setup

To set up the WebHosting Module you need to configure your ApiOmat instance via apiomat.yaml .

Setup Ports

On a new installation, the FTP connection can be used on default port 2021.
Customized ports, including passive ports, can be set up in the apiomat.yaml using the keys yambas.ftp.port or yambas.ftp.passivePorts.

The passive ports setup may contain the following formats:

2300 : only use port 2300 as the passive port
2300-2399 : use all ports in the range
2300- : use all ports larger than 2300
2300, 2305, 2400- : use 2300 or 2305 or any port larger than 2400

Setup FTP over TLS

Enabling SSL for a FTP over TLS encryption will require a keystore, which can be created using the following command (more information can be found here: https://docs.oracle.com/cd/E19509-01/820-3503/ggfen/). The keytool binary can be found in the JDK installation bin directory.

keytool -keystore WebhostingKeystore.key -genkey -keyalg RSA

Just fill in the certificate details and use the provided password as key password at the end (do not provide a second one). Afterwards, a WebhostingKeystore.key keystore file will be written to the current directory.

Now, specify the path to the recently created keystore file in the yambas.ftp.keystore.path config value and enter the password at the yambas.ftp.keystore.password config. After that restart yambas.

Setup Limits

Furthermore the following limits can optionally set up within the apiomat.yaml:

yambas.limits.maxDataUploadMB - the maximum upload size in MB (default: 200)
yambas.ftp.maxlogins - max number of parallel logins (default: 1000)
yambas.ftp.idleTimeout - idle timeout to close connection in milliseconds (default: 20000)

Usage

After adding the module to your app, you have two possibilities to manage the files contained in your hosted environment: REST and FTP. The path/directory structure you use managing these files are also used to access them via browser.

The base path for accessing your files is http://<hostname>/yambas/rest/web/<your_apps_name>/<used_system>

So, if you create a file hello.html at path subdir for your app named MyApp on system LIVE, it would be accessible through the URL http://<hostname>/yambas/rest/web/MyApp/LIVE/subdir/hello.html

Default file: index.html

If no file name was specified, Webhosting Module tries to return an index.html file.

Management by REST

The REST API for this module provides methods to

upload a file
upload a zip containing all files, which will get unzipped on server
copy the current Javascript SDK of your app straight to your webhosting environment
read a file or directory
read a file or directory authenticated by user session token
delete a file or the whole directory

You can try out some of these methods on our REST API documentation page. Also you can use CURL to call all REST APIs.

REST Examples

The following CURL examples show you how to interact with REST API:

Upload a file:

curl -X POST --header 'Content-Type: application/{MIME-TYPE}' --header 'Accept: application/json' --header 'X-apiomat-system: {SYSTEM}' --header 'If-None-Match: false' --header 'Authorization: Basic {BASE64-ENCODEDAuth}' \n --data-binary "@{FILE}" 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}{file}'  

Upload a zip containing all files, which will get unzipped on server:

curl -X POST --header 'Content-Type: application/zip' --header 'Accept: application/json' --header 'X-apiomat-system: {SYSTEM}' --header 'If-None-Match: false' --header 'Authorization: Basic {BASE64-ENCODEDAuth}' --data-binary "@{ZIP-FILE}" 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}'

Copy the current SDK to the web hosting file system:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/html' --header 'X-apiomat-system: {SYSTEM}' --header 'If-None-Match: false' --header 'X-apiomat-apikey: {APIKEY}' --header 'Authorization: Basic {BASE64-ENCODEDAuth}' 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/copySDK'

Read a file:

curl -X GET --header 'Accept: application/octet-stream' --header 'X-apiomat-system:  {SYSTEM}' --header 'If-None-Match: false' --header 'Authorization: Basic  {BASE64-ENCODEDAuth}' 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}{file}'

Read a directory:

curl -X GET --header 'Accept: application/octet-stream' --header 'X-apiomat-system:  {SYSTEM}' --header 'If-None-Match: false' --header 'Authorization: Basic  {BASE64-ENCODEDAuth}' 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}/'

Read a file authenticated by user session token:

In order to call this REST end point you have to first configure a session token for the user that should get access to the file resource. This can be reached by using Dashboard's Data Editor. Simply update an user's entry by adding a string into to sessionToken column.

Alternatively you can use OAuth2 to define a user session token by following the guide ApiOmat and OAuth2 .

curl -X GET --header 'Accept: application/octet-stream' --header 'X-apiomat-system:  {SYSTEM}' --header 'If-None-Match: false' 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}{file}?token={sessionToken}'

Read a directory authenticated by user session token:

In order to call this REST end point you have to first configure a session token for the user that should get access to the file resource. This can be reached by using Dashboard's Data Editor. Simply update an user's entry by adding a string into to sessionToken column.

Alternatively you can use OAuth2 to define a user session token by following the guide ApiOmat and OAuth2 .

curl -X GET --header 'Accept: application/octet-stream' --header 'X-apiomat-system:  {SYSTEM}' --header 'If-None-Match: false' 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}/?token={sessionToken}'

Delete a file:

curl -X DELETE --header 'Accept: text/html' --header 'X-apiomat-system:  {SYSTEM}' --header 'If-None-Match: false' --header 'X-apiomat-apikey:{APIKEY}' --header 'Authorization: Basic  {BASE64-ENCODEDAuth}' 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}{file}'

Delete a whole directory:

curl -X DELETE --header 'Accept: text/html' --header 'X-apiomat-system:  {SYSTEM}' --header 'If-None-Match: false' --header 'X-apiomat-apikey:{APIKEY}' --header 'Authorization: Basic  {BASE64-ENCODEDAuth}' 'http://{YOUR_BASE_URL}/yambas/rest/web/{appName}/{system}/{path}'

REST Authorization

For a Basic authentication the basic header is a BASE64 string. The string has the following structure:

Auth BASE64 string

user@domain.com:password

Alternatively the common option '-u' can be used to authenticate the user.

Management by FTP

If you like to access your data like known from other hosting services, just connect to ApiOmat via FTP. The connection parameters are:

User name – Your ApiOmat username
Password – Your ApiOmat password
Host – Your hostname of ApiOmat installation
Port – 2021, or any other port defined in the apiomat.yaml/yambas.conf file
Protocol – FTP
Encryption – ‘explicit FTP over TLS’ or ‘none’

images/download/attachments/13272721/ftpConnect.png

You can choose to use encryption or not by setting the Encryption parameter. Please be aware that SFTP is NOT supported!

Limitations

The Webhosting module is available in all paid plans.

PHP and CGI scripts are not supported

renaming files is currently not supported. enaming files is currently not supported (renaming files is currently not supported

(renaming files is currently not suppor