This document explains the desktopserver framework. It covers how to get desktopserver integration running, certificates, security, and troubleshooting.
The desktopserver framework provides the functionality behind Shotgun's local file linking and Toolkit integration. It provides a local websocket server that securely listens for requests from Shotgun websites for an action that requires desktop access.
For local file linking, these requests allow Shotgun access to local file paths from the web interface and the ability to open those files directly from Shotgun pages when requested. For Toolkit, they allow Shotgun to determine what pipeline actions have been registered for a given entity and to execute them.
How to get desktop integration running
For these Shotgun features to work, some supported desktop integration must be running. This page covers the various options for how Shotgun can integrate with your desktop. The Websocket Server section covers the functionality that this framework provides.
There are two ways to run this server: bundled with Shotgun Desktop or standalone.
This framework is bundled with Shotgun Desktop, which can be downloaded here. When Shotgun Desktop is run it will automatically start up the websocket server. If you are already running Shotgun Desktop then your setup process is complete.
This framework is written so that the functionality it provides can be run standalone. To run the server you would clone this repository and run:
# Generates the certicicates python app/certificates.py # Runs the standalone server. python app/app.py
Note that under Linux you need to generate the certificates BEFORE launching Chrome or the browser won't be able to communicate with the local server.
Configuring the standalone server
You can store the browser integration settings in a configuration file. This configuration file can be specified using the
--configuration command line argument or by setting the environment variable
SGTK_BROWSER_INTEGRATION_CONFIG_LOCATION. More details on how you can configure the local server can be found in our sample file.
Removing a certificate
If you wish to remove a certificate you have created, you can run the
python certificates.py --remove command.
Launching via a wrapper
By default, the server will use the operating-system default to launch a command (the equivalent of "xdg-open" on Linux, "open" on OS X, and "run" on Windows). If you wish to provide your own wrapper for launching files you can set the SHOTGUN_PLUGIN_LAUNCHER environment variable to point to your custom wrapper. If that is set, the wrapper will be called with the path as its only argument.
The first time you run the server it will generate the certificate required to establish a secure connection. These certificates are stored local to your machine and are never shared with the public. They allow the encrypted connection that websockets requires, which is necessary despite all traffic remaining local (from your browser to the server); Shotgun's websocket traffic is never made available over the Internet.
When the certificates are registered with the system you will see dialogs appear like the following. Click "Ok" to allow the registration to proceed.
When using the Shotgun Desktop, the generated certificates will be stored in the following locations:
OS X: ~/Library/Caches/Shotgun/desktop/config/certificates
When using the standalone server, the generated certificates will be stored in the
resources/keys folder by default.
Security Setup - Local Shotgun Installs
By default, the websocket server is setup to listen to hosted Shotgun sites on port 9000. If you run a local Shotgun server, you will need to update the configuration for the Shotgun server to allow connections from your websocket server.
When running Shotgun Desktop, you will need to setup a
config.ini file that lives with the
Shotgun binary. There are detailed instructions for where this file needs to live
Within that file there is a section that controls the functionality of the websocket server. A typical configuration would look like this:
[BrowserIntegration] low_level_debug=0 port=9000 enabled=1 whitelist=*.shotgunstudio.com
Click here to view the complete list of options for the Desktop Server and a brief description for each option.
On Linux the server introduces a dependency on libffi. If Desktop or the standalone server crashes on startup and you see a message about libffi not found in your logs, then you need to install this package.
Email email@example.com with any issues or questions during setup. If there is a problem running the server, please set debug to 1 in the config.ini file and include Desktop's log file.
The log file can be found in the following locations:
OS X: ~/Library/Logs/Shotgun/tk-desktop.log