. . .

Webhosting Module

images/download/attachments/14614710/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 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/14614710/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.