How do I convert my project from a single root to a multi-root configuration?

Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations Admin Guide or contact support if you do not have a more advanced configuration.

Your project uses a single local storage root (eg. all of your project files are stored underneath a single root point like /sgtk/projects). You now want to add a new storage root to store some of your project files. This is a common situation that arises when you're running out of disk space or want some media to be on a faster storage, etc. Toolkit currently requires that you have at least one local storage named "primary" so if you're using a single root, then that's what you have. Now lets say we want to add another one named "secondary".

Add the local storage in Shotgun

  • In Shotgun, navigate to the Admin > Site Preferences page
  • Open up the File Management section
  • Click on [+] Add Local File Storage
  • Fill out the name ("secondary") and the paths to the storage root on all of the relevant platforms. If you're not using a particular platform, you can simply leave it blank.
  • Click on the Save Page button on the top or the bottom of the page

 file_management.png

Add the new root to your pipeline configuration

Toolkit caches information about the local storages used in a pipeline configuration in the config/core/roots.yml file. Edit this file to add the new secondary storage root you just created in Shotgun:

primary: {linux_path: /mnt/hgfs/sgtk/projects, mac_path: /sgtk/projects, windows_path: 'z:\sgtk\projects'}
secondary: {linux_path: /mnt/hgfs/sgtk/secondaries, mac_path: /sgtk/secondaries, windows_path: 'z:\sgtk\secondaries'}

Modify your schema to use your new local storage root

Now that you've defined the new storage root and essentially told Toolkit about it, you need to decide how you're going to use it in your directory structure. For this example, let's assume I want all of my asset work to go in the secondary storage, and all of my shot work to go in the primary storage. I might setup my schema to look like the following in config/core/schema:

 

schema_multi__Shared_.png

At the top level of your schema, you'll have a .yml file to configure the root of each storage. 

config/core/schema/project.yml

# the type of dynamic content
type: "project"

# name of project root as defined in roots.yml
root_name: "primary"

config/core/schema/secondary.yml

# the type of dynamic content
type: "project"

# name of project root as defined in roots.yml
root_name: "secondary"

  

Update your template paths to specify which root to use

Finally you will update1 the paths defined in your config/core/templates.yml file to specify which storage root to use, and update any of the paths as necessary. Remember that your template paths are very good friends with your schema and they need to match up. If you have a template path defined that doesn't match correctly with the path defined in your schema, you'll run into errors.

For example, since we want to have all of our asset work on the secondary storage, to update the maya_asset_work template path, we'd modify it to look like this:

maya_asset_work:
definition: '@asset_root/work/maya/{name}.v{version}.ma'
root_name: 'secondary'

You should follow this same pattern for each template path in your config/core/templates.yml file. Specify the correct root_name for each one ('primary' or 'secondary').

It is worth noting that updating the paths might not be ideal, since any old files that were created using the previous value will not be accessible by Toolkit once the new value is set (e.g. old work files won't be found by Toolkit after changing their template path). If this is a concern, you may then create a new template (e.g. houdini_shot_publish_v2) with the new location and upgrade your apps to use that new version. Not all apps handle a fallback concept like this, but this will allow some apps to recognize the old files. This does not affect publishes, as these are always linked to their publish in Shotgun.

 

 

Follow

1 Comments

  • 1
    Avatar
    Krzysztof Klimczyk

    Thanks for the article, very useful!

    It is worth mentioning that inside your secondary schema you need to replace occurrences of $project with $yourSecondaryName in your .yml files (if you happened to copy over the schema).

    Edited by Krzysztof Klimczyk
Please sign in to leave a comment.