mounts

Defines the directories that are writable even after the app is built.

If set as a local source, disk is required.

Optional in single-runtime and composable images.

After your app is built, its file system is read-only. To make changes to your app’s code, you need to use Git.

For enhanced flexibility, Upsun Fixed allows you to define and use writable directories called “mounts”. Mounts give you write access to files generated by your app (such as cache and log files) and uploaded files without going through Git.

When you define a mount, you are mounting an external directory to your app container, much like you would plug a hard drive into your computer to transfer data.

Define a mount

To define a mount, use the following configuration:

mounts:
  'MOUNT_PATH':
    source: MOUNT_TYPE
    source_path: SOURCE_PATH_LOCATION

MOUNT_PATH is the path to your mount within the app container (relative to the app’s root). If you already have a directory with that name, you get a warning that it isn’t accessible after the build. See how to troubleshoot the warning.

The accessibility to the web of a mounted directory depends on the web.locations configuration. Files can be all public, all private, or with different rules for different paths and file types.

Note that when you remove a local mount from your .platform.app.yaml file, the mounted directory isn’t deleted. The files still exist on disk until manually removed (or until the app container is moved to another host during a maintenance operation in the case of a tmp mount).

Example configuration

mounts:
  'web/uploads':
    source: local
    source_path: uploads
  '/.tmp_platformsh':
    source: tmp
    source_path: files/.tmp_platformsh
  '/build':
    source: local
    source_path: files/build
  '/.cache':
    source: tmp
    source_path: files/.cache
  '/node_modules/.cache':
    source: tmp
    source_path: files/node_modules/.cache

For examples of how to set up a service mount, see the dedicated Network Storage page.

Ensure continuity when changing the name of your mount

Changing the name of your mount affects the default source_path.

Say you have a /my/cache/ mount with an undefined source_path:

mounts:
  '/my/cache/':
    source: tmp

If you rename the mount to /cache/files/, it will point to a new, empty /cache/files/ directory.

To ensure continuity, you need to explicitly define the source_path as the previous name of the mount, without leading or trailing slashes:

mounts:
 '/cache/files/':
   source: tmp
   source_path: my/cache

The /cache/files/ mount will point to the original /my/cache/ directory, maintaining access to all your existing files in that directory.

Overlapping mounts

The locations of mounts as they are visible to application containers can overlap somewhat. For example:

applications:
  myapp:
    # ...
    mounts:
      'var/cache_a':
        source: service
        service: ns_service
        source_path: cacheA
      'var/cache_b':
        source: tmp
        source_path: cacheB
      'var/cache_c':
        source: local
        source_path: cacheC

In this case, it does not matter that each mount is of a different source type. Each mount is restricted to a subfolder within var, and all is well.

The following, however, is not allowed and will result in a failure:

applications:
  myapp:
    # ...
    mounts:
      'var/':
        source: service
        service: ns_service
        source_path: cacheA
      'var/cache_b':
        source: tmp
        source_path: cacheB
      'var/cache_c':
        source: local
        source_path: cacheC

The service mount type specifically exists to share data between instances of the same application, whereas tmp and instance are meant to restrict data to build time and runtime of a single application instance, respectively. These allowances are not compatible, and will result in an error if pushed.