Desktop and Mobile

Nuxeo Drive Installation / Configuration

Updated: March 18, 2024

Requirements

To be able to synchronize folders on your computer, you need to install the Nuxeo Drive client on your computer. We provide OS-specific installers for Mac OS X and Windows, available from the Nuxeo Drive tab of the Home. For Linux, you need a PyQt4 with WebKit support.

GNU/Linux support for Nuxeo Drive is fragile and currently depends on several obsolete modules. Keep an eye on our roadmap for developments and the deployment instructions on GitHub for more information.

Support

See this up-to-date support page to know what OS vendor and version we are supporting; but also the Python version we are currently using.

Installation

Installing Nuxeo Drive Addon

This addon requires no specific installation steps. It can be installed like any other package with nuxeoctl command line or from the Update Center.

After Nuxeo Drive has been installed on the server, a Nuxeo Drive tab in the user Home, from which you can see what Nuxeo spaces are synchronized with Drive.

Installing Nuxeo Drive on Your Computer

If you try to synchronize a folder and you haven't installed the Nuxeo Drive client yet or haven't provided your credentials to the Nuxeo Drive client, you are automatically directed to the Nuxeo Drive home tab to install it.

Installing Nuxeo Drive on macOS

  1. Download the installer (.dmg file) from the Nuxeo Drive tab in the Home or from the Nuxeo Drive update site.
  2. Run the installer: drag and drop the Nuxeo Drive icon in the Applications directory.
    Nuxeo Drive is now installed on your computer.
  3. You now need to start Nuxeo Drive on your computer. A Nuxeo Drive folder will be created by the system at the root of your local home folder (/Users/USER/). This is the place where synchronized documents will be stored on your computer.

Installing Nuxeo Drive on Windows

  1. Download the Windows installer (.msi file) from the Nuxeo Drive tab in the Home or from the Nuxeo Drive update site.
  2. Run the installer: indicate where Nuxeo Drive should be installed (typically C:\Program Files (x86)) and click Next until the installation process is done. Nuxeo Drive is now installed on your computer.

    If you have any problem due to a previous installation of Nuxeo Drive you can try using this Microsoft tool to uninstall it properly.

  3. You now need to start Nuxeo Drive to use it. A new Nuxeo Drive folder will be created by the system in your local Documents folder (C:\Users\USER\Documents\). This is the place where synchronized documents will be stored on your computer.

Installing Nuxeo Drive on Ubuntu/Debian (and Other GNU/Linux Variants)

The .deb package of the client is not yet available. In the mean time you can manually install the development version. Has been reported to work on: Ubuntu >= 12.04.

To Install Nuxeo Drive on your Linux computer:

Requirements

  1. xattr

    First note that Nuxeo Drive uses Extended file attributes through the xattr Python wrapper.

    On FreeBSD, and macOS, xattrs are enabled in the default kernel.

    On GNU/Linux, depending on the distribution, you may need a special mount option (user_xattr) to enable them for a given file system.

    Check your current mount, e.g.:

    cat /proc/fs/ext4/sda3/options | grep xattr
    # "user_xattr" means the file system has xattr already enabled
    

    If the current mount doesn't have xattr, remount the filesystem with xattr. e.g.:

    sudo mount -oremount,user_xattr /dev/sda3
    
  2. Python 2.7

    Nuxeo Drive uses some packages, which are only compatible from python version 2.7. If this excludes using the standard python installation of certain OS distributions, you may still install python 2.7 manually from the download pages on your system. However, this may break other tools in your environment, who need to be consistent with the default python packages. Using Anaconda to switch between different python installs/environments may help in this case.

  3. pip

    Make sure that the latest version of pip is installed.

    sudo pip install -U pip
    

