Course13:IT Advanced - 05 Setting up the Application Platform

From innovaphone wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

How to set up the AP manually

Prerequisites

You can run the App Platform on a hardware box (such as your IP411 or IP811) or you can run it as a virtual machine in a VMware or Hyper-V environment.

Let's look at installing it on your IP411LEFT. The only thing that is required to do so is to install an SSD. We recommend to use at least 32GB of SSD size. Roughly 2 GB are used by the operating system, so that would leave you with 30GB of usable space for Apps and their data.

Of course, if you do this course as an on-site course or you have already used your equipment in an IT Connect training, then you already have the SSD installed!

Installing the basic Application Platform

The Application Platform (AP) actually is an extremely light-weight Linux kernel with a number of Apps running on top of it. These Apps (technically spoken: Linux processes) are controlled (that is, started and stopped) by a component called Platform Manager. They communicate with other parties (for example, the end-users myApps clients) through web-socket connections handled by a specialized web server on the AP.

Please click the load button so moodle knows that you started this book: Setting_up_the_application_platform

(Further Hints) You will see a note to the effect that the APPPLATFORM is missing. Something like:
07.03.2023 15:12:26.6341 0.000 0000.992 runtime script: APPPLATFORM: offline
You can safely ignore this for now!
However, if other devices show up as offline, please keep waiting (and refresh the Devices page from time to time).

Enabling AP support

The SSD of your box is normally used by the built-in web server to provide a WebDAV drive (which is available as http://172.31.31.2/DRIVE/CF0), so it is not available for the AP.

To use the SSD for the AP instead of for the WebDAV drive
  • click screenshot.png on Enable App Platform support in App-Platform / General (if not yet done and App Platform support is not enabled is shown).
    Ascreenshot.png reset required message appears and you need to reset the box to have the setting take effect. As soon as the box is online again, the App Platform/General menu will have much more sub-menus and also the App Platform/General form now has a number of properties which can be set
(Further Hints) If you proceed, all data will be erased from the SSD!
     

The APs IP address

As the AP is a separate Linux system running on your box, it has its own network interface and hence needs a separate IP address. We recommend to use DHCP along with a proper reservation for your AP.

To set up the reservation on your DHCP server, you need to know your AP's MAC address. This is the MAC address of the box you are using (this would be 00-90-33-40-00-B3) with the first 00 replaced by 02. So in your case, it's 02-90-33-40-02-B3.

Fortunately, moodle has already prepared our little training DHCP server in IP4 / ETH1 / Leases with a reservation for the AP (called App Platform IP411LEFT). In real life, you would need the customers network administrator to provide it.

To turn on the DHCP client on the AP to be installed, screenshot.png change Interface for DHCP to ETH0 in App-Platform / IP.


We stated above that the AP has its own network interface. However, if you look at your box, there is no extra physical socket for this interface (there is only ETH0 and ETH1, which are the two network interfaces used by the standard firmware of your box). In fact, the AP's network interface is bridged internally. Therefore, you need to set the physical interface of the box you want the AP to use (usually ETH0) in to Proxy ARP mode.

You do this by ticking screenshot.png the Proxy ARP check-mark for the physical ethernet interface you intend to use. In our case this is IP4 / ETH0.

(Further Hints) Don't forget to reboot your box again (as indicated by screenshot.png the reset required message)!


Downloading the AP

The next step to install the AP is to download the operating system, Platform Manager and Web Server. This is done directly from the box you want the Application Platform to run on.

(Further Hints) As we will install the AP on the IP411LEFT, an SSD must be installed in it. Fortunately, in your training equipment in the on-site course, this already has been done. If you do the course on-line, make sure you have your own SSD installed (see https://class.innovaphone.com/moodle2/pix/f/pdf.gif How to install an SSD in your IP411 for some hints).

The box will suggest an URL to download the image of the latest-greatest version of the system from (something like https://store.innovaphone.com/release/download/app-platform/XXXXXX/app-platform-armel.img). But how does it know this version?

AppStore structure


Let's look into how an App Store works a bit. The App Store is reached through an URL (for example, link_intern.png store.innovaphone.com: release/download.htm which is the standard innovaphone release App Store). In this place (which is hardwired to the firmware of the box), you find a number of JSON files which describe what can be found in that store. One of these files is link_intern.png store.innovaphone.com: release/download/linux.json. As the name suggests, it defines the Linux (a.k.a. AP) files available. When you download it, you'll find something like

{
"platforms": [{
"id": "arm",
"text": "App Platform ARM",
"file": "app-platform/110026/app-platform-armel.img",
"update": "app-platform/110026/update-armel.img",
"version": "110026"
}, {
"id": "arm64",
"text": "App Platform ARM64",
"file": "app-platform/110026/app-platform-arm64.img",
"update": "app-platform/110026/update-arm64.img",
"version": "110026"
}, {
"id": "x86_64",
"text": "App Platform x86_64",
"file": "",
"update": "app-platform/110026/update-x86_64.img",
"version": "110026"
}],
"devices": [{
"id": "IP0011",
"platforms": ["arm"]
}, {
"id": "IP3010",
"platforms": ["arm"]
}, {
"id": "IP3011",
"platforms": ["arm"]
}, {
"id": "IP311",
"platforms": ["arm"]
}, {
"id": "IP411",
"platforms": ["arm"]
}, {
"id": "IP511",
"platforms": ["arm"]
}, {
"id": "IP6010",
"platforms": ["arm"]
}, {
"id": "IP810",
"platforms": ["arm"]
}, {
"id": "IP811",
"platforms": ["arm"]
}, {
"id": "IP0013",
"platforms": ["arm64"]
}, {
"id": "IP6013",
"platforms": ["arm64"]
}]
}

This is to say that there are APs for the IP0011, IP3010, IP3011, IP311, IP411, IP6010, IP810, IP811, IP0013 and IP6013. Some of them use the arm platform, some the arm64 platform. The image for these platforms can be found at app-platform/110026/app-platform-armel.img (or app-platform-arm64.img). This is how the firmware determines the currently released version of the AP and where to download it.

There are similar .json files which describe the link_intern.png firmware and link_intern.png Apps currently available.
(Further Hints) But don't be afraid if this looks all Greek to you wink For now it is enough to understand that the files available in an App Store are controlled by some .json files specifying what is available and on which path. So if you ever run into issues where you can't download a file from the app store (for example, if you have set up your own), this is the time to dig into this a bit deeper wink

Using your own AppStore

You sometimes will want to use a different AppStore (for example, when your device do not have access to store.innovaphone.com). You can do this by simply changing the URL property to where the AP Linux image is on your AppStore.

As we indeed want to use moodle's AppStore (so we always get the versions used in the training) we will exactly do this. So enter http://class.innovaphone.com/moodle2/webbuild/store.php/1-3/app-platform/0/app-platform-armel.img screenshot.png as URL and click on the Install button.

The box will now download and install the AP. When it is done, you will see the message
Installation finished!
App Platform booted
You can now switch to the App Platform/General tab and see that
  • Status is App Platform processor active
    This basically says that the AP support is enabled and the box's second CPU (which is used to run the AP) is started
  • Boot status is App Platform booted
    This indicates that the Linux kernel has booted successfully and also has started the platform manager
  • the Autostart App Platform check-mark is ticked
    So the AP will be started whenever the box is booted
The fields Kernel file (kernel-armv7te), Initrd file (empty) and Kernel command line (root=/dev/sda3) should never be changed unless you really know what you are doing.

For more details, see fish-help.png App Platform/General and fish-help.png Concept App Platform.

Logging in

The AP is now ready to accept a log-in to its Web user interface. It can be reached using its domain name (https://apps.dvl-ckl2.net) or IP address (172.31.31.12).


Trusting the Web user interface

When you click on either of the links above, you will probably see your browser complain that accessing it is a security risk. This is because the AP web server has a self-signed certificate installed, which is not trusted by the browser. We will see later how to replace it with a trustworthy certificate. For now, you screenshot.png can convince your browser that you accept the risk and want to access the site anyway.

The default password to log in to the AP via the Web UI (the so-called AP Manager password) is pwd.

The user interface you see is familiar to you from the IT Connect course. It is what you see when you opened the screenshot.png AP Manager App in myApps.

Setting the AP passwords

  • the AP Manager password
    This is required to log-in to the Web UI and also to link a PBX to the AP (we will discuss this later). The default is pwd, no user name required
  • the Linux admin user
    This is required to log-in to the AP using SSH. Note that you will never need this in normal operation (only if some emergency repair work needs to be done). Nevertheless, an attacker might (and probably will) try to exploit a weak password here. The default user is admin(cannot be changed), the default password is ipapps
  • the Linux root password
    This is required to perform restricted commands on the SSH command line. As before, you will never use it in normal operation. The user is root (and you cannot change it), the default password is iplinux
(Further Hints) Of course you don't want to leave those passwords as is. The Install would set them to the highly confidential, very secure password it randomly creates for your installation.

Fortunately, even though we don't use the Install here, the three passwords will be set to secure values later on by the Devices App. We will see how this works later.

For now, we only change the AP Manager password. You will find the place to do that when you open the screenshot.png Security tab in the Platform Settings. Set the screenshot.png AP Manager password to ip411 please !

Setting our private App Store

While we are at that: we also want to use moodle's App Store to install Apps later on. Using a private App Store is configured in the AP by setting the App Store URL to the URL of the apps.json file on your App Store.

To use moodle's App Store, set http://class.innovaphone.com/moodle2/webbuild/store.php/1-3/apps.json screenshot.png as App store URL.

Making your AP known to moodle

While we are at it. In order for moodle to be able to see your devices (to check the configuration you have done), these devices need to connect to moodle. This is actually the same mechanism that your devices use to connect to your Devices app!

For this to work, you need to tell your AP how to reach moodle. The URL for this is set in the Devices app URL 2 field in the Settings / General. Obviously you wouldn't do this in real life.

For now, you don't need to understand what exactly is going on here, just configure wss://training-apps.training.innovaphone.com/class.net/Trainee-Devices/sysclients in the Devices app URL 2 field and you're done.

(Further Hints) As soon as you have done this correctly, the complaint about the missing APPPLATFORM on the Devices page will disappear.

Using the command line

As said before, you should never need to use this. However, for disaster recovery it is useful to know how you'd do it if you need to wink

Access to the command line is done using the SSH protocol. You will therefore need an SSH-client. We recommend to use WinSCP (which you anyway want to use as a WebDAV client) in conjunction with putty. Both are linked on our download.png Recommended Tools for this Course page.

(Further Hints) If you have installed putty and WinSCP, this link should work for you: SSH client for your AP (ssh://172.31.31.12). Otherwise you can simply start your favorite SSH client.

We are not going to have a unix basics course here, but let's at least try to log in and do some basic commands:
  • video2.png connect to apps.dvl-ckl2.net or 172.31.31.12 and log in as admin with password ipapps. You will see what's called screenshot.png the command prompt now. It shows who you are (admin@app-platform) and where you are (/mnt/sda2/home/admin)

  • You video2.png can change the place you are (a.k.a. the current directory) using the cd command. Try

    cd /etc/init.d

    and you will notice that the prompt changes to admin@app-platform|/etc/init.d>, reflecting the new working directory. So when a support guy someday says "go to /mnt/sda2/log/apps/manager" then you know how to do it

  • to video2.png list the content of a directory you can use the ls command. Just type

    ls

    and you will see a list of files in your current directory. Type

    ls -l

    to see the same list with more details for each file. Finally type

    ls /mnt/sda2/log/apps/manager

    to see the list of files in that directory

  • df is another interesting command. video2.png Type

    df

    to see the current disk usage split up by logical device. The device you are probably interested in is /dev/sda2 by the way (this is where all the live data is written to)

  • the rm command (shorthand for remove) removes files and should be used with some care obviously. Sometimes however it is useful to remove large log files. video2.png You could try

    rm /mnt/sda2/log/apps/manager/*.txt

    the rm command will ask you if you're sure and you need to confirm with y (for yes):

    admin@app-platform|/mnt/sda2/log/apps/manager> rm /mnt/sda2/log/apps/manager/*.txt
    rm: remove '/mnt/sda2/log/apps/manager/manager-2019-11-01T15_44_22Z_641.txt'? y

    but then it will find out that it can't remove the file(s):

    rm: can't remove '/mnt/sda2/log/apps/manager/manager-2019-11-01T15_44_22Z_641.txt': Permission denied

  • as you have seen, the things you may do using the admin account are limited. To have unlimited access, you need to elevate yourself to being root. video2.png Do this by typing

    su root

    as soon as you have provided the password for the root account (remember, this is iplinux by default) you will see that the prompt changed to root@app-platform|/etc/init.d>, reflecting the new user (you can actually omit root, in the command, so you just type su, as root is the default account then). As root is the Linux super-user, you now can do everything on your AP, good and bad!

    So you now could remove the log files as shown above. It'll work. Of course, you can also just trust me and do it only when you really need to

  • but you can now try a variation of the df command which is called du. Change to the /mnt/sda2/log directory by typing

    cd /mnt/sda2/log

    here you find a number of sub-directories (try the ls command to see them!) where all kinds of log files are stored. video2.png The command

    du -h

    will show you the screenshot.png disk usage split up by directory

  • to terminate the elevated command prompt, video2.png type

    exit

    (see how the prompt changes back). The su command has stacked a new command prompt (unix'ish this is known as interactive shell) for root on top of your initial command prompt for admin. The exit command terminates the command prompt.

    (Further Hints) You can also do just one elevated command by typing sudo -u root cmd. For example, the whoami command (which tells you who you are) will output admin when you call it now. However, if you call

    sudo -u root whoami

    it will output root (as it will elevate you to root, execute the whoami command and then fall back to admin's privileges again)

  • to log out, you must terminate the outermost (that is, initial) command prompt. video2.png Simply type

    exit

    and your SSH session will be closed. If you still see a prompt, you probably have stacked another shell (for example using the su command). Just type exit again until you are logged off
(Further Hints) The list of Linux commands is even in our lightweight kernel quite long. But as said before, you should never need them anyway. However, if you need to proceed like advised by innovaphone support staff or as recommended in our wiki for disaster recovery, then it is good if you at least know how to log in and -out.

Adding Apps

We have set up the basic AP already. That wasn't too hard.

However, if you start myApps now (you can do that using the URL /PBX0/APPCLIENT/131375/appclient.htm?lang=en and use john.doe as Username and ip411 as Password) you video2.png will see no Apps at all. Even if you click on Add some apps -> you will find that there are none.

Let's see how to fix that.

PBX Apps

As we already have seen in the IT Connect training, some Apps are actually hosted in the PBX instead of the AP (for example, the PBX Manager Apps). So these Apps should appear in John Doe's myApps client (as the PBX is already there and therefore their Apps should be there too) - but they don't. Why is that?

As you might recall from the IT Connect training, Apps are only available if they are assigned to a user in the Apps tab of the User object (or in the Apps tab of a Config Template PBX object that the user is inheriting). So far, we have screenshot.png not assigned any App to John Doe.

Fix this by screenshot.png ticking the pbxmanager check-mark in John Doe's Apps tab.

When you now open John Doe's myApps client (john.doe, ip411) you will find the PBX Manager App in the Add some apps -> area and can screenshot.png add it to his home screen.

To make Apps available which are hosted on an AP, more needs to be done.

Updating the basic AP services

To be able to access Apps hosted on an Application Platform, we need an App Service on this AP to begin with. So far, our AP is just empty, no App Services and hence no Apps at all. So let us begin with installing an App Service.

App Services can be loaded from App Stores. By default, this would be store.innovaphone.com (which redirects you to the release store http://store.innovaphone.com/release/130000/download.htm). However, as we already have seen, you can create your own store. Moodle has also done so and we are using this (https://class.innovaphone.com/moodle2/webbuild/store.php/1-0).

You can access it by clicking on the screenshot.png App Store icon in the AP Manager UI (which we still need to access using its domain name (https://apps.dvl-ckl2.net) or IP address (https://172.31.31.12) as it is not yet available in our myApps client yet - we're working on it wink).

The first thing it requires you to do is to accept the Terms for Using the innovaphone App Store without Charge.

When you do so, you can unfold the Installed apps / innovaphone AG area and will observe that most of the App Services you have seen before are not (yet) present. screenshot.png Only the App Platform Manager and the Webserver are there.

They have been installed as part of the AP (along with the light weight Linux kernel). If you screenshot.png look at them however, you will notice that they are outdated and can be updated.

How comes that there are updates to components which we installed just now (and we did use the latest-greatest to install the AP)? The answer is quite simple. The AP install package is a bundle of the Linux kernel, the Webserver and the Application Platform Manager. This is essential cause the Linux kernel needs something to start when it boots (which is the Webserver and Application Platform Manager). Of course, when bundling them with the Linux kernel, we use the then-current versions. Both are built and released frequently while the Linux kernel (and hence the AP install package) is updated only rarely.

To be sure your system is up-to-date,

(Further Hints) The updated Webserver and App Platform Manager will be re-started right away, so don't be surprised that the manager's web UI is closed and you are requested to log-in again.

Adding an App Service instance

Now that we have updated the base system and seen how to open the App Store UI, we can easily add some App Services.

Let's start with the Devices App Service:

When you close the App Store area, you will see that the Devices App Service was downloaded, installed and screenshot.png started right away.

What a Service is
In the Application Platform, an App Service essentially is a piece of code that runs on the AP. However, to be usable, the code would need some data storage and some configuration settings in addition to the pure code.

Therefore, you can think of an App Service as a type of service. To actually use it, you need to create an instance of this type of service (known as an App Service Instance).

So installing the Devices App Service gives us the option to create an instance which we then actually can use . This is done with the App Platform Manager of course. Only if this is done, we can actually use the services provided by an App Service!

So when you think "I am using Devices" then you should actually think (or at least keep in mind) "I am using my particular Devices instance".

To be able to use Devices, add an instance to it:
Service instance properties
Let's see what properties an instance has (note that the order is a bit different from the order in the UI, this is for educational reasons only smile)
  • Domain
    This has to be the System Name of the PBX the new instance is intended to be used with. Note that you can create multiple instances and each of these instances can be used in multiple, unrelated PBX systems (e.g. if a hoster provides PBX systems which share the same AP). But you cannot have multiple PBXs sharing the same instance
  • Name
    This is the technical name of the instance. It shows up in administrator interfaces only, so not in end-user interfaces. We recommend to use only short lowercase, letters and digits only names (no punctuation or white space).
    Although the Name does not need to be unique in an AP, the combination Domain/Name has to be! In other words, if you serve multiple PBXs with an App Service (say, Fax), you can create multiple instances (one per PBX) and call all of them fax but only if you use different domains
  • Password
    The instance password. This is used as a shared secret between an instance and the PBX. Both sides need to share this password in order for the connection to work.

    (Further Hints) Please note that the Password is a secret shared between an App service instance and a PBX whose users shall be able to use the instance. No two App instances should share the same password thus (especially, the same password should never be used for all of the instances). In fact, the instance password is not used anywhere else and thus there is actually no need to remember it once it is set. If it gets lost, you can simply set a new one on both ends (the instance and the PBX App object). This is why the Install creates different random passwords for each App service instance

  • Webserver path
    The first part of the URLs which are used to access the services provided by this instance. It must be unique in this AP
  • Database host
    The name or IP address of the host where the database for the App Service instance is to be created. In most cases (and certainly in this course), this is the local host where the App Platform runs and hence we can leave this field empty
  • Database name
    The database name used by this instance. It must be unique in this AP
  • Database user
    The name of the database user that is allowed to access the instance's database

    (Further Hints) Note that Webserver path, Database name and Database user have reasonable default values which you should only change if you really know what you're doing!

  • Database password
    The password used by the Database user. You will need this only in the rare case when you need to access the database using Linux database tools
  • Exclude from overall backups
    You might recall this from your IT Connect training. Should be ticked if the instance shall not be backed up by the standard backup routine done by the Devices App. Usually not ticked except for the special Files App instance which is used to store your backups (to avoid recursive backups)
  • the Name shall be devices
  • The Domain shall be the System Name of your PBX (dvl-ckl2.net in your case)
  • In real life, the Password shall be a secure one (like the Install uses the generic, secure password that it randomly chooses). Here in the training, we use ip411 (as we do all over the place) for both the Password and the Database password
The screenshot.png new instance will be created. The only thing left to do here is to start it, so it can accept service requests. You do so by screenshot.png selecting the instance and then hit the Start button in the Manage section of the upper ribbon band.

Testing the App
To check out the App instance, you can try its user interface(s). Use the Apps button in the Instances part of the top ribbon-band. It will show a pop-up with the available interfaces.

(Further Hints) All interfaces exposed by an App Service are known as App. Note that not all Apps actually have a real web user interface. Some Apps are for programmatic use only. For example, Device's second App listed (innovaphone-devices-api) is such a programmatic interface. If you click on this App, you get a blank box only as it has no web user interface.

Making Apps available to myApps users

Now that we have installed the App (more precisely, the App Service Instance), we need to make it available to users.

As discussed before, you need to tick the respective check-mark in the Apps tab of a user or template to give access to an App. However, when we screenshot.png look now in to John Doe's user object, there is still no such check-mark.

This is because AP-hosted Apps first need to be made known to the PBX before they can be made available to users. This is done by screenshot.png creating a PBX object of type App.

App object properties
The App object's properties on the General tab are pretty straight forward:
  • Description
    is for some optional notes explaining the purpose of the App to end users. It will be screenshot.png shown in a popup message when you hover over its icon in myApps. You can change that at any time later on without breaking anything
  • Long Name
    is the name used to display the App to end-users. This of course is not optional and it needs to be unique throughout your system. You can change it later on without breaking anything
  • Display Name
    Like for any other object, this is a name that will be used when displaying the object to users (e.g. this is what would be shown as the name of the App in the myApps client). It is used if set, otherwise, the Long Name is used. In many situations therefore, you will simply leave it empty. The difference is that the Display Name does not need to be unique
  • Name
    however is used as an id for the App. Like the Long Name, it needs to be unique throughout your system. Choose it carefully as you can't change it later on easily

    (Further Hints) Note that the Name does not need to match the screenshot.png Name of the App service instance. However, it might be less confusing obviously, if it does.

    Also note that we - as usual - recommend to use A-Z, a-z, 0-9, ``.´´ (dot) and ``-´´ (dash) only in a Name. It must not start with a dot however. This rule-of-thumb is good for the Name or SIP property in all PBX objects whatsoever

  • Password
    is used as a shared secret between a PBX and an App service instance. It has to screenshot.png match the App service instance's password
(Further Hints) The Hide from LDAP check-mark does not affect the functionality of the object. However, as for all objects which should not be called by everyone (either cause it doesn't make sense or not everybody should know about it), you should tick it for each App object. If so, the object is never shown in end-user user lists (neither in myApps nor on the phone).

That was the easy part wink

Making Apps available to myApps users (contd.)

The properties in the App and Apps tab however are a bit more difficult:
  • URL
    is the URL to reach the respective App. It is built according to the following screenshot.png template: https://<ap-fqdn>/<appsi-path>/<appsi-name>:

    • ap-fqdn: the fully qualified domain name of your AP (e.g. apps.dvl-ckl2.net)
    • appsi-path: the Webserver path as configured for the App service instance (dvl-ckl2.net/devices in our case, which was the default the AP manager suggested to create a unique path)
    • appsi-name: the name for the App as shown in the Apps popup for an App Service (innovaphone-devices for this App, this is hard-coded by the App Service and cannot be changed)

      (Further Hints) You can see all the screenshot.png available URLs in the Edit popup in the AP manager

  • Licenses
    defines the number of so-called Service licenses allowed for the App. Usually, if the App does not use Service licenses, you leave that empty. Service Licenses are used by App Services with custom licensing schemes
The remainder of the properties in both the App and Apps tab depends on the App you are configuring. In other words, you don't have a choice - you need to set it up as the app requires. To know what is required, you can consult the documentation. For innovaphone Apps, you will find the information in the wiki article describing the respective App service. For the Devices App for example, this would be fish-help.png Concept App Service Devices. These articles will have a chapter called "Apps" with a section for each App which lists all required options. In our case section innovaphone-devices is relevant and tells us that we need to tick the Websocket check-mark.

(Further Hints) You can find a complete list of App object properties in the fish-help.png App Objects Parameters chapter of fish-help.png Concept Apps.


Making Apps available to myApps users (contd. II)

So let's do it now:

  • open the list of PBX objects on your IP411LEFT
  • create a new PBX object of type App
  • type whatever you like as Description (or leave it empty)
  • tick the Hide from LDAP check-mark
  • use Devices as Long Name
  • leave Display Name empty
  • use devices as Name
  • use ip411 as Password (as this is what we used as Password for the App instance before)
In the App tab
  • for the URL property recall that
    • the protocol is always HTTPS, so we use https:// as scheme
    • the App is hosted on your App platform, so the host is apps.dvl-ckl2.net
    • usually, the system's domain is used as the App service's unique path, so it is dvl-ckl2.net
    • the name of the instance we have created was devices (note that we could have named it foo or bar instead)
    • the name of the App is innovaphone-devices and this is hardcoded in to the App service (so we cannot call it differently)
Therefore, when we glue all those pieces altogether, we use https://apps.dvl-ckl2.net/dvl-ckl2.net/devices/innovaphone-devices as URL
  • tick the Websocket check-mark
In the Apps tab
  • leave all check-marks un-ticked
Congratulation! You created your first App object smile
Nevertheless, the Devices App is still not available to John Doe. We still need to assign the App to the user.

To do so, proceed as follows:
  • open John Doe's user object
  • switch to the Apps tab
  • and screenshot.png tick the devices check-mark

    (Further Hints) Note that the name that appears in the list of assigned Apps here (devices) is exactly the Name property of the corresponding App object (the one we created just before). This is why you can't easily change the App object's Name - you would loose all assignments!
John Doe now has Devices in his ALL APPS list in myApps available and can put it on his home screen.


This is probably a good time to log in to the myApps client.

You can open the myApps client using the URL https://hq.dvl-ckl2.net/PBX0/APPCLIENT/137786/appclient.htm?lang=en. and login as john.doe using ip411 as password.

You may also want to put our first App (which is Devices) on John's home screen.

Multiple Apps in a single App service instance

As we have seen in the AP Manager's Apps tab for Devices, this App service provides screenshot.png multiple Apps (innovaphone-devices, innovaphone-devices-api and csvapi).

Although the second interface (innovaphone-devices-api) is a programmatic interface that does not have a web UI (hence the name API), it must be made known to the PBX so that it can be used from the PBX (either by other App services or by users who use Apps that use the API).

So as you might have guessed, it is necessary to create an App object in the PBX for each of these Apps. Again, the details how to set the various properties of those App objects can be determined as before.

So, to create the App object for the innovaphone-devices-api
  • create an App object in the PBX with Long Name set to DevicesApi
  • tick the Hide from LDAP check-mark
  • Name set to devices-api
    note that both Long Name and Name could be set differently, the App would work nevertheless
  • Password set to ip411 (this has to be like this exactly, as this is the Password we have set for the devices App service instance before)
  • URL set to https://apps.dvl-ckl2.net/dvl-ckl2.net/devices/innovaphone-devices-api
  • the Websocket and Hidden check-marks ticked (we know this from the fish-help.png Concept App Service Devices article in the wiki)
  • as this API is required for some administrative Apps which our John Doe shall be able to use, we need to tick devices-api (that is, the Name of the new App) in John Doe's Apps tab

App services with multiple Apps

(Further Hints) As we have seen, App services may provide multiple Apps (and hence multiple App URLs). When this is the case, make it a habit to always create App objects for all of the Apps that are listed in the respective wiki article for the App service (e.g. in fish-help.png Concept App Service Devices) in your PBX. So for Devices for example, create App objects for innovaphone-devices-api as well as for innovaphone-device (just like we did right now).

The reason for this is, that proper function of all the Apps may rely on the existence of all those App objects. In other words: if the App object for one App is missing, another App may fail.

This is one of the most prominent reasons for the Users App to fail.

Adding your devices to Devices

While dealing with the Devices App, we can also do some basic steps to add all of your devices to the Devices app.

As you probably recall from the IT Connect training, all of the devices of an installation can (and actually should) register with a Devices App service instance.

This is simply done by configuring the websocket URL of your Devices instance (also known as sysclient URL) to all your devices. The URL is made up of
  • the URL scheme wss:// (which as you probably know stands for web socket secure)
  • the DNS name of your application platform (apps.dvl-ckl2.net in your case)
  • the System name of your PBX (dvl-ckl2.net in your case)
  • the instance name of your Devices instance (devices in your case)
  • the fixed string sysclients
So you end up with wss://apps.dvl-ckl2.net/dvl-ckl2.net/devices/sysclients as Devices-Registration URL (also known as sysclient URL).

Registering all your devices with Devices

To register your devices with your Devices instance, you need to configure the sysclient URL in two places:
  • the PBX: configure the sysclient URL from above for your PBX in General / Devices-Registration
  • the Application Platform

    You may recall that the AP actually is a fully fledged second device within your IP411LEFT. So the Devices App URL property which we have set in the IP411LEFT before is only for the firmware part of your IP411LEFT. The AP part must be configured separately.

    To do so,
(Further Hints) Of course we could add the Sysclient URL to each of our remaining devices (IP111 etc.) too. We will skip this for now because we will get to it later anyway.

Creating the domain in Devices for your installation


Devices is a service that can manage all the devices of your system.

However, it can also manage the devices of more than one system (imagine a hosted PBX provider who manages all of the devices of all its customers in a single Devices App). In case of multiple systems you could of course create one Devices instance for each system and register the devices with the respective instances using different sysclient URLs. But that would force you to use a separate App for each of your systems, which might be annoying.

Therefore, Devices itself supports the concept of multiple domains (which might be a little confusing in the beginning admittedly, as we now have domains in the App Platform Manager and also in the Devices App). You would then create a separate domain (within Devices) for each of your systems and use the same sysclient URL for all the devices.

But even if you only run a single system, you need to create this single domain inside Devices.

So the next step is to create an appropriate registration domain for your PBX system in Devices:
  • within the Devices UI, screenshot.png switch to the Domains tab and
  • add a new domain by clicking on the + Add domain link
  • use your screenshot.png PBX's System name property as screenshot.png Domain name (be sure that they do match exactly!). In your case, this is dvl-ckl2.net
  • use ip411 as password (of course, in real-life, you would use a secure password)
  • make sure you uncheck the Deploy the domain password on all devices check-mark!
In real life, as noted above, you would want to use a secure (probably random) password for the domain. Also, you probably want to check the Deploy the domain password on all devices check-mark. This makes sure that any device registered to your Devices instance will have the password for the admin UI changed to the domain password. The reason for this is that device access should always take place using the Devices App, not directly through the Web UI (this is for emergency cases only). But in the training, we do not want this to happen, as all devices must retain their default password!

You can leave all other properties as is.

Adding your devices to the Devices domain

When screenshot.png switching to the Devices tab, you might observe that your domain devices, although listed, are shown with this strange screenshot.png wrench symbol. This is to say that the device tries to register with Devices but is unknown. In other words: you need to approve each device that wishes to join the domain explicitly.

(Further Hints) Don't be afraid: this is not going to be too much work. When devices use the provisioning (as you have seen in the IT Connect training), they will be approved to the domain automatically.

Adding the device to the domain can be done when you select such an unknown device. The Edit dialog which appears then allows you to specify the domain and an arbitrary name for the device.

(Further Hints) Be sure not to join devices to the domain which you don't know! This might be an attempt to attack your system (as devices get access to sensitive information during their configuration by Devices).

To add your devices to the domain
  • click on each device with the screenshot.png wrench symbol on the Devices tab
  • set a useful name (this is only for you to distinguish the devices later on).
    For the "firmware devices", a suitable name is already suggested (actually, moodle has configured these names in their General/Admin section before) and you can keep it if you like. For the AP (this is the one with the MAC address starting with 029033, remember?) you need to set one
  • and screenshot.png set the device's domain to the screenshot.png System name of your PBX

Special App objects

There are a number of specialized App object types available in the PBX. All of them serve the same basic purpose: make an App known to the PBX and hence available to users. However, they are hand-crafted for specific Apps and their needs:
  • screenshot.png AP
    Defines the PBX Manager Plugin App provided by each AP (this App allows you to easily create App objects for the Apps provided by the App services installed on the AP, we'll look into this in a minute)
  • screenshot.png Push
    Defines the Push App which is used by a PBX to notify/wakeup Android and iOS apps (e.g. to signal an incoming call)
  • screenshot.png Voicemail
    Defines the Voicemail App (surprise, surprise)
  • screenshot.png Fax
    Defines the Fax App (again, surprise)
  • more to come...
For now, it is sufficient to understand that these objects define Apps just like we did before for the Devices App which then need to be assigned to users (using their user object's Apps tab).
     

The "AP Manager" App

There is one specific App available on each AP even if no App service at all has been installed. This App provides access to the AP's admin web user interface (the one you see when you log in to the AP (e.g. https://apps.dvl-ckl2.net) using the manager password as we did so far).

screenshot.png This App (usually called AP Manager) is provided by the AP's manager and does not need to be (neither can be) installed or configured on the AP. Still - as with all Apps - it must be made known to the PBX so that it then can be made available to users.

The URL for the App is https://<ap-fqdn>/manager/manager where ap-fqdn is the DNS name of the AP (apps.dvl-ckl2.net in our case).

The password for the AP Manager App object must match the admin password of the application platform (ip411 in our case). If you leave it empty, it defaults to the box's admin password.

To provide access to the AP manager's admin UI, you proceed as follows:
  • create an App object in the PBX with the following screenshot.png properties on the General tab:

    • Hide from LDAP: ticked
    • Long Name: AP Manager
    • Display Name: leave empty
    • Name: apps
    • Password: ip411

  • ... on the screenshot.png App tab:

    • URL: https://apps.dvl-ckl2.net/manager/manager

  • ... no changes on the Apps tab
  • tick the screenshot.png apps check-mark in John Doe's user object's Apps tab
John Doe now has the AP Manager App available in his ALL APPS area (from where you may want to add it to the home screen).
     

The App Service PbxManager Plugins

There is some support for Application Platforms and App Services available in the screenshot.png PbxManager.

The elements in the PBX Manager are dynamically created when corresponding items exist in the system. This is why they sometimes are also referred to as plugins. Let's see what they can do for us.

Adding APs

App services installed on an AP can provide screenshot.png PBX Manager plugins (you have seen this in the IT Connect training already). They can help with adding the App objects to the PBX (which we have done manually before for the Devices App) and can also do some basic configuration of an App instance.

For these plugins (sometimes referred to as the colorful icons for obvious reason) to show up, we need to make the AP itself known to the PBX. This is done by creating a PBX object of type AP for each known Application Platform.

As we already discussed, an AP type object is in fact a specialized App object especially for PBX Manager plugins. Not surprisingly, it looks quite similar to the standard App objects.

To make our Application Platform known to the telephone system, the following steps are required:
  • create a new screenshot.png AP type PBX object
  • set screenshot.png Description to This is Christoph's application platform
  • tick the Hide from LDAP check-mark
  • set Long Name to Christoph's AP
  • set Name to ckls-ap
  • set Password to the platform manager's Manager password (which we have set to ip411)
  • set screenshot.png URL to https://apps.dvl-ckl2.net/manager/manager-domain-api
  • leave Account empty
When you now open the PBX Manager again, you will notice a screenshot.png new (colorful smile) icon called Christoph's AP devices. This name is built up by the screenshot.png Long Name of the AP object for the Application platform (Christoph's AP) and the screenshot.png Name of the respective App service instance (devices).

This icon is created by the App Platform Manager (the one that the URL https://apps.dvl-ckl2.net/manager/manager-domain-api we used above for creating the AP object points to). It is related to an App service instance, not an App service and the manager will create one such icon for each App service instance. In other words: If we were to add another instance to the Devices App service, another icon would appear.

The host-local path of the URL above (/manager/manager-domain-api) is actually fix, that is, it will be exactly this path on every AP. This is in contrast to other Apps, as the manager of course only exists once and is not domain-specific.

Dynamic AP password

In the previous chapter, we have used the AP's manager password (ip411 in our case) as password for the AP object. This is correct because both the AP object's and the AP manager's password are used as shared secret which must match so that the connection is authorized.

If you change the password in the AP object (Christoph's AP) into something random (say xyz123), you will see that the PBX Manager does not show the respective icons any more (you need to refresh the myApps client with F5 or right-click/reload to see the effect). This is of course expected behavior as the shared secret do not match any more.

The surprising thing is that if you now actually delete the password in the AP object (not the password of the AP manager!), the PBX Manager plugins will be available again.

So how can that be?

If the password in an AP object is left empty, the PBX will use the device's admin password instead.


(Further Hints) In the course, as we have discussed before, DO NOT SET THE Deploy the domain password on all devices option!

This makes sense as the Devices App service has an screenshot.png option to Deploy the domain password on all devices (you have seen that in the IT Connect training already). If this option is turned on and the domain password is changed, then all connected devices get their admin password changed - including the AP! The AP's manager password is its admin password (you might recall that you use it to log in to the AP manager using this password when you access it through its IP address directly). So when this happens and a fixed password was configured in the AP object, you would loose access through the PBX Manager (as now the shared secret do not match). If you leave the AP password empty however, the new (changed) admin password will be used which again matches the AP manager's password.

(Further Hints) So if you use the Deploy the domain password on all devices option, we recommend to leave the AP object's password empty.

Btw: this only works if the device's User Name in General / Admin is screenshot.png set to admin. So do not change this if you want to use this mechanism.

Two instances

As mentioned before, a single App Service can have more than one App Service instance. To see how that works, let's reproduce what the Install does with the Files App service.

It installs the Files App service and also two instances of it, Files and Backup Files.

Install the service
We already know how to install the Files App service:
  • open the Platform Manager (now that we have the nice little screenshot.png AP Manager icon, we can open it from myApps which is more elegant than to open it directly through its web interface at https://172.31.31.12)
  • open the App Store
  • unfold the All apps/innovaphone AG list
  • scroll down to the Files App and select it
  • screenshot.png select version srTraining from the drop-down
  • screenshot.png click on Install
  • accept the license terms if you are asked for it and install the Files App Service
  • screenshot.png leave the App Store area
  • then add screenshot.png an instance called files for domain dvl-ckl2.net, set both Password and Database password to ip411
  • add screenshot.png another instance called backup-files for domain dvl-ckl2.net, set both Password and Database password to ip411
  • also, tick the Exclude from overall backups check-mark for the backup-files instance (this flag will stop Devices later on to backup this instance)
  • start screenshot.png both instances
We now have a new App service with two instances, so we'd expect 2 new (colorful) icons in the PBX Manager - and indeed, screenshot.png here they are smile

Create the App objects in the PBX
We could create the App objects manually in the PBX as we did before. However, this time, we want to do it using the PbxManager plugins which appeared.

It is important to understand that each of the two new icons relates to a specific instance of the Files App service. You can see which icon relates to which instance because the instance's name appears in the icon label. So to create the App objects for both Apps provided by the Files App service (which are the Files App and the Files Api) for both instances (which are files and backup-files) we need to use both icons.

Let's start with the files instance:
  • start the Christoph's AP files plugin
  • screenshot.png click on + Add an App to create an App object in the PBX
  • click on screenshot.png on Files Api to add the App object for the files api to the PBX
  • screenshot.png use FilesApi for the Files Api field (which will become the Long Name in the new PBX App object) and files-api for the SIP field (which will become the Name)
Eh voilà, the App object screenshot.png has been created. Even the screenshot.png URL and the check-marks have been set.

We can add the App object for the Files App itself the same way:
  • click on Christoph's AP files plugin again
  • click on + Add an App and select Files App
  • use Files for the Files App field and files for the SIP field
The screenshot.png App objects are easily created.

Finally:

Creating App objects for Apps

As we said before, the PBX Manager AP plugins can do basic configurations for an App service instance and help with creation of App objects for the Apps provided by the App service.

The Devices's App plugin however does not feature any special configuration dialog. So the only thing you see when you screenshot.png open the plugin is the + Add app function (as well as the two App objects we have already created manually). The green checkers next to the App objects indicate that the plugin seems to like what we have created wink

Creating the App objects for the App service's Apps is easier via the PBX Manager plugins than in the advanced UI where we have done it just before. Of course, the plugin itself knows how the URL needs to look like and which check-marks have to be set. So the only screenshot.png properties you need to set (and hence can set or modify) are Name and SIP (which are equivalent to Long Name and Name in the advanced UI, which is a bit confusing).

How the plugins manage the instance password

You might have observed that you cannot actually set or modify the password though. So how does the plugin know the password to be able to set it correctly in the App object?

(Further Hints) As described in fish-help.png Concept Apps, the plugins use a little trick here. If they need to set the password and don't know it, they simply create a new random password and set it in both the App object and the App service instance. While this has the beauty that both passwords match thereafter (which is a requirement for the App object to work as you already know), it has the drawback that it silently changes the instance's Password. This is a bit confusing and sometimes even breaks working configurations. Keep this in mind or simply create the App object manually using the advanced UI.

Generally, when using the PBX Manager plugins for the App services, make sure that
  • the App service instances are used from a single PBX only (that is, you have a single master PBX)
  • or, you have a master / slave setup where all PBXs using the App service instance are fully replicated (we will look into what this means in more detail later, for now: all slaves share the same PBX objects)
If this is not the case, do not use the plugins to create or modify the App objects in the PBX (but don't be scared, you will usually meet the criteria listed above).

Instance configuration

Some PBX Manager plugins can do even more: they can set some basic configuration parameters in the App service instance.

To see how this works, we'll setup a Reporting App service first:
Then in the PBX Manager
This is an example for a general configuration dialog which an App instance can provide (you may view it as an administration settings dialog in contrast to user specific configuration dialog which would appear in a burger-menu in the Apps themselves).

In this case, you can modify the deletion strategy for the CDRs processed and stored in the Reports App service instance.

(Further Hints) And by the way, believe me, you don't want to set it to disabled. CDRs will quickly fill your database and one day, your AP's disk will be full and it will not boot any more and fish-help.png you're in trouble.

Instance properties are stored in the App instance database on the AP itself, not in the PBX. This is why they are also saved upon a backup and restored with an instance restore.