Document Root (docroot)

A document root directory, also known as a docroot directory, is the main directory for the TFServer where the files and database directories are stored. It is the base directory from which the TFServer serves files and processes requests.

The docroot directory is a required directory for ALL TFServer configurations except the in-memory only (diskless) TFS implementation (see Transactional File Server Interface with In-memory Database Library).

When a user accesses a TFS, the TFServer looks for the requested database within the document root directory. The TFServer then retrieves the requested database information and sends it back to the user's TFS client for processing.

Each database instance managed by a TFS will be stored in a sub-directory of the docroot named with the database name including the .rdm extension.

Location

The specific location of the document root directory can vary depending on the TFServer software and its configuration. For example, the default docroot directory for the TFServer is the current working directory when the TFServer process is started. The developer can direct the TFServer to use another directory on startup by supplying a command-line option for the RaimaDB utilities (see rdm-tfs) or programmatically using a configuration setup option prior to starting the TFS (see rdm_tfsSetOption()).

The default location for the docroot directory is determined by the following precedence prior to instantiating the TFS:

  1. The docroot directory is explicitly set.
  2. The docroot directory is defined in a system environment variable RDM_DOCROOT.
  3. The docroot directory is defined as the current working directory when the TFS is instantiated if the current working directory (CWD) is not the root directory of the file system. (Not recommended)

In other words, you will only need to set the docroot if your database is located outside of your projects root directory. If working with a remote TFS or client/server application, the docroot will not be applicable as the application will look to where the remote TFS is hosted.

Setting the DOCROOT for the TFS Examples

The selected location of the docroot directory should be sufficient size to hold the database instances that will be managed by the TFS.

For client/server applications, the docrootis set on the TFS host. For example, if the rdm-tfs utility is used as the TFS host, the docroot can be set by: 1) defining the RDM_DOCROOT environment variable before executing rdm-tfs; 2) providing the --docroot option on the command line; or, 3) use the CWD of the rdm-tfs application when launched (not recommended).

DOCROOT Location Rules

  1. The docroot directory CANNOT be the root directory of the file system;
  2. The docroot path specification CANNOT be a relative path;
  3. The docroot path must be writable for the TFS process;
  4. The docroot directory should not used for storing files not managed by the TFS.