getting_started.txt

Getting Started
===============

The WEBDIR environment variable must be set prior to running the regression tests (and should be added to the
user's ".profile" or equivalent if that has not been done already).

export WEBDIR=/srv/www/htdocs

After cloning the repository run "config" in order to configure the system for 3rd party dependencies (and to
set the default server port) then "make all" to build all of the targets and then run "do_tests" batch/script
to test that all core functionality is working:

./config
make all
./dotests

(if using Windows need to omit the ./ prefixes so just "config" and "dotests" and "set" rather than "export")

The next step is to make sure that MySQL is installed and operating. The following steps will create a DB for
testing the system, populate this DB with tables and data and check that all is functioning as expected:

./create_db ciyam
./init Meta ciyam
./test -t=../tests Meta_tests.sio
./drop_db ciyam

The "ciyam" DB should only be used for regression test purposes (by repeating the above steps) so now another
DB needs to be created for the IDE itself:

NOTE: In order for this second init to work the user must have "rwx" permissions for the WEBDIR directory.

./create_db Meta
./init Meta Meta

************************ Alternative DB creation for storage hubs with no web server ************************

export WEBDIR=.
export CIYAM_TEST_STORAGE=1
./create_db Meta
./init Meta Meta
export CIYAM_TEST_STORAGE=
export WEBDIR=

*************************************************************************************************************

The next step is to make sure that the web server's FCGI is installed and operating. Run the following batch/
script to install the FCGI testbed:

./install_test_fcgi

Assuming no errors occurred you should now be able to access the webpage: http://localhost/test_fcgi.html

It will present a HTML form with a Perform Post Request button. To verify that FCGI is working correctly next
click on the button. Output should look something like the following:

Posted Data: name=Joe+Bloggs&age=&sex=male&submit=Perform+Post+Request...
(if the browser prompts to download the .fcgi file then configure Apache according to fcgi_configuration.txt)

If you go "back" to the page and then click the button again you should now see some like this:

Found HTTP_COOKIE: TEST=TEST_COOKIE

Posted Data: name=Joe+Bloggs&age=&sex=male&submit=Perform+Post+Request...

If all has gone well then it is time to install the IDE application which is done as follows:

./setup Meta meta
./install_fcgi ciyam_interface meta
./install_fcgi upload meta
./install Meta meta index

For a production environment the initial "ciyam_server.sid" file (created by the "config" batch/script) needs
to be removed prior to starting the application server (leave this file if is a development environment or an
application server that is intended just to act as a storage hub).

./save_identity
./erase_identity

To use the application you'll need to make sure that the application server (ciyam_server) is running. To run
it with Windows use "start /min ciyam_server" and under Linux "./ciyam_server &". Once the application server
has started and is "listening" you are now nearly ready to create your first web application.

***************************** Extra steps if MySQL 'root' password is not blank *****************************

If you have a non-blank 'root' password for your MySQL server then this password will need to be known by the
application server in order for the 'Meta' application to be able to create (and drop) a DB. This password is
stored in the application server's main configuration file (ciyam_server.sio) in an encrypted base64 format.

Looking at the default ciyam_server.sio file you'll notice the following line:
# <sql_password>*a8634af27d824c4bbf916e16cbd33284:GKmbnPd+f9Ar4AuAvvQNLg==

The comment character ('#') will need to be removed and then the base64 changed to the encrypted form of your
MySQL root password. To determine the encrypted base64 password a protocol command "encrypt" exists. For ease
of use a batch/script called ./password can be used to determine the correctly encrypted password value. This
script can be used in one of two ways. The first is as follows:

./password my_password
#84d63bc99961b749e52cd4a81f219f0c:Q1MTn/kwcSl4VjGlmv0dgw==

The second method is to run the script without passing the password as an argument (use this way if you don't
want the password it to be visible on the screen or kept in command history). If you use this method then you
will be prompted to type in the password (which will not be echoed).

./password
Password:
#c67d4b5a8d9c48a193cfd37423c9c288:YqNAPnlu7jz6eyY7YexRuA==

Once you have modified the <sql_password> value in "ciyam_server.sio" (and removed the # comment marker) then
you will need to stop and restart the application server (if using Windows then focus on the "cmd" window for
"ciyam_server" and type "Ctrl-c" to shut it down and if using Linux type "fg" to bring the "ciyam_server" job
to the foreground and type "Ctrl-c" to shut it down).

*************************************************************************************************************

If all went well the you should now be able to access the IDE: http://localhost/meta

***************************** Extra step when "ciyam_server.sid" is not present *****************************

The first time you access the IDE you will be presented with a dialog for recording (or restoring) the system
identity as well as providing a master password (used to unlock the system whenever the application server is
restarted). Note that IT IS CRITICAL TO RECORD THE SYSTEM IDENTITY (and safer if done using pen and paper) as
this is used to encrypt/decrypt sensitive information such as system passwords. Also note that this encrypted
identity information is not stored until you login to Meta (the login dialog will appear after completing the
identity dialog). The encrypted master password is stored in "ciyam_server.sid" and although it includes salt
and underwent numerous rounds of SHA256 "hardening" using a very simple password would not be recommended.

*************************************************************************************************************

From the login form which should have appeared use the user id "!guest" with password "guest" (no quotes). If
you are wondering why the ! prefix it is due to the fact that users which are created as initial data for the
application do not have "hashed passwords". After you login if you change password then at the next time that
you login the ! must *not* be prepended (i.e. just "guest"). Thus for security purposes all such initial data
User records should have their passwords changed or be either removed or have their Active status switched to
off/false.

Creating an Application
-----------------------

Once you have logged in click on "Models" (in the navigation menubar) and then click "Create New" in order to
begin the application creation process. The "New Model" form will require a Name to be entered (for this test
the name "Sample" should be used).

The "Add Packages" drop list will default to the value "Standard User" which is fine (along with the defaults
for the other fields) so now simply click "Save Details" to create the new Model. After saving the "Standard"
package will automatically be installed while the "User" package will just appear greyed out (for those using
Windows an extra "cmd" window will temporarily appear while the "Standard" package is being installed).

To install the "User" package click on the greyed out "User" list item then from the "Package" view form next
click on the "Install" button. You might notice from the "Package" view form that there are a number of child
"Package Options" present. These "options" allow customisation of a package prior to installation. Because of
the fact that the "User" package has such options it is not automatically installed as the "Standard" package
was (the "Standard" package has no installation options beyond the defaulted "@has_blockchain" one).

For the purposes of creating a test "demonstration" Application the "User" package should simply be installed
with the "Package Options" as they are by default. After the "User" package has been installed (assuming that
no error occurred during installation) then click on "Applications" from the navigation menubar and as before
click "Create New" to create the Application. In order to simplify creating a new Application enter the exact
same text for Name as you used for the Model (in this case "Sample"). After typing in the Name next click the
"Save Details" button and you should see in the child "Modules" list that the Model "Sample" has been created
for you (if not then most likely the Name was not an exact match or "Add Modules Automatically" was not set).

Assuming the Application has successfully been created (if not then it is possible the MySQL root password is
not correct or present in the server configuration file), then all that remains to be done now is to click on
the "Generate" button (leaving the Generate Type as "Full Generate"). After clicking the button Windows users
(once again) will see a new "cmd" window appear. To see the application generation details click on the arrow
icon that appears below the Version field.

Assuming no problems have occurred then you should see lines of text that describe each of the artifacts that
have been created (such as the "sample" web directory, all of the source files and the "make" output which is
then finally followed by the DB construction and population with initial data).

If no errors have occurred during application generation then you should now be ready to test your first ever
CIYAM application. This should be as simple as typing "localhost/sample" into your browser (in another window
than that used for "Meta"). If the system identity was provided to Meta then you can now login using the user
id "admin" and the master password entered into the identity dialog. If the identity dialog was not used (due
to not erasing the initially generated identity) then use "!admin" and "admin" instead.

Once logged in click on "System Information" (from the navigation menubar) to see the Identity of the system.
Do not forget to click on Logout (at the top right of the page) before closing the web page.

Installing Package Types
------------------------

By default the package types which are included in the "Meta" system are functional ones (such as providing a
System singleton that can be used for holding system-wide default values and also for the User record type so
that users can be given login credentials and security permissions). Although vitally important these package
types are not so interesting (as seen in the sample application created initially).

In order to be able to create a more interesting application it is recommended to install one or more package
types that are not automatically included in "Meta". To do this you'll need to login to "Meta" using the user
id "admin".

The navigation menubar will look very different when you are logged in as "admin" as this special user is not
intended to perform standard activities but instead to perform "system configuration" and "user maintenance".
After clicking on "Package Types" you should see a small list of the automatically included packages. Too add
a new package type click "Create New". The Type Name will default to "New_Package_Type" and as this name will
be automatically changed during the Package Type "Install" it does not need to be changed so you just need to
click "Save Details" to continue.

The next step is to locate a "package bundle" which is a file ending with the extension "*.package.bun.gz" in
the project's source directory. After you "Attach" this file (which will "upload" it) you should see that the
"gz" file has been attached. Now all that needs to be done is click on "Install" (again under Windows a "cmd"
window will appear during the installation). If no error has occurred then the Type Name will have changed to
the name of the package type automatically and the various other fields will have been set.

It should be noted that some package types will have one or more dependencies upon other package types so the
order that new package types are installed is important.

For more specific information about the various Package Types that are available refer to "packages.txt".