Deploying an XApp

From Morfikwiki.com

Jump to: navigation, search

Note: for information on deploying Browser XApps, see Deploying a Browser XApp.

Contents

[edit] Available Options

Click on the option that applies to you:

Platform Stand-alone XApp Morfik Plug-in XApp Plug-in XApp (ISAPI) Plug-in XApp (Apache) Plug-in XApp (IIS)
Windows Morfik Apache 1.3 Morfik Apache 1.3

Apache 2.2

Linux Morfik Apache 1.3 <Available, not tested> <None> Apache 2.2 <None>

[edit] Windows

[edit] Windows, Stand-alone XApp with Morfik Apache 1.3

Deploying an XApp a simple 2-step process:

  1. first install the relevant project files, and then
  2. install the Firebird database engine along with some Apache dll files.

The .EXE, .MXD and .MXR (and the _Resource folder and all its contents, in the case the Package Resources option is unticked) is all that is required to be deployed onto the host machine.

Install relevant Firebird and Apache files

An installation of the Firebird database engine and the presence of Apache dlls are required on your deployment PC in order to run your Morfik Applications (xApps). Please note that this is not an installation of a set of frameworks; it is just a simple installation of Firebird and Apache dlls.

You have two choices for the Firebird install.

Firebird Embedded (and Apache) Installer
Firebird Embedded database engine and Appache dlls are installed with this deployment kit. This installation is more suitable for the initial XApp testing. Using the Embedded version of Firebird means that only one application can access your database at a time, which is usually your XApp. Please use the Firebird Server installation if you wish to connect to external shared Firebird databases or use other utilities such as database backup tools. FireBirdEmbedded _Apache_installer.zip
Firebird Server and Apache Installer
Firebird Server database engine and Apache dlls are installed with this deployment kit. This installer installs Firebird database engine Server on your deployment pc which (unlike Firebird Embedded) allows multiple connection to your project Database. You will need multiple connection to your database for backup purposes or if your project database is accessed by multiple XApps.

MorfikServerInstaller1.4.0.1.zip

MorfikServerInstaller2.0.0.2.zip

[edit] Windows, Morfik Plug-in with Morfik Apache 1.3

Multiple Morfik applications can be run on the same PC provided that they run on different HTTP Ports. However there are times when you may have to run multiple applications on a single port, mainly port 80.

Creating a Host XApp

The first step for setting up the environment for running plug-in XApps is to compile a host XApp which will host the plug-ins XApps. A host XApp is a blank project with the port number under which the plug-ins XApps will run.

Create a new project and choose a name for it (in this example we use the name "host" for the host XApp project). Compile the project as “Stand-Alone XApp” under “Project” menu “Project Options” (this is the default option). Choose the port which will be used on the server for the plug-in XApp projects.

After a successful compilation there should be a host.exe file inside the project folder. Copy this file along with host.mxd and host.mxr to the server where the plug-in XApps will run.

Also there is a need to install “Morfik Firebird Server and Apache Installer1.1.0.exe” on the same server.

  • Make sure Firebird SQL server is running.
  • Double click on host.exe file and start the host XApp.
  • Right mouse click on your host icon on the Task Bar and run the project as a service (optional).
  • Create a text file in the same folder where the host XApp is located and call this file yourproject.ini (in this case host.ini).
  • Now you are ready to compile and deploy the plug-in XApps.


Deploying Plug-in XApp Projects

Compile the plug-in XApps (in this example we use myXApp1 and myXApp2 for the name of these plug-in projects) choosing “Morfik Plug-in XApp” from “Binary” drop down box under “Project Options” of “Project” menu. After a successful compilation, copy myXApp1.dll, myXApp1.mxd, myXApp1.mxr and any other files specific to this project to a folder on the server (create a folder called myXApp1 under the folder where the host XApp on the server is located. eg. c:\host\myXApp1 ).

Do the same as above for myXApp2 project.

  • Open host.ini (should have been created in earlier steps) file and add the following entries in it and save the file. 
[XAppPlugins]
Plugin1=myXApp1
Plugin2=myXApp2

[myXApp1]
Name=myXApp1
Path=C:\host\myXApp1\myXApp1.dll 
Host=myXApp1.mydomain.com 

[myXApp2]
Name=myXApp2
Path=C:\host\myXApp2\myXApp2.dll 
Host=myXApp2.mydomain.com
  • Before the plug-in XApps can be reached the host XApp needs to be restarted. (Go to Windows services and restart host service).
  • Once the host XApp is running, each plug-in XApp and the host XApp can be accessed using their corresponding URLs.
  • If a port other than 80 is choosen for the project, the port needs to be specified in the URL address when accessing the plug-ins.
  • This method of deployment relies on domain/sub-domain name resolution on the server so for every XApp created a DNS entry is needed in order to access it.


