Whenever possible, OpenVista and GT.M should be installed to the same standard locations on the Linux filesystem.  Packages of OpenVista and GT.M can then be created that will install files to these standard locations, and scripts and utilities will have a predictable place to look for OpenVista and GT.M files.  Further, OpenVista itself can be modified to auto-discover its own instance name ("namespace") by inspecting the name of the directory it's in.

The following are suggested filesystem locations for OpenVista and GT.M.

GT.M

GT.M binaries should be installed in /opt/lsb-gtm/<version>_<platform>, e.g., /opt/lsb-gtm/V5.3-002_i686 or /opt/lsb-gtm/V5.3-002_x86_64.  By installing each version of GT.M to its own directory, we can change the version of GT.M in use on a per-process basis by changing the values of the $PATH and $gtm_dist environmental variables, which may aide in upgrading GT.M.

OpenVista

OpenVista instances should be installed in /opt/openvista/<instance_name>, where instance_name is a short identifier given to the OpenVista instance.  This identifier is used as the UCI when configuring OpenVista.  It is analogous to the namespace name in Caché.  Because each instance has a unique identifier, several instances of OpenVista can exist simultaneously on a single server - you may have a production instance and an instance used for training, for example.

Unlike GT.M, which is installed into a directory whose name includes the version of GT.M installed there, the directory that houses OpenVista instances is simply named /opt/openvista because the various instances of OpenVista found below /opt/openvista may be different versions of OpenVista.  This is not a problem because OpenVista has its own update mechanism (KIDS), and unlike GT.M, you do not typically replace one installation of OpenVista with another when you upgrade - doing so would wipe out your database.

Each OpenVista instance should have the following directory structure:

/gtm
/globals
/journals
/routines
/objects
/images
/backups
/etc
/tmp

GT.M is should be a symlink to the version of GT.M being used by this instance of OpenVista, e.g., /opt/lsb-gtm/V5.3-002_i686.  Any configuration that contains the GT.M directory (e.g., scripts that set $gtm_dist) should point to this symlink instead of the GT.M directory in /opt directly.

The globals directory houses GT.M database files (.dat files) and the global directory file (mumps.gld) which maps global variables and locks resource names to database files.

GT.M journal files are written to the journals directory.

The routines directory contains MUMPS routines (.m files).

On proudction instances, for simplicity, all routines are stored in the top level routines directory.  Putting all the routines in a single directory avoids issues with KIDS, VPE, and other tools reading and writing routines to the wrong directory.  It comes at the cost of flexibility - you cannot share certain routines across instances and you cannot separate "released" routines from "hotfix" or "patch" routines.  However, for production environments, we want to encourage all changes be delivered through KIDS anyway, so the loss of a "patch" directory is not a problem.  Also, in a production environemnt, we want the instance to be completely isolated from other instances (which may be used for training or development), so the inability to share routines is not a factor, either.

On revision-controlled "progenitor" instances, no routines are stored in the routines directory itself; the routines are stored in subdirectories that reflect the origin of the routine.

• development – code that is under development; this directory should always be empty in production environments
• hotfixes –  code not yet part of any Kernel Installation and Distribution System (KIDS) build or other distribution
• customer –code that is part of a customer-specific KIDS build
• medsphere – Medsphere-owned code that is part of a KIDS build
• vendor – code from third-party vendors, e.g., the Victory Programming Environment
• foia – unmodified code from the U.S. Department of Veterans Affairs (VA)

Some routines exist only in one tier, such as the Victory Programming Environment routines, which are unique to the vendor tier. Other routines may have versions in more than one tier, e.g., some FOIA routines may reside in the foia tier, while Medsphere-modified versions of the same routines reside in the medsphere tier.  In this case, the routine in the higher tier is used by GT.M.  The tiers are ordered so that Medsphere-modified versions of routines take precedence over stock FOIA routines, hotfix routines take precedence over the same routines in any other tier, etc.

On development instances, or in an Application Service Provider (ASP) enivronment, the routine layout may be customized to allow sharing of certain routines to save disk space and memory.  The advanced setup required for these environments is beyond the scope of this proposal.

