View source for HOWTO Install and Use the CVMFS Client

We use CVMFS to distribute our software at remote productions sites, like the OSG and NERSC. Binaries, resource files, CCDB SQLite, and helper scripts are all available via CVMFS. This HOWTO will describe how to install the CVMFS client on a local Linux machine. After that, all of the pieces needed to build and run GlueX software locally on the machine are available if the native OS is CentOS 7 Linux. If some other OS is run on the local machine, and singularity is available, CVMFS itself will provide a CentOS 7 singularity container that can be used to run the GlueX software.

The procedure described below requires root access. If root access is not available, there is an alternate method for accessing CVMFS from user space described in [[HOWTO use prebuilt GlueX software from any linux user account using cvmfsexec|this HOWTO]]. At this writing, the alternate will only work for RedHat, CentOS, and SUSE distributions.

Disclaimers:
*This version of the HOWTO describes a build from the source code. Other options for installing the CVMFS are described in the [https://cvmfs.readthedocs.io/en/stable/cpt-quickstart.html# CVMFS Getting Started Guide].
* The configuration steps are pulled from the guide, but modified to be relevant for GlueX.
* These instructions are appropriate for an installation on a single host. If the client is meant to be used by a large cluster, there are additional steps needed to maintain performance.
* Running GlueX software from inside a singularity container is assumed. This is not strictly necessary, but the instructions are specific to this use case. 

== Installing the CVMFS Client ==

The source code is available from GitHub. To get it:

  git clone https://github.com/cvmfs/cvmfs

Checkout a tagged version:

  cd cvmfs
  git checkout cvmfs-2.8.1

There is an INSTALL file in the top-level directory, but the gist is to run, from the top-level directory:

  mkdir -p build
  cd build
  cmake ../
  make
  sudo make install

The tricky part is to get a successful cmake. That requires that all packages needed as dependencies are installed. The list of packages that need to be installed depends on the distribution and the roster of packages already installed, as usual. Thus a one-size-fits-all list does not exist. Here are some hints:

* '''Fedora 34''': fuse-devel, libcap-devel, autofs
* '''Ubuntu 20.04.4''' : autofs, python-setuptools, libfuse-dev, libcap-dev, unzip, attr and the build_scrips prerequisites for Ubuntu 20.04

Collaborators are encouraged to contribute to these hints.

== Configuring the CVMFS Client ==

All commands in this section require root privilege unless otherwise noted.

=== Configure AutoFS ===

Run

  cvmfs_config setup

This will modify the autofs configuration.

=== Start AutoFS ===

Fedora:

  systemctl restart autofs

=== Create default.local ===

Create the file /etc/cvmfs/default.local. It should contain:

  CVMFS_REPOSITORIES=oasis.opensciencegrid.org,singularity.opensciencegrid.org
  CVMFS_CLIENT_PROFILE=single

=== Verify the File System ===

Run

  cvmfs_config probe

This can be run from a non-privileged account. Here is example output:

  $ cvmfs_config probe
  Probing /cvmfs/oasis.opensciencegrid.org... OK
  Probing /cvmfs/singularity.opensciencegrid.org... OK

== Running GlueX Software==

==== Install Singularity ====

* '''RedHat-like distributions''':
** old school: yum install singularity
** new school: dnf install singularity

==== Run the Container ====

  singularity shell --cleanenv --bind /cvmfs /cvmfs/singularity.opensciencegrid.org/markito3/gluex_docker_prod:latest

You will be placed in a bash shell in your home directory. /group/halld is mounted, just like at JLab. You will not see all files under /group/halld, but those needed to build and run GlueX software will be there. In particular you can set up your environment in the usual way:

  source /group/halld/Software/build_scripts/gluex_env_boot_jlab.sh
  gxenv

A simple test of your environment:

  hd_root

should give you the help message.