• Sign In
  1. Start Page
  2. Collaboration
  3. Files
  4. File Administrator Guide

Set File Roots

Documentation: Version 18.1

Set File Roots

Print Print Branch
LabKey Server provides tools for securely uploading, processing and sharing your files. If you wish, you can override default storage locations for each project and associated subfolders by setting site-wide or project-level file roots.

Topics on this page:

Site-wide File Root

The site-wide file root is the top of the directory structure for files you upload. By default it is the same as the LabKey Server installation directory, but you may choose to place it elsewhere if required for backup or permissions reasons.

During server setup, a directory structure is created mirroring the structure of your LabKey Server projects and folders. Each project or folder is a directory containing a "@files" subdirectory.

You can specify a site-wide file root at installation or to access the "Configure File System Access" page on an existing installation.

  • Select (Admin) > Site > Admin Console.
  • Click Admin Console Links and under Configuration click Files.

When you change the site-wide file root for an existing installation, files located under that site-wide file root will be automatically moved to the new location. The server will also update paths in the database for all of the core tables. If you are storing file paths in tables managed by custom modules, the custom module will need register an instance of org.labkey.api.files.FileListener with org.labkey.api.files.FileContenService.addFileListener(), and fix up the paths stored in the database when its fileMoved() method.

Files located in projects that use pipeline overrides or set their own project-level file roots will not be moved. Please see Troubleshoot File Roots and Pipeline Overrides for more information.

Project-level File Roots

You can override the site-wide root on a project-by-project basis. A few reasons you might wish to do so:

  • Separate file storage for a project from your LabKey Server. You might wish to enable more frequent backup of files for a particular project.
  • Hide files. You can hide files previously uploaded to a project or its subfolders by selecting the "Disable File Sharing" option for the project.
  • Provide a window into an external drive. You can set a project-level root to a location on a drive external to your LabKey Server.
  • From your project:
  • Select (Admin) > Folder > Project Settings.
  • Click the Files tab.
  • Click Save.

You can also see or set the project-level file root by selecting (Admin) > Folder > Management and opening the Files tab.

File Root Options

The directory exposed by the Files web part can be set to any of the following directories:

  • @files (the default)
  • @pipeline
  • @filesets
  • @cloud
  • @wiki
  • any children of the above
Administrators can select which directory is exposed by clicking the triangle menu () on the Files web part and selecting Customize. In the File Root pane, select the directory to be exposed and click Submit. The image below shows how to expose the sub-directory Folder A.

Alternative _webfiles Root

Administrators can enable an alternative WebDAV root for the whole server. This alternative webdav root, named "_webfiles", displays a simplified, file-sharing oriented tree that omits non-file content (like wikis), and collapses @file nodes into the root of the container’s node.

To access or mount this root go to a URL like the following (replacing my.labkeyserver.com with your real server domains):

http://my.labkeyserver.com/labkey/_webfiles

This URL will expose the server's built-in WebDAV UI. 3rd party WebDAV clients can mount the above URL just like they can mount the default _webdav root.

To enable this alternative webdav root:

  • Select (Admin) > Site > Admin Console.
  • Click Admin Console Links and under Configuration click Files.
  • Under Alternative Webfiles Root, place a checkmark next to Enable _webfiles.
  • Click Save.

The _webfiles directory is parallel to the default _webdav directory, but only lists the contents under @files and its child containers. @pipeline, @filesets, @cloud and @wiki contents are not accessible from _webfiles.

Any name collisions between between containers and file system directories will be handled as follows:

Child containers that share names (case-insensitive) with file system directories will take precedence and be displayed with their names unchanged in the WebDAV tree. File system directories will be exposed with a “ (files)” suffix. If there are further conflicts, we will append “2”, “3”, etc until we find an unused name. Creating a subdirectory via WebDav always create a child file directory, never a child container.

Named File Sets

Named file sets are additional file stores for a LabKey web folder. They exist alongside the default file root for a web folder, enabling web sharing of files in directories that do not correspond exactly to LabKey containers. You can add multiple named file sets for a given LabKey web folder, displaying each in its own web part. The server considers named file sets as "non-managed" files systems, so moving either the site or the folder file root does not have any effect on named file sets. File sets are a single directory and do not include any subdirectories.

To add a named file root:

  • On the Files web part, click the dropdown triangle next to Files and select Customize
  • On the Customize Files page, click Configure File Roots.
  • Under File Sets, enter a Name and a Path to the file directory on your local machine.
  • Click Add File Set.
  • Add additional file sets are required.
  • To display a named file set in the Files web part, click the dropdown triangle on the Files web part, and select Customize.
  • On the File Root dropdown, select your named file set, and click Submit.
  • The Files web part will now display the files in your named file set.

For details on URL parameters used with named file sets, see Controlling File Display via the URL.

For details on displaying a named file set using the JavaScript API, see JavaScript API - Samples.

Summary View of File Roots and Overrides

You can view an overview of settings and full paths from the "Summary View for File Directories" section of the "Configure File System Access" page that is available through (Admin) > Site > Admin Console > Admin Console Links > Configuration > Files. A screenshot:

File directories, named file sets and pipeline directories can be viewed on a project/folder basis through the "Summary View." The 'Default' column indicates whether the directory is derived from the site-level file root or has been overriden. To view or manage files in a directory, double click on a row or click on the 'Browse Selected' button. To configure an @file or an @pipeline directory, select the directory and click on the 'Configure Selected' button in the toolbar.

If you add a pipeline override for any folder, we don't create a @files folder in the filesystem. The server treats an override as a user-managed location and will use the path specified instead.

Note that a @pipeline marker is used in the "Summary View for File Directories", available through (Admin) > Site > Admin Console > Admin Console Links > Configuration > Files. However, there is no corresponding @pipeline directory on the file system. The summary view uses the @pipeline marker simply to show the path for the associated pipeline.

Related Topics

Search

 

Pages

 

previousnext
 
expand allcollapse all