GT.M object files are written to the objects directory.

Images uploaded to OpenVista through its document imaging feature including patient photos, scanned documents, and images are stored in the images directory.

Backups are written to the backups directory.

The etc directory holds configuration files that are specific to this instance.  Other configuration-like files such as generated SSH keys are also stored here.

Temporary files are stored in the tmp directory.

Traditionally, single-letter directory names have been used to house routines, globals, objects, etc.  While spelled-out directory names such as "routines" and "globals" are less MUMPS-y than single-letter directory names, spelled-out directory names are more self-explanatory for Linux system administrators who may be unfamiliar with GT.M, MUMPS, and OpenVista.  Also, when using an interactive shell, working with spelled-out directory names requires the exact same number of keystrokes as single-letter directory names - i.e., r<tab> will auto-complete "routines/" for you; if you were using single-letter directory names, you would have had to type r<tab> or r/ anyway.

Some VistA directory layouts include a bin directory to house scripts used to set up the environment, perform backups, etc.  Instead of a per-instance bin directory, OpenVista uses one set of scripts for all instances of OpenVista on the system.  Scripts to manage OpenVista are installed from packages to /usr/bin.

Multiple Filesystems

On production systems, it may be desirable to separate OpenVista files onto different partitions based on their file type so that the underlying physical storage can be configured separately based on the different access, storage, and data retention requirements of databases, journals, and images. For example, you might create separate filesystems for databases, journals, and images. The journals partition might reside on a physically separate disk from the databases partition for increased isolation and fault tolerance, and the images parition may be mounted across the network from a machine with more storage.

There are multiple ways to accomplish this, and each method has strengths and weaknesses.  The tools created as part of the OpenVista/GT.M Integration Project will only create the directory structures outlined above - because there are so many ways to configure the physical storage, we leave it up to the system administrator.

The most straightforward and fault-tolerant way to separate files by type and by OpenVista instance is to mount a different filesystem in place over the existing directory (after moving the files first, of course).  For example, an administrator may want the journal files for the production instance to live on a separate disk, so she may mount /opt/openvista/production/journals to /dev/sdb1.  /dev/sdb1 is just an example - the underlying device may be an LVM logical volume, MD device, NFS share, or SAN device.  The disadvantage to this approach is filesystem proliferation - if you isolate the four different filetypes in four separate partitions and you have three instances of OpenVista, you have twelve filesystems to create and manage.

Another approach is to isolate the files by file type only.  For example, if you want images from all instances of OpenVista to live on a single NFS-mounted share, you might mount the NFS share to /images, then replace the images directories in the various OpenVista instances with symlinks pointing to /images/<instance_name>.  For example:

/images                                                # NFS-mounted directory
/images/production                                     # contains images from production instance
/images/training                                       # contains images from training instance

/opt/openvista/production/images -> /images/production # symlink to real location
/opt/openvista/production/training -> /images/training # symlink to real location

Note that you can mix and match approaches for different types of files.  For example, you may want each instance's journals to reside on their own isolated filesystems so that unexpected rapid journal growth in one instance will not affect the others, but every instance's images are stored on a single filesystem.

In some cases, you may not want to separate the files at all - on a virtual machine used for demos, it may be acceptable to have everything to live on a single filesystem.

File and Directory Permissions

To help isolate OpenVista from the rest of the Linux system, /opt/openvista should be owned root:openvista and chmod'd 2750, i.e., only members of the openvista group would have read access to the OpenVista instances under /opt/openvista. All files and directories in each instance should also be owned by the openvista group - the sticky bit helps with that.  Within each instance, directories under which files are created and removed in normal operation such as tmp should be chmod'd 2770, meaning group write access is allowed.  Care should be taken that users create files with group write permission so that other members of the openvista group can update the files they create.  Directories that have static contents such as globals should be chmod'd 2750.  (Note that while the database files themselves may change in normal operation, new files should not be created in the globals directory.)  Since all members of the openvista group require write access to the database files, no futher attempt is made to restrict users in this group at the Linux filesystem level.  Further restrictions should be imposed by OpenVista itself.