[edit] Windows, Apache ISAPI Plug-in XApp with Apache 1.3

Attention!

  • This option has been discontinued as of Morfik 2.0.

Instructions

  • In the IDE, from the main menu choose “Morfik Options”.
  • On the “Compiler” tab in the “Options” Dialog box, select “Apache Plug-in XApp” from “Binary” drop down box and click on “OK” button.
  • Compile your project.
  • If compilation is successful you should see a file called: "your-project.dll" (replace your-project with the name of your project).

Notes and reminders

  • Morfik XApps have been tested with Apache 1.3.37
  • Apache 1.3.x with FPC is problematic. There are no known problem with Delphi.
  • You need a computer or a server with Apache 1.3.37 and Firebird installed and running.(Make sure the fbclient.dll of firebird is accessible and MFKUDF.dll is in the UDF directory of Firebird.)
  • Copy all your necessary files (including your-project.dll, your-project.mxd, your-project.mxr and any other files) to a suitable folder.
  • Locate your apache “http.conf” file and add or change the following lines:
    • Add this line “AddModule mod_isapi.c” to http.conf for isapi support.
    • Add this line “AddHandler isapi-isa .dll” to tell Apache which module should handle the .dll extensions.
    • Change the document root to the folder you have your XApps under. (eg. DocumentRoot "C:/Samples" )
    • Make sure you add the ExecCGI flag to Options for the folder that your XApps will run under. For example: 
<Directory "C:/Samples">
   Options ExecCGI  Indexes FollowSymLinks MultiViews
   AllowOverride None
   Order allow,deny
   Allow from all
</Directory>
  • Save the http.conf file.
  • Restart the Apache server.

[edit] Windows, Apache ISAPI Plug-in XApp with Apache 2.2

Attention!

  • This option has been discontinued as of Morfik 2.0.

Instructions

  • In the IDE, from main menu choose “Morfik Options”.
  • On the “Compiler” tab in the “Options” Dialog box, select “Apache Plug-in XApp” from “Binary” drop down box and click on “OK” button.
  • Compile your project.
  • If compilation is successful you should see a file called: "your-project.dll" (replace your-project with the name of your project).
  • You need a computer or a server with Apache 2.2.4 and Firebird installed and running.(make sure the fbclient.dll of firebird is accessible and MFKUDF.dll is in the UDF directory of Firebird.).
  • Copy all your necessary files (including your-project.dll, your-project.mxd, your-project.mxr and any other files) to a suitable folder.
  • Locate your apache “http.conf” file and add or change the following lines:
    • Make sure this line “LoadModule isapi_module modules/mod_isapi.so” exists in http.conf for isapi support.
    • Add this line “AddHandler isapi-handler .dll” to tell Apache which module should handle the .dll extensions.
    • Change the document root to the folder you have your XApps under. (eg. DocumentRoot "C:/Samples" )
    • Make sure you add the ExecCGI flag to Options for the folder that your XApps will run under. For example: 
<Directory "C:/Samples">
   Options ExecCGI  Indexes FollowSymLinks MultiViews
   AllowOverride None
   Order allow,deny
   Allow from all
</Directory>
  • Save the http.conf file.
  • Restart the Apache server.

To run your XApp

On Windows, if your DocumentRoot in http.conf is set to “c:/samples” and your project is under c:\samples\project1 folder then to run your XApp assuming your project dll is called project1.dll, in the address bar of IE or Firefox (or whatever your browser is) type http://address-of-your-server/project1/project1.dll and press enter.

[edit] Windows, Apache Native Plug-in XApp with Apache 2.2

To prepare the server for deploying your XApps:

  • Install Apache 2.2 on the server (if it is not already installed).
  • Install Firebird 2.1 on the server.
  • Copy MFKUDF.dll to the UDF folder of the Firebird installation.

