Add Assets

In Cascade, an Asset is defined as any object or directory your application needs or delivers that is not a part of your code repository and does not reside in a database but needs to reside logically somewhere in the codebase or web root for the application to work correctly.

The Assets are part of the project and may be moved around the hosted environments with a click of a button. The Assets in a project are made “live” in each environment by placing a symbolic link to them in the target environment.

Example uses of the Assets feature:

  • The wp-uploads directory in a Wordpress system
  • The sites/default/files directory in a Drupal system
  • Vendor directory for Composer libraries not stored in Git


You will need to log into Cascade as a Project Administrator to configure Assets. To check your permissions, please navigate to the overview page of the project you wish to modify. If your display does not include the Assets icon ( Open the Assets settings ) in the left toolbar, your account does not have sufficient privileges to proceed. If you click the Assets icon, you should see the Assets configuration page.

Show the Assets settings for the project

In addition to the correct permissions in Cascade, in order to transfer pre-existing assets to your hosting system, additional access to the file systems is required. This tooling and access layer is managed by Contegix. If you have questions or need access please contact your project technical lead or Contegix support to request access to upload files.

Enable Assets

Please navigate to the overview page of the project you wish to modify and click the Assets icon ( Open the Assets settings ) in the left toolbar. If assets are not currently enabled you will see a page like below.

The Assets feature is disabled

  1. Uncheck the checkbox titled “This project does not use assets” to enable assets.
  2. Click the Save button in the banner that appears in the navigation area.

Add Additional Assets

Please navigate to the overview page of the project you wish to modify and click the Assets icon ( Open the Assets settings ) in the left toolbar.

Take note of any instruction provided at the top of the page and keep in mind that Assets are managed in groups because each Cascade project is connected to multiple environments, each one with their own copy of the Assets to use.

Note: You can add as many asset groups as your application needs by repeating the instructions below. To access these additional assets there is a pager provided to the right of the add button or on the margin of each asset group.

Step 1: Enter a name

  1. Click the + to open the add asset group form.
  2. Fill in the Asset Group name field.

Step 2: Adjust assets per environment

For each environment in the asset group, do the following:

  1. Adjust the Asset Path to be the relative path within the project webroot where the project expects the asset to served from. Take note of the following conditions expected on successful deployment of the asset:
    1. The resulting symbolic link will point to the Asset Storage Mount configured for that environment.
    2. The last component of this path will be the name of the symbolic link.
    3. The remainder of the path will decide what directory the link will be placed in.
  2. Adjust the Asset Storage Mount to be the absolute path outside the project webroot where the actual files are stored.
    • Take note of these paths, as, you will be required to migrate your project assets into this path for the first environment in your workflow.
  3. A banner with a save button will appear at the top of the page when changes are detected.
  4. Click the save button in the banner to submit the form.

An example of assets configured for Drupal public and private uploads

Step 3: Initialize assets

The final step is to initialize the assets.

  1. Navigate to the project overview dashboard.
  2. For each environment listed, find the “Initialize” button for each asset and click it to create an empty asset at the path specified by the value of Asset Storage Mount.
  3. Since all your assets should be empty at this phase, you can choose any environment for the FROM value. Be sure the to value is the environment you clicked.

Step 4: Migrate Assets (optional)

For projects just staring out and/or having their own system for managing assets, this step may be unnecessary. For pre-existing project or continuing efforts, data migration will be necessary to seed the hosting environments initially.

As mentioned previously in this guide, uploading the project assets to your hosting system is handled through conventional means, and access to those endpoints is handled by Contegix support. We have support for SFTP, Rsync, and other common tools. Please refer to the documentation provided to you and reach out to support if you have any questions.