This topic is under construction for the 24.3 (March 2024) release of LabKey Server. For current documentation of this feature, click here.
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-level or project-level file roots.
Topics
Note that if you are using a
pipeline override, it will supersede settings described on this page for file roots.
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 > Configuration > Files.
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 overridden. 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 > 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.
Site-Level File Root
The site-level file root is the top of the directory structure for files you upload. By default it is under the LabKey Server installation directory, but you may choose to place it elsewhere if required for backup, permissions, or disk space 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. Unless the site-level root has been overridden at the
project or folder level, files will be stored under the site-level root.
You can specify a site-level file root at installation or access the "Configure File System Access" page on an existing installation.
- Select (Admin) > Site > Admin Console.
- Under Configuration, click Files.
Change the Site-Level File Root
When you
change the site-level file root for an existing installation, files in projects that use file roots based on that site-level 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.FileContentService.addFileListener(), and fix up the paths stored in the database within its fileMoved() method.
Files located in projects that use pipeline overrides or in folders with their own project- or folder-level file roots will not be moved by changing the site-level file root. If you have set project-level roots or pipeline overrides, files in these projects and their subfolders must be moved separately. Please see
Troubleshoot Pipeline and Files for more information.
Changes to file roots are
audited under Project and Folder events.
Block Potentially Malicious Files
Files with names containing combinations like " -" (a space followed by a hyphen or dash) can potentially be used maliciously (to simulate a command line argument). Administrators can block the upload of such files with two site-wide options.
- Block file upload with potentially malicious names: Blocks direct upload and drag-and-drop of files.
- Block server-side file creation with potentially malicious names: Also blocks server-side actions like import of folder archives containing wiki attachments with potentially malicious names, as these attachments are represented as "files" in the folder archive format.
Project-level File Roots
You can override the site-level 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.
Changes to file roots are
audited under Project and Folder events.
Folder-level File Roots
The default file root for a folder is a subfolder of the project file root plus the folder name. If the project-level root changes, this folder-level default will also change automatically to be under the new project-level root.
To set a custom file root for a single folder, follow these steps:
From your folder:
- Select (Admin) > Folder > Management.
- Click the Files tab.
Changes to file roots are
audited under Project and Folder events.
Migrate Existing Files
When you change the site-level file root for an existing installation, the entire directory tree of files located under that site-level file root are automatically moved to the new location (and deleted in the previous location).
When you select a new project-level (or folder-level) file root, you will see the option "Proposed File Root change from '<prior option>'." Select what you want to happen to any
existing files in the previous root location. The entire directory tree, including any subfolders within the file root are included in any copy or move.
Options are:
- Not copied or moved: Default
- Copied to the new location: The existing files stay where they are. A copy of the files is placed in the new file root and database paths are updated to point to the new location.
- Moved to the new location: Files are copied to the new location, database paths are updated to point to this location, then the original files are deleted.
Note: All work to copy or move the entire directory tree of files is performed in a single pipeline job. The job will continue even if some files fail to copy, but if any file copy fails, no deletion will occur from the original location (i.e. a move will not be completed).
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
- any children of the above
Administrators can select which directory is exposed by clicking the
(triangle) 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):
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.
- 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, and @cloud 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.
Map Network Drive (Windows Only)
LabKey Server runs on a Windows server as an operating system service, which Windows treats as a separate user account. The user account that represents the service may not automatically have permissions to access a network share that the logged-in user does have access to. If you are running on Windows and using LabKey Server to access files on a remote server, for example via the LabKey Server pipeline, you'll need to configure the server to map the network drive for the service's user account.
Configuring the network drive settings is optional; you only need to do it if you are running Windows and using a shared network drive to store files that LabKey Server will access.
Before you configure the server below, your network directory should already be mapped to a letter drive on Windows.
- Select (Admin) > Site > Admin Console.
- Under Configuration, click Files.
- Under Map Network Drive, click Configure.
Drive letter: The drive letter to which you want to assign the network drive.
Path: The path to the remote server to be mapped using a UNC path -- for example, a value like "\\remoteserver\labkeyshare".
User: Provide a valid user name for logging onto the share; you can specify the value "none" if no user name or password is required.
Password: Provide the password for the user name; you can specify the value "none" if no user name or password is required.
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" file 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 (triangle) 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 (triangle) on the Files web part, and select Customize.
- Open the "@filesets" node, 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 an example showing how to display a named file set using the JavaScript API, see
JavaScript API Examples.
Disable File Upload Site-Wide
Site Administrators of Premium Editions can disable file upload across the entire site. When activated, file upload to both the file and pipeline roots will be disabled.
When file upload is disabled, the
Upload button in the File Repository is hidden. Also, dragging and dropping files does not trigger file upload. Users (with sufficient permissions) can still perform the following actions in the File Repository, including: download, rename, delete, move, edit properties, and create folder.
Note that attaching files to issues, wikis, or messages is
not disabled by this setting.
Changes to this setting are
logged under the
Site Settings Events log.
To disable file upload site-wide:
- Go to (Admin) > Site > Admin Console.
- Under Configuration, click Files.
- Place a checkmark next to Disable file upload.
- Click Save
Related Topics
