# MSS Code Factory: A Fractal Programming System

Prev | Documentation Home | Next

## Installing a Manufactured Project

#### Installing a Windows 10 with WSL Ubuntu development environment

I may no longer have a Linux system, but Windows Services for Linux with Ubuntu 17.04 is coming along nicely. I've successfully built 2.8 under the code stack, suppressing the deprecated code warnings as I've no interest in carrying the 2.8 code base any further than it has to go.

I've been busy seeing what I can do with the combination of Windows 10 and WSL Ubuntu development environments. (I'll just refer to the Ubuntu environment as "WSL" for the future.)

I installed the JDK 9's for both environments -- Oracle JDK 9 for Windows and openjdk-9-jdk-headless for WSL.

Git and ant were installed for both environments. Ant for WSL recommends a whole bunch of extra stuff to go with it, and I installed pretty much all of the recommendations.

There were some extra Windows tools to install to support GPG signing and SSL encryption. Both environments have been configured, though I can't get GPG encryption and SSL encryption to share keys; they use different armored formats.

You'll do a lot of googling for things like "Windows SSL git config" and "Windows Kleopatra Git config", but I'm not going to document the details -- there is plenty of fine documentation out there that I just followed to get things up and running.

I pruned the JavaFX code from 2.8 and 2.9 so they can both be built with openjdk-9-jdk-headless. That means no more CFBam editor. That will only exist for the 2.10 code base.

The build environments used for the projects are as follows:

- MSS Code Factory 8 is built with WLS openjdk-9-jdk-headless
- edu.princeton.wordnet is built with WLS openjdk-9-jdk-headless
- MSS Code Factory 9 source is built with Oracle JDK 9
- MSS Code Factory 10 source is built with Oracle JDK 9

I have a collection of environment scripts:

- home-template
  - wsl-ubuntu-env
    - bin
      - InstallDevTools.bash
    - dot-bashrc
    - dot-gitconfig
    - dot-msscfrc
    - dot-profile
    - dot-vim
      - dot-netrwhist
    - dot-viminfo
    - dot-vimrc
  - windows-10-env
    - dot-config
    - dot-msscfrc
    - dot-viminfo
    - dot-vimrc
    - _viminfo

Don't forget to replace the "dot-" part of the file names with ".".

I also have a copy of the jars I depend on for Java builds in the apache.org directory of the download server. Most of these are the versions from Ubuntu 17.04 and the relevant apache.org websites, refreshed only this past fall.

I expect MSSCFHOME to be set to "d:\msscodefactory" under Windows. In theory you could point it somewhere else, but I kind of assume you're on D:. I should probably add an MSSCFDRIVE environment variable that specifies the drive letter and then an MSSCFDIR that is MSSCFDIR without the drive letter. MSSCFHOME would then be set to match. If I then specify "%MSSCFDRIVE%:" in my scripts instead of "d:", I should be able to make the installation location-agnostic, though I do assume exactly one installation per machine.

Correspondingly, MSSCFHOME needs to be set to the /mnt/drive/msscodefactory location matching the Windows directory in your .profile. You'll find the pattern strings "Your Name" and "your@email.address" littering the template files. Edit them accordingly. You'll also need to edit the SSL and GPG key ids according to your keys.

I need to document the system environment variables and PATH elements I expect you to set for the Windows 10 environment. I rely on those in my scripts.

#### Installing Manufactured Database Schemas

All of the platforms can run the Java client applications through a "bash" shell, so I've only tested the unsuffixed/Windows scripts and the .bash Linux scripts in the various 2.10 projects delivered by MSS Code Factory. Under Windows 7, you need to install Cygwin64 and add its `bin` directory to your system PATH. There are no .bat files in the samples, but it should be easy enough to craft them if you so desire.

You'll also need to install the Java 9 JDK (either from Oracle or via the add-on packages from Ubuntu) and make sure it is your default JDK if you are going to run builds rather than installing a pre-packaged 2.10 application. In the case of Windows 7, you need to install Eclipse OEPE from Oracle, and add its version of "ant" to your system PATH so it can be found by Cygwin's "bash" prompt.

In the case of the 2.10 installation packages, you just need to extract the zip file, and add its `java/bin` directory to your PATH. For Microsoft SQL Server you need to install the JDBC drivers to the appropriate `java/bin` directory. Some projects might not properly package the PostgreSQL drivers, so add those if need be as well.

#### DB/2 LUW

##### Debian Linux

