Project

General

Profile

Wiki ยป

Using Ansible for Management of a FWD Ubuntu System

Introduction

The VM management bzr repository at https://proj.goldencode.com/downloads/automation/fwd_mgmt/ provides scripts to automate the configuration of an existing Ubuntu 16.04 machine, to be used as a FWD conversion and/or application server machine.

The scripts are written for an open source systems management tool called Ansible.

To use these scripts, there will be two systems:

  1. the TARGET system, which will be configured by the Ansible scripts
  2. the CONTROLLER system, on which the Ansible scripts will be executed

For these instructions, substitute the following placeholders in each command:

  • <server_hostname> This is the hostname of the target system (VM) on which you are installing.
  • <admin_username> This is the admin user account on the target system (VM) on which you are installing.

This process is used to create systems that can be used to deploy build, test or production systems. This can be used on physical systems or on virtual machines. The result is designed for and tested on a single server system. There is no requirement for a Graphical Desktop environment (e.g. Gnome or KDE) to be installed.

The following components are installed:

  • PostgreSQL Database Cluster
  • Imported database instance for the application database (only a single DB instance is supported at this time). This is optional.
  • FWD Application Server
  • Converted Application (converted binaries and the runtime configuration). Optionally the conversion environment is fully setup and executed.
  • FWD Web Client and the Spawner
  • Standard Embedded Mode Web Application

This is sufficient to run remote FWD clients (ChUI, Swing GUI, locally installed web clients), ChUI clients and both kinds of GUI web client. If the system does have a graphical desktop environment, then it would be possible to run any of the interactive clients (e.g. Swing clients) there as well.

Prerequisites

Ubuntu 16.04 System

This process does not install the Ubuntu operating system itself. It is assumed that there are two existing systems (or virtual machines) running Ubuntu 16.04. While it is possible to run the automated installation on a TARGET Ubuntu 16.04 system that has had other software installed and configured, starting with a fresh install will ensure that the process will work. The controller is not sensitive to this same issue.

Project Configuration

The application must have an established project configuration. This includes the conversion tool configuration and scripts for conversion as well as the configuration needed for executing the converted result.

The project configuration DOES NOT include the application's source code.

To create a project configuration for an application, start with ChUI Hotel Project as a Template or GUI Hotel Project as a Template. These provide a project configuration that can be customized for your project.

If a system is needed for exploration and prototyping purposes, the two sample projects can be used as is (ChUI Project Configuration, see Hotel ChUI Demo Application or GUI Project Configuration, see Hotel GUI Demo Application).

In short, to create a runtime system you must have an existing project configuration or one of the FWD sample projects. The project configuration must be zipped up without any top level directory included in the zip. This must have the same folder structure as the Hotel demo projects. The zip will be extracted to /opt/<appname>/ folder in the TARGET system.

In the instructions below, the project configuration zip will be referred to as <fwd_app_cfg_zip>.

FWD

By default the process will download the latest FWD code. You may override this to use a specific version. The public versions available can be found in Downloads. In the instructions below, the FWD zip will be referred to as <fwd_zip>.

In the case where you are making edits to the FWD project and need to build this zip for your customized FWD distribution, the zip file must have a root p2j/ folder. It will be extracted to /opt/ and a symbolic link /opt/<appname>/p2j/ will be created, targeting the /opt/p2j/ folder.

Converted Application

There are two ways to deploy an application:

  1. Put the 4GL source code on the TARGET system and run conversion. This is called convert_in_place mode. This is useful for development and test systems.
  2. Run conversion on some other system and gather the converted results (no source code) for deployment to the TARGET system. This is called deploy_preconverted_result mode. This is most common for production systems.

These two modes are mutually exclusive: you can either deploy for conversion or deploy a preconverted application.

Convert From 4GL Source on the TARGET System

The following inputs are needed when running convert_in_place mode.

4GL Source Code

Create a zip file that includes all necessary 4GL source code and resources (e.g. icons, bitmaps). In the instructions below, the source code zip will be referred to as <fwd_app_code_zip>. The zip will be extracted to the /opt/<appname>/abl/ folder.

The source must be zipped up without any top level directory included in the zip. The structure of the source tree inside should contain all the directories that would normally be present when running or compiling in OpenEdge. The project configuration will have a PROPATH defined that references these locations.

Schemata

Create a zip file that includes all necessary 4GL schema files (in .df form). In the instructions below, the schemata zip will be referred to as <fwd_app_schemata_zip>. The zip will be extracted to the /opt/<appname>/data/ folder.

The source must be zipped up without any top level directory included in the zip.

4GL Source Code Patches (Optional)

This is only needed if you are converting from 4GL source code on the TARGET system.

This is an optional zip file which contains any patches to apply to the 4GL source code. It would also include a patch script named patches.sh. Without the patches.sh, nothing will be done. Normally, this would be coded to use the patch utility to edit source files based on patch files created with diff.

In the instructions below, the patches zip will be referred to as <fwd_app_patches_zip>. The patches must be zipped up without any top level directory included in the zip. If this exists, it will be extracted to the /opt/<appname>/abl/ folder and Ansible will execute the patches.sh script. The patches.sh script must reside in the top level of the zip, such that it will be found as /opt/<appname>/abl/patches.sh when it is extracted.

Possenet Code (Optional)

This is only needed if you are converting from 4GL source code on the TARGET system.

If your project uses ADM or ADM2, then it will need to convert with the Possenet version of the ADM/ADM2 framework instead of the version that is included with OpenEdge. There are other use cases where this code may be needed. Please see Possenet for details.

Download the latest Possenet code or use a specific Possenet zip. In the instructions below, the Possenet zip will be referred to as <possenet_zip>. If specified, the Possenet sources will be extracted to /opt/<appname>/abl/ folder.

To enable Possenet sources, add the fwd_possenet=true Ansible option when invoking the installation script (more details below). This is enough to let the Ansible scripts download the latest Possenet code . If you want to use a specific Possenet zip, set the fwd_possenet_url="file:///opt/<possenet_zip>" option.

Deploy Pre-Converted Results

For deploy_preconverted_result mode, all inputs will be provided in a single zip file.

In this mode you must create a zip file with the jars and conversion artifacts of a previously converted application. The easiest way to do this is to run ant deploy.dist AFTER you successfully convert (and compile). It will generate the necessary zip file in distribution/<app_name>_jars_deploy_<YYYYMMDD>.zip.

In the instructions below, the binary deployment zip will be referred to as <fwd_app_deploy_zip>. The zip will be extracted to the /opt/<appname>/ folder.

If you manually create the zip file, the source must be zipped up without any top level directory included in the zip. It should include these contents:

build/lib/*
adm_windows.json
name_map.cache
ddl/*
data/namespace/*
cfg/registry.xml

This zip is used to avoid conversion on the TARGET system. The results are run on the TARGET system using the FWD runtime environment.

Exported Database .d Files

A zip file containing the dump (OpenEdge database export) of all ABL tables as exported in .d files. The data dump files must be zipped up without any top level directory included in the zip. In the instructions below, the dump zip will be referred to as <fwd_app_data_dump_zip>. The content of this zip will be extracted to /opt/appname/data/dump/<dbname>/ folder.

If this file is missing, the data import will be bypassed.