Installation

  1. Then install the required system and Python packages and the Nuxeo Drive code itself.

    Debian package manager:

    sudo apt-get install python-pip python-dev python-qt4 libffi-dev git
    

    Redhat package manager (RPM):

    sudo yum install python-pip python-devel PyQt4 libffi-devel git
    

    Then finally install the Nuxeo Drive requirements and Nuxeo Drive itself. These are common installation actions, not depending on the package manager. (warning: define the version you want in the DRIVE_VERSION variable, ex: release-2.1.113 - Find the Nuxeo Drive tags list here):

    # For Drive < 2.2.227:
    DRIVE_VERSION=release-2.1.113
    pip install -r https://raw.github.com/nuxeo/nuxeo-drive/$DRIVE_VERSION/requirements.txt
    pip install -r https://raw.github.com/nuxeo/nuxeo-drive/$DRIVE_VERSION/unix-requirements.txt
    pip install git+https://github.com/nuxeo/nuxeo-drive.git@$DRIVE_VERSION
    
    # For Drive >= 2.2.227:
    DRIVE_VERSION=release-2.2.323
    pip install -r https://raw.github.com/nuxeo/nuxeo-drive/$DRIVE_VERSION/requirements.txt
    pip install -r https://raw.github.com/nuxeo/nuxeo-drive/$DRIVE_VERSION/requirements-unix.txt
    pip install git+https://github.com/nuxeo/nuxeo-drive.git@$DRIVE_VERSION
    
  2. For now, the systray icon is not visible under Unity desktop. As a consequence, the configuration window only appears at the first launch. If you want to change it, issue the following commands:

     pkill ndrive
     rm -rf ~/.nuxeo-drive
     ndrive &
    
  3. Now configure automatic start and protocol handler:

    # Install for local user. See $XDG_CONFIG_DIRS for a system wide install
    # Configure Nuxeo Drive to load at startup
    mkdir -p ~/.config/autostart
    cat >~/.config/autostart/ndrive.desktop <<EOF
    [Desktop Entry]
    Type=Application
    Exec=ndrive
    Hidden=false
    NoDisplay=false
    X-GNOME-Autostart-enabled=true
    Name[fr_FR]=Nuxeo Drive
    Name=Nuxeo Drive
    Comment[fr_FR]=
    Comment=
    EOF
    
    # Install for local user. See $XDG_DATA_DIRS for a system wide install
    # Add handler for opening files
    cat >~/.local/share/applications/nxdrive-handler.desktop <<EOF
    [Desktop Entry]
    Type=Application
    Exec=ndrive %u
    Name=Nuxeo Drive Protocol Handler
    GenericName=Nuxeo Drive Handler
    Comment=Handle NXdrive URL
    Terminal=false
    MimeType=x-scheme-handler/nxdrive
    EOF
    update-desktop-database ~/.local/share/applications/
    
  4. You now need to start Nuxeo Drive on your computer. A Nuxeo Drive folder will be created by the system at the root of your local home folder. This is the place where synchronized documents will be stored on your computer.

Starting Nuxeo Drive

After you installed Nuxeo Drive, you need to start it manually.

Start Nuxeo Drive like any other application:

  • On macOS, Nuxeo Drive is in the Applications directory.

    When you double click on the icon, a security message appears. To bypass it, you can modify your security settings or click right on Nuxeo Drive application and click on Open.

  • On Windows, Nuxeo Drive is started from Start > Programs > Nuxeo Drive.
  • On GNU/Linux, check that $HOME/.local/bin is in the PATH, then press Alt+F2 and enter ndrive.

Upgrading Nuxeo Drive

When a new version of Nuxeo Drive is available, a message is displayed at the bottom of the systray menu.

  1. Click on the upgrade message at the bottom of the systray menu.
  2. If you want Nuxeo Drive to update silently the next time, check the box Automatically update Drive in the General tab.
  3. Click on the green icon. Nuxeo Drive is updated and automatically restarted.

Configuration

Settings

Accessing the Settings Window

On Windows

  1. Right-click on the the icon in the systray.
  2. Click on the icon and on the Settings menu item. The Settings window is displayed.

On macOS / GNU/Linux

  1. Click on the the icon in the systray.
  2. Click on the icon and on the Settings menu item. The Settings window is displayed.

The Nuxeo Drive settings window shows four tabs that enable you to customize the behavior of your Nuxeo Drive:

  • General This is where you select the general behavior of your Nuxeo Drive: what language to use, the update policy, etc.
  • Accounts Set up one or several Nuxeo Platform accounts to synchronize with Nuxeo Drive.
  • Advanced Set up your proxy, change the log level and get a zipped bug report.
  • About Information about the Nuxeo Drive version and license.

Managing Local Nuxeo Drive Accounts

You can use Nuxeo Drive to synchronize content from several Nuxeo Platform applications. This means that you can set up several accounts on Nuxeo Drive. Accounts are managed from the Accounts tab of the Settings window.

Adding a New Account