After installing the DB/2 LUW database software, which creates a database administrator account (I'll call it db2admin for the sake of argument) and a default instance for the administrator data, you'll need to do an `su -l db2admin`. If you've previously installed the database instance, drop the old database, and create a new instance, `db2inst2` for argument's sake:

> `db2 drop database db2inst2`
> `db2 create database db2inst2 using codeset utf8 territory us pagesize 32 k`

Exit from the administrator account, and go to your project's `dbcreate/$projectname$/db2luw` directory. Remove any existing *.log files.

Connect to the database instance you just created, as in:

> `db2 connect to db2inst2 user db2admin using $password$`

Create the msidata1 tablespace:

> `db2 create tablespace msidata1 pagesize 32 k`

Now source the `crdb_$dbname$.bash` script. You'll see a series of messages stream by as the database is created and its initial security data populated.

> `. ./crdb_$dbname$.bash`

Disconnect from the database:

> `db2 connect reset`

A log file of the database install process is produced to `db2output.log`, or you can scroll back through the window to look for errors (which is what I prefer to do as it's much less to review than the whole log file is.)

Install the IBM-supplied JDBC `.jar` files in your project's `java/bin` directory and build the source. Add the directory to your PATH variable. Create appropriate .bash scripts for running the manufactured projects applications. There are many examples in the 2.10 projects shipped by MSS Code Factory.

##### Windows 7

After installing the DB/2 LUW database software, which creates a database administrator account (normally db2admin) and a default instance for the administrator data, you'll need to do an `su -l db2admin` and create an instance, say `db2inst2`:

> `db2 create database db2inst2 using codeset utf8 territory us pagesize 32 k`

Exit from the administrator account, and go to your project's `dbcreate/$projectname$/db2luw` directory. Remove any existing *.log files.

Connect to the database instance you just created, as in:

> `db2 connect to db2inst2 user db2admin using $password$`

Now create an "msidata1" tablespace, optionally providing arguments as defined by the IBM documentation:

> `db2 create tablespace msidata1 pagesize 32 k`

Now call the `crdb_$dbname$.bat` script. You'll see a series of messages stream by as the database is created and its initial security data populated.

> `call crdb_$dbname$.bat`

Disconnect from the database:

> `db2 connect reset`

A log file of the database install process is produced to `db2output.log`, or you can scroll back through the window to look for errors (which is what I prefer to do as it's much less to review than the whole log file is.)

Install the IBM-supplied JDBC `.jar` files in your project's `java/bin` directory and build the source. Add the directory to your PATH variable. Create appropriate .bash scripts for running the manufactured projects applications. There are many examples in the 2.10 projects shipped by MSS Code Factory.

#### Microsoft SQL Server

##### Debian Linux

Although there is no support for Debian Linux to run a Microsoft SQL Server, you can install client access software provided by Microsoft. Once you have installed the database instance on the server and extracted the Microsoft SQL Server JDBC drivers to the appropriate subdirectory of your project's `java/bin` directory, you should be able to run the manufactured Java applications from the command line by adding the project's `java/bin` directory to your PATH after performing a successful `ant` build.

##### Windows 7

Open a DOS window. Go to your project's `dbcreate/%projectname%/mssql` directory. Delete any existing *.log files. Invoke crdb_%dbname%.bat with the arguments for the name of the system running SQL Server with instance identifier, the database administrator's user name (normally "sa"), and the password for the database administrator account:

> `crdb_%dbname%.bat localhost\SQLExpress sa %password%`

The script will take a significant amount of time to run, and will produce a `crdb_%dbname%.log` file of the results of the database creation. If you search the log file for "Server", you should be able to verify that the script ran successfully.

You will need to install the Microsoft-provided JDBC `.jar` files to the appropriate subdirectory of your project's `java/bin` directory before you can build the manufactured code and run it. Creation of the appropriate project's `.bat` files for running the Java applications is left an exercise for the development team. There are many examples in the manufactured CF* 2.10 projects delivered alongside the MSS Code Factory 2.9 downloads from SourceForge.net.

#### MySQL

##### Debian Linux

After installing the MySQL database software, make sure you can connect as the administrator (normally "root") to the database server via TCP (127.0.0.1 if you're a developer.)

Exit from the administrator account, and go to your project's `dbcreate/$projectname$/mysql` directory. Remove any existing *.log files.

Run the `crdb_$dbname$.bash` script. You'll see a few summary messages go by as the database is created and its initial security data populated.

> `./crdb_$dbname$.bash -U root -P $password$`

A log file of the database install process is produced to `crdb_$dbname$-YYYYMMDD_HHhMM.log`. You can verify that the installation ran cleanly by looking for the string "ERROR", and deciding if they matter or not.

Install the MySQL-supplied JDBC `.jar` files in your project's `java/bin` directory and build the source. Add the directory to your PATH variable. Create appropriate .bash scripts for running the manufactured projects applications. There are many examples in the 2.10 projects shipped by MSS Code Factory.

##### Windows 7

After installing the MySQL database software, make sure you can connect as the administrator (normally "root") to the database server via TCP (127.0.0.1 if you're a developer.)

Exit from the administrator account, and go to your project's `dbcreate/$projectname$/mysql` directory. Remove any existing *.log files.

Run the `crdb_$dbname$.bat` script. You'll see a few summary messages go by as the database is created and its initial security data populated.

> `./crdb_$dbname$.bat root $password$`

A log file of the database install process is produced to `crdb_$dbname$.log`. You can verify that the installation ran cleanly by looking for the string "ERROR", and deciding if they matter or not.

Install the MySQL-supplied JDBC `.jar` files in your project's `java/bin` directory and build the source. Add the directory to your PATH variable. Create appropriate .bash scripts for running the manufactured projects applications. There are many examples in the 2.10 projects shipped by MSS Code Factory.

#### Oracle

It is possible, but very painful to install an Oracle XE server on a Debian "Jessie" Linux amd64 box, but I got it to work. To be honest, I can't remember all of the steps involved and I don't know which ones actually were important, so I'm not going to even try to document the process. But it can be done -- take heart!

##### Dual Platform: Linux and Windows/Cygwin64

After installing the Oracle database software, make sure you can connect as the administrator (normally "system") to the database server via TCP (127.0.0.1 if you're a developer.)

If you have previously installed an instance of the database, remove it by doing a "`drop user $dbname$ cascade;`" while you're logged in through a SQL*Plus command line.

Exit from the administrator account, and go to your project's `dbcreate/$projectname$/oracle` directory. Remove any existing *.log files.

Run the `crdb_$dbname$.bash` script. You'll see a few summary messages go by as the database is created and its initial security data populated.

> `./crdb_$dbname$.bash -H 127.0.0.1 -U system -P $password$ -D /oracle/accessible/tablespace/directory`

You only need to create the tablespaces once, so omit the -D and directory specification if you have already done so by a previous install of the database schema. You can also optionally specify the Oracle server port via "`-p $port$`" as well. There is also a "`-S $servicename$`" option, but I don't think I've ever had to use either option.

A log file of the database install process is produced to `crdb_$dbname$-YYYYMMDD_HHhMM.log`. You can verify that the installation ran cleanly by looking for the string "ERROR", and deciding if they matter or not.

Install the Oracle-supplied JDBC `.jar` files in your project's `java/bin` directory and build the source. Add the directory to your PATH variable. Create appropriate .bash scripts for running the manufactured projects applications. There are many examples in the 2.10 projects shipped by MSS Code Factory.

#### PostgreSQL

##### Debian Linux

After installing the PostgreSQL database software, make sure you can connect as the administrator (normally "postgres") to the database server via TCP (127.0.0.1 if you're a developer.)

Exit from the administrator account, and go to your project's `dbcreate/$projectname$/pgsql` directory. Remove any existing *.log files.

Run the `crdb_$dbname$.bash` script. You'll see a few summary messages go by as the database is created and its initial security data populated.

> `./crdb_$dbname$.bash -H 127.0.0.1 -U postgres -P $password$ -D /postgres/accessible/tablespace/directory`

You only need to create the tablespaces once, so omit the -D and directory specification if you have already done so by a previous install of the database schema. You can also optionally specify the PostgreSQL server port via "`-p $port$`" as well.

A log file of the database install process is produced to `crdb_$dbname$-YYYYMMDD_HHhMM.log`. You can verify that the installation ran cleanly by looking for the string "ERROR", and deciding if they matter or not.

Install the PostgreSQL-supplied JDBC `.jar` files in your project's `java/bin` directory and build the source. Add the directory to your PATH variable. Create appropriate .bash scripts for running the manufactured projects applications. There are many examples in the 2.10 projects shipped by MSS Code Factory.

##### Windows 7

After installing the PostgreSQL database software, make sure you can connect as the administrator (normally "postgres") to the database server via TCP (127.0.0.1 if you're a developer) from the DOS command line.

Exit from the administrator account, and go to your project's `dbcreate/$projectname$/pgsql` directory. Remove any existing *.log files.

Run the `crdb_$dbname$.bat` script. You'll see a few summary messages go by as the database is created and its initial security data populated.

> `crdb_$dbname$.bat 127.0.0.1 postgres $password$ C:\postgres\accessible\tablespace\directory`

You only need to create the tablespaces once, so omit the directory specification if you have already done so by a previous install of the database schema. The scripts do not allow for specifying a port under Windows.

A log file of the database install process is produced to `crdb_$dbname$.log`. You can verify that the installation ran cleanly by looking for the string "ERROR", and deciding if they matter or not.

Install the PostgreSQL-supplied JDBC `.jar` files in your project's `java/bin` directory and build the source. Add the directory to your PATH variable. Create appropriate .bash scripts for running the manufactured projects applications. There are many examples in the 2.10 projects shipped by MSS Code Factory.

#### SAP/Sybase ASE

##### Debian Linux

After installing the SAP/Sybase ASE database software to /home/sap/sybase, which creates a database administrator account "sa" and the database server instance itself, you should verify that you can log in to the sa account:

> `isql -U sa -P password -S HOSTNAME -D master`

Review the script for creating the default device in your project's Sybase script directory, and make sure it points to where you want to create the default database device. Note that the script will only create the device if it doesn't already exist, so if you've resized it since the initial creation, those resizing changes won't be lost.

You do not need to be logged in to the sap or sybase accounts to run the database creation scripts; you just need to be able to log in via isql as "sa".

Run `crdb_$dbname$.bash` script. Very few messages are logged to the screen, but you can open another window and tail the log file that is being created if you want to monitor the script's progress.

A log file of the database install process is produced. To review the log file for errors, use something like the following:

> `grep Msg *.log -A 5 | more`

There will likely be an error about the user for the database already existing, as well as a number of 2007 messages for stored procedures being used/referenced before they have been defined/installed. Those messages are normal and can be ignored.

### Deploying and initializing your project

There are sample Tomcat 8 server.xml configuration files for the http XMsg server and the https SM server in cfacc-server-http.xml and cfacc-server-https.xml respectively. Download them, rename them to "server.xml" in the appropriate deployments, and edit them to replace all occurences of the CFAcc references with ones appropriate for your project.

The SM (Security Manager) war is deployed with HTTPS enabled, while the XMsgSrv war is deployed over HTTP and implements its own encryption schema using AES256.

You'll need to use the Java keytool to create RSA 2048 bit key pairs for the XMsg server and for your client device.

`keytool -genkeypair -keystore $keystoreFileName -storepass pw -keyalg RSA -keysize 2048 -alias $deviceName -validity 2000 -storetype jceks`

You need to change all the references for CFDbTest210 to the name and version of your project, and it is particularly important to update the database PoolClass variable to specify the class name of the database connection pool for your project and the database you are using to run your server (the sample configurations are for Tomcat 8 with PostgreSQL.)

In order for users to be able to register new accounts via the Security Manager pages, the Java mail configurations have to be specified and valid. A confirmation email gets sent out when the user registers a new account, and unless they continue the registration process using the link provided by that email, they will not be allowed to log in to the system.

Launch the security manager web server and use a browser to navigate to the default index.html page for the services. You'll be redirected to initialize the server's password and cluster information, then redirected to the login web form. Note that I do not think you can run the HTTPS and HTTP servers at the same time in one web container instance, because the Security Manager and XMsgSrv would each try to initialize the global database connection pool and probably cause problems for each other as a result.

Now launch your Custom JavaFX HTTP GUI client. It will initialize it's configuration file, which you can then edit to point to your preferred JCEKS key store, and specify the name of the device/key alias of an RSA 2048 key pair. Once you've done so, relaunch the client application.

You'll be prompted by the client application for your keystore and key passwords, after which a window is displayed with the device name and export key text. Leave that window alone for the moment.

Log in to the Security Manager web interface as "system" using the password you configured, and add a device. Copy-paste the device name from the client application to the appropriate form field, and then copy-paste the key text to the appropriate form field. When you submit the device public key information, the server will verify that it can use the key for authentication, and save it as the default for the system account. Note that you can have as many device keys configured as you like.

Now you can launch the XMsgSrv war in it's web server.

Once the XMsgSrv war is started, you can log in to the client. If you launched the server in debug mode through Eclipse, a browser will have been started and redirected from index.html to the server's providing URL. Copy-paste that URL to the Server URL field of the login form.

The cluster has to be either "default" or "system". If it's "system", then the tenant also has to be "system". If it's "default", you'd normally be able to use any tenant name you've created under the default cluster.

You should get a connected dialog box, and then be able to navigate around the Swing GUI.

Don't forget to log out when you're done.