To deploy your XApp:

  • Open your project (let's call it Project1) in the Morfik IDE.
  • Go to Morfik Options, Compiler tab, set the Binary Kind to "Apache Plug-in XApp".
  • Compile the project.
  • Copy the following files and folders to the modules folder of your Apache installation:
    • Project1.mxr
    • Project1.mxd
    • Project1.dll
    • _Project1Resources
  • Open Apache's httpd.conf file in notepad.
  • Add the following line after the other LoadModule statements in the httpd.conf file: 
LoadModule project1_module modules/project1.dll
  • Add the following line at the end of the httpd.conf file: 
<Location /project1>
    Options Indexes FollowSymLinks MultiViews +ExecCGI 
	SetHandler project1-handler
    Order deny,allow
    Allow from all
</location>
  • Restart the Apache service.

To view your XApp:

  • You should now be able to access the XApp via a web browser using the following URL: 
http://address-of-your-server/project1

[edit] Linux, Apache Native Plug-in XApp with Apache 2.2

[edit] Windows, IIS Plug-in XApp with IIS 6.0

Tested under Windows 2003 with IIS 6.0


To compile your project as a plug-in for IIS 6

To compile your project as a plugin for IIS

  • In the IDE, from the main menu choose “Morfik Options”.
  • On the “Compiler” tab in the “Options” Dialog box, select “IIS Plug-in XApp” from “Binary” drop down box and click on “OK” button.
  • Compile your project.

If compilation is successful you should see a file called your-project.dll (replace your-project with the name of your project) created under the directory your project files are under.

IIS 6 is a lot more secure than previous versions and it adds some powerful features and flexibilities for running and maintaining your sites and applications. There are many ways you can run your XApps under IIS, the aim of this basic instruction is only to show you one of the easiest way you can get your XApps running under IIS. There are a lot more, for example if you need multiple applications running under the same server in isolation mode or if you need to implement a higher level of security or performance, but those topics are beyond the scope of these simple instructions.


To run your project under IIS 6

To run your project under IIS

  • You need a computer or a server with Microsoft Windows 2003 or XP with IIS and Firebird SQL 2 installed. (After installing Firebird place mfkudf.dll in the Firebird UDF folder).
  • Copy all your necessary files (including your-project.dll, your-project.mxd, your-project.mxr and any other files) to a suitable folder.
  • sure your XApps are allowed to run as Extensions under IIS. To do this, in IIS console expand “Web Services Extensions” node and either select “All unknown ISAPI Extensions” and click on “Allow” button (this method is not secure) or use “Add a new web services extension …” link under the same node to add your XApp to the allowed list.
  • From IIS management Console.
  1. Expand “Web Sites” node.
  2. Right mouse click on “Default Web Site”.
  3. From the “New” menu select “Virtual Directory”.
  4. A wizard dialog pops up. Click next.
  5. Enter an Alias name for your XApp and click next.
  6. Browse to the folder where your XApp project files were copied to, select and click next.
  7. Select “Read” and “Execute” options.
  8. Click next and finish the wizard.
  • If you expand the “Default Web Site” node of the MS IIS Console, you should see the alias name you chose for your XApp under this node.

[edit] Windows, IIS Plug-in XApp with IIS 7.0

Tested under Windows Vista with IIS 7.0


To compile your project as a plug-in for IIS 7

To compile your project as a plugin for IIS

  • In the IDE, from the main menu choose “Morfik Options”.
  • On the “Compiler” tab in the “Options” Dialog box, select “IIS Plug-in XApp” from “Binary” drop down box and click on “OK” button.
  • Compile your project.

If compilation is successful you should see a file called your-project.dll (replace your-project with the name of your project) created under the directory your project files are under.

IIS 7 is a lot more secure than previous versions and it adds some powerful features and flexibilities for running and maintaining your sites and applications. There are many ways you can run your XApps under IIS, the aim of this basic instruction is only to show you one of the easiest way you can get your XApps running under IIS. There are a lot more, for example if you need multiple applications running under the same server in isolation mode or if you need to implement a higher level of security or performance, but those topics are beyond the scope of these simple instructions.


To run your project under IIS 7

To run your project under IIS

  • You need a computer or a server with Microsoft Windows Vista with IIS 7 installed. (Note: when installing IIS 7, you must remember to tick the ISAPI Extensions checkbox, as it is not ticked by default.)
  • Install Firebird 2.0. (After installing Firebird place mfkudf.dll in the Firebird UDF folder.)
  • Copy all necessary project files (including your-project.dll, your-project.mxd, your-project.mxr and any other files) to a suitable folder, e.g. c:\Samples.
  • Open the Internet Information Services (IIS) Manager.
  • In the Connections panel, navigate to the Default Web Site node, then right-click >> Add Virual Directory.
  • In the Add Virtual Directory dialog, enter an alias for your xapp (e.g. "Project1") and the physical path to your xapp (e.g. "c:\Samples\Project1"); click OK.
  • Double-click on the Handler Mappings icon (note: if you cannot see this icon, click the Features View button at the bottom of the screen).
  • In the Handler Mappings list, select ISAPI-dll, then click on Edit Handler Permissions in the Actions panel.
  • In the Edit Handler Permissions dialog, ensure the Read, Script and Execute checkboxes are all ticked; click OK.
  • In the Connections panel, navigate to the top-level node (the one showing your computer name).
  • Double-click on the ISAPI And CGI Restrictions icon (note: if you cannot see this icon, click the Features View button at the bottom of the screen).
  • In the Actions panel, click on Add....
  • In the Add ISAPI or CGI Restriction dialog, enter the absolute filename of your xapp (e.g. "c:\Samples\Project1\Project1.dll"), and tick Allow Extension Path To Execute; click OK.
  • In the Connections panel, navigate to the Default Web Site node, then right-click >> Start (note: skip this step if it is already started).
  • To test your XApp, in the address bar of IE or Firefox (or whatever your browser is) type http://address-of-your-server/alias-name/your-project.dll and press enter.

[edit] Linux

[edit] Linux, Stand-alone XApp with Morfik Apache 1.3

These are basic instructions on how to compile and run XApps under Linux. It has been tested on Fedora Core 4, openSUSE 10.1, Debian 3.1, Ubuntu 7.10, Ubuntu 7.10 Server Edition, Ubuntu 8.

Compiling an XApp

  1. Open the XApp project to be compiled for Linux OS.
  2. In the Morfik Options Dialog, in the Compiler Tab, select ‘Linux, Intel x86’ from Target Platform drop down box.
  3. Click OK and then compile the project.
  4. The linker will fail if the path of the project file contains spaces. The workaround is to copy the project folder to some path without spaces (say c:\myproject\)
  5. That’s it!


Prepare your Server:
  1. First you must prepare your server (this only has to be done once).
  2. Depending on the system you use you may want to try out one of the following tutorials (These tutorials are highly recommended, as they cover and download all the library's that the xApp Requires):


Installing Firebird:

  1. Download and install firebird 2.0 database for your Linux platform.
  2. Make Sure that firebird 2.0 has been installed as some linux distro's like Ubuntu download firebird 1.5 instead (when you do apt-get install firebird).
  3. Copy the supplied mfkudf.dll to the UDF directory, where Firebird was installed (make sure the permission rights are correct on this file eg chmod g+rx mfkudf.dll)
    • On Ubuntu this directory is located in the "/usr/lib/firebird/2.*/UDF/". On Ubuntu 8.04, Firebird is installed in /opt/firebird.
  4. Change the sysdba password to ‘masterkey’. (there is a tool under …./firebird/bin dir called gsec. Run gsec like the following example: ./gsec –user sysdba –password thepassword . You most likely find the password for sysdba in a file under main directory where Firebird was installed called SYSDBA.password. Once gsec is running then use this command to change the password to masterkey: “modify sysdba –pw masterkey”.
  5. Make the user under which the XApp runs, a member of Firebird group.
    • If you wish to create a new user use the "sudo useradd -G {firebird} username" command (without quotation marks, and replace username with the user name you wish to specify).
    • If you wish to add a existing user to a group use the "sudo usermod -a -G firebird username" command (without quotation marks, and replace username with the user name you wish to specify).
  6. Copy the supplied libhttpd.so to /usr/lib and set its executable permissions to (755). This can be set with the following command: sudo chmod 755 /usr/lib/libhttpd.so
  7. Following is a list of other lib files which you may need to have (a version of) on your Linux system. If you don’t have them, find the required package and install them. (The 'Prepare your Server' tutorial above would of downloaded the libraries needed to run your xApp):
    • libc.so
    • libcrypt.so
    • libdl.so
    • libpthread.so
    • librt.so
    • libuuid.so

Installing/Running XApps

  1. Copy to Linux target the following files (mind capitalization):
    • Binary executable file of an XApp - XXX
    • Project file for an XApp, which describes source files, tables, queries, etc that are part of a project - XXX.Mxp
    • Resources file for an XApp, which contains images, text files, etc that are added into a project - XXX.Mxr
    • A Firebird database file; the primary database for an XApp - XXX.Mxd
    • Web Service Description Language file describing how other applications can access the services exposed by an XApp - XXX.wsdl
    • For example, for the Northwind project
      • The required files would be: "Northwind", "Northwind.Mxp", "Northwind.Mxr" and "Northwind.Mxd".
      • Firebird should have read and write access to database file (chmod 666 “databasefile" to get right file permission rw-rw-rw-) and execution rights to binary file.
  2. Run the application. (Recommended that the application not be run as the root user, for better security, you may require the sudo command for it to run).


Notes and Reminders: If you experience problems and are unable to resolve it yourself, please send us a detailed error-report and if possible include the results of a strace log (zipped, please).

To get the strace, run the application as follows: strace -f -o myfile.log -s 255 myapplication (eg. strace -f -o northwind.log -s 255 ./Northwind)

This should provide you with a myfile.log file which should help us diagnose the problem (you may want to peek inside; maybe you'll find the reason for the faulty behavior yourself?)

[edit] Files Needed


[edit] See Also



Retrieved from "http://www.morfikwiki.com/Deploying_an_XApp"
Personal tools