Installing Facets
Some Caveats
Facets is designed to be a high performance extremely scalable Java database. This comes with a couple of conditions attached to it. Facets must be installed on a machine whose IP address always resolves correctly back to it's hostname. If this is not the case on your machine please resolve it prior to attempting to install and operate Facets. If your machine is not correctly configured, Facets may refuse to start some of the required services. Please also ensure that you read the installation guide regarding setting shared memory limits, since this is vital to the correct operation of Facets.
Suggested Configurations
When installing Facets the installer will install the files into a default directory unless otherwise specified. It is often convenient to install the Facets installation into it’s own directory that is owned by a particular user. Having the files that belong to Facets owned by a specified user is quite useful from a security and permissions perspective. Depending on whether it is necessary to run multiple instances of Facets on a single machine it may be better to carefully lay out the installation directory prior to creating the various portions of Facets.
If the installer is allowed to create and start an instance of Facets during the installation phase, then a default configuration will be created and started. The default configuration is convenient for most tasks, but if you wish to customize the installation it is better not to let the installer create and start an instance for you. To install a customized version of Facets proceed as detailed below, substituting the name of the user you wish to use for gsadmin and the directory that you wish to use for /opt/gemstone
- Create a user that will own the Facets directories and files. On Linux this will typically involve two steps:
>/bin/useradd -d /opt/gemstone gsadmin
The above creates a locked user account with the name of gsadmin and sets the users home directory to be /opt/gemstone.
Force a password change the next time this user logs in:
>/usr/bin/chage -d 0 gsadmin
Set the inital password of the gsadmin account to "password":
>/usr/bin/usermod -p “password” gsadmin
- Create the directory that you wish the Facets files installed into
actually create the directory
>sudo mkdir -p /opt/gemstone
This assumes we wish to install Facets into a directory called /opt/gemstone. We prefix the command with sudo to ensure that we have enough privilege to create the directory. The -p option creates all the intermediate directories in the event that they do not exist
>sudo chown gsadmin /opt/gemstone
this changes the ownership of the directory so that it is owned by the gsadmin user
define an enviroment variable that points to this directory, we will call it GEMSTONE
>setenv GEMSTONE /opt/gemstone
- Install Facets
Log in as gsadmin, with the password that was specified in step 1 above, you should be prompted to change the password, change it to something secure and appropriate.
Locate the directory that contains the Facets media (either the directory that you downloaded and unpacked the Facets download into, or the directory where the CD ROM was mounted) for example, on many Linux systems CDs are mounted at /media/cdrom, so in the example we will assume that the Linux CD was mounted there
Start the installer:
>sh /media/cdrom/facets/setupLinux.bin
this command will run the installer and the following window should appear:
Figure : Installer
accept the defaults until the following contents appear
Figure : The Facets Installer directory selection
change the default directory to that which was created above in step 2
allow the installer to install the files, when the following contents appear:
Select the option for skipiing creation and startup of a Facets instance. Allow the installer to complete.
Add the $GEMSTONE/bin directory to the path for the gsadmin user, (the mechanism for doing this varies from shell to shell). It is important that the $GEMSTONE/bin directory appears first in your path, since some versions of Linux may be installed with a version of Java and Facets may not operate correctly when run using that version. Ensuring that the $GEMSTONE/bin directory is first in your path will ensure that the Facets Java VM is used in preference to all others.
reload the environment
- Create a GNS directory and a GNS
The Global Naming Service, (GNS) is used to keep references to all named objects generated by the Facets system itself. All the running portions of a Facets systems can be retrieved from within the GNS. We need to create a GNS before we can create a Facets system. It is good practice to create a directory for the GNS files to be stored in, since if we do not create one, Facets will spread the contents of the GNS around in whatever directory we are in when we create it.
create the directory for the GNS, for this example we use /opt/gemstone/gns
>mkdir /opt/gemstone/gns
change into that directory
>cd /opt/gemstone/gns
now actually create the GNS, we use the gsjadmin command to create the GNS, gsjadmin is the workhorse of Facets administration since it can be used to perform most administrative tasks required for a Facets installation
>gsjadmin create gns
the GNS has now been created, so we need to start it before we can do anything else
>gsjadmin start gns
- Ensure that a locks directory exists in the gsadmin home directory
change into the gsadmin home directory by issuing the command
>cd /opt/gemstone
ascertain whether the locks directory exists by issuing the command
>ls locks
if the reply is "ls: locks: No such file or directory" or something similar, you need to create a locks directory
to create a locks directory, issue the following command
>mkdir locks
- Finally we can create a Facets system by issuing the following command
(replace "systemName" with the name that you wish the system to be known by)
>cd /opt/gemstone/gns
>gsjadmin create system systemName
finally start the system by issuing the command
>gsjadmin start system systemName
The installer will install the files into a default directory unless otherwise specified. It is often convenient to install the Facets installation into it’s own directory that is owned by a particular user. Having the files that belong to Facets owned by a specified user is quite useful from a security and permissions perspective. Depending on whether it is necessary to run multiple instances of Facets on a single machine it may be better to carefully lay out the installation directory prior to creating the various portions of Facets.
If the installer is allowed to create and start an instance of Facets during the installation phase, then a default configuration will be created and started. The default configuration is convenient for most tasks, but if you wish to customize the installation, it is better not to let the installer create and start an instance for you. To install a customized version of Facets proceed as detailed below, substituting the name of the user you wish to use for gsadmin and the directory that you wish to use for /opt/gemstone.