When you add a new account you need to provide the following information:

  • Name: Give a name to the Nuxeo Drive account you are setting. This is helpful when you use Nuxeo Drive with several applications.
  • Folder: Select where you want your Nuxeo Drive folder to be created.
  • URL: Type the URL of your Nuxeo application, with the /nuxeo suffix (http://NUXEO_SERVER/nuxeo for instance).
  • Username: Type your username to the Nuxeo Platform application.
  • Password: Type your password to the Nuxeo Platform application.

The creation of a new account triggers the following actions:

  • A Nuxeo Drive folder is created at the location you chose (see section Accessing the Nuxeo Drive Folder).
  • Nuxeo Drive starts synchronizing the Nuxeo workspaces or folders you indicated as synchronized in the Nuxeo Platform. It will automatically update content when there is a modification on the server.
  • In the Nuxeo Drive tab in your Home, an authentication token corresponding to the computer you are synchronizing from is displayed. The list of synchronized folders is displayed in the Synchronization roots section of the tab.

Deleting an Account

You can delete accounts from your Nuxeo Drive at any time by clicking on the Delete account button of the corresponding account, in the Settings window. The local Nuxeo Drive folder is not deleted.

Changing the Nuxeo Drive Language

By default, Nuxeo Drive is available in English and in French.

To change the language of Nuxeo Drive:

  1. Open the Nuxeo Drive Settings window.
  2. Click on the General tab.
  3. In the Language drop down list, select the language you want to use. The Settings window language is immediately changed.

Configuration Parameters

Nuxeo Drive has different parameters that you can set up through (sorted by priority):

  • Via the REST API endpoint /drive/configuration served by the server (since NXP-22946 and Nuxeo Drive 3.0.0);
  • A $HOME/.nuxeo-drive/config.ini file;
  • With a registry key inside HKEY_LOCAL_MACHINE\Software\Nuxeo\Drive (since Nuxeo Drive 2.1.331, Windows only);
  • The command line;
Parameter Default Value Description
ndrive-home %HOME%/.nuxeo-drive Define the personal folder.
log-level-file DEBUG Define level for file log. Can be TRACE, DEBUG, INFO, WARNING, ERROR. This can also be set up from the Settings window.
log-level-console INFO Define level for console log. Can be TRACE, DEBUG, INFO, WARNING, ERROR.
log-filename None The name of the log file.
locale en Set up the language if not already defined. This can also be set up by the user from the Settings window.
force-locale None Force the reset to the language.
update-site-url http://community.nuxeo.com/static/drive/ Configure custom update website. See Nuxeo Drive Update Site for more details.
beta-update-site-url http://community.nuxeo.com/static/drive-tests/ Configure custom beta update website.
debug False Activate the debug window, and debug mode.
nofscheck False Disable the standard check for binding, to allow installation on network filesystem.
proxy-server None Define proxy server. This can also be set up by the user from the Settings window.
proxy-type None Define proxy type. This can also be set up by the user from the Settings window.
proxy-exceptions None Define URLs exception for the proxy.
consider-ssl-errors False Define if SSL errors should be ignored.
delay 30 Define the delay before each remote check.
handshake-timeout 60 Define the handshake timeout.
timeout 30 Define the socket timeout.
update-check-delay 3600 Define the auto-update check delay. 0 means disabled.
max-errors 3 Define the maximum number of retries before considering the file as in error.

When use as command line argument you need to prefix with long argument modifier --.

Nuxeo Drive and Audit Logs

Nuxeo Drive makes an extensive use of audit logs to get a summary of the server-side changes.

Since Nuxeo Platform 7.3 we chose to use Elasticsearch as a default back end for audit logs. This improves scalability especially when using Nuxeo Drive with a large set of users.

That's why we strongly recommend to keep this default configuration, but you can still disable Elasticsearch for Audit Logs.

Uninstalling Nuxeo Drive

To uninstall Nuxeo Drive from your computer, you need to remove the following items:

  • The .nuxeo-drive hidden folder where logs are stored
  • The Nuxeo Drive client application
  • The Nuxeo Drive local folder, only if you want to get rid of all the synchronized files and folders.

Uninstalling Nuxeo Drive on macOS

To uninstall Nuxeo Drive:

  1. Quit Nuxeo Drive:
    1. Click on the icon in the system tray.
    2. Click on Quit in the menu.
  2. Open a terminal and execute the following command:

    rm -rf ~/.nuxeo-drive
    
  3. Remove Nuxeo Drive from your applications like you usually remove any application.

  4. Delete the Nuxeo Drive item from your Favorites in the Finder.

At this point you have uninstalled the Nuxeo Drive program and its configuration. If you want to get rid of the synchronized data you also need to delete the Nuxeo Drive folder like you delete any regular folder.

Uninstalling Nuxeo Drive on Windows

To uninstall Nuxeo Drive:

  1. Quit Nuxeo Drive:

    1. Click on the icon in the system tray.
    2. Click on Quit in the menu.

    At this point you can check that there are no ndrivew.exe remaining processes in the Processes tab of the Windows Task Manager that you can open by typing Ctrl + Shift + Esc. If you find such processes, kill them manually by right-clicking on their name and clicking on End Process.

  2. Uninstall the Nuxeo Drive application like a regular program using the Control Panel.

    If you have any problem during the uninstallation process you can try using this Microsoft tool to uninstall Nuxeo Drive properly.

  3. Waiting for NXDRIVE-476 to be resolved you also need to manually delete the empty C:\Program Files (x86)\Nuxeo directory.

At this point you have uninstalled the Nuxeo Drive program and its configuration. If you want to get rid of the synchronized data you also need to delete the Nuxeo Drive folder like you delete any regular Windows folder.

Uninstalling Nuxeo Drive on GNU/Linux

To uninstall Nuxeo Drive:

  1. Quit Nuxeo Drive:
    • Click on the icon in the system tray.
    • Click on Quit in the menu.
  2. Open a terminal and execute the following command:

    rm -rf ~/.nuxeo-drive
    
  3. Uninstall the Nuxeo Drive application using the following command:

    sudo pip uninstall nuxeo-drive
    

    At this point you have uninstalled the Nuxeo Drive program and its configuration. If you want to get rid of the synchronized data you also need to delete the Nuxeo Drive folder like you delete any regular Linux folder.