# `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](https://fixed.docs.upsun.com/create-apps/app-reference/single-runtime-image.md#top-level-properties) and [composable](https://fixed.docs.upsun.com/create-apps/app-reference/composable-image.md#top-level-properties) 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.

**Note**: 

 - Mounts aren’t available during the build
 - When you [back up an environment](https://fixed.docs.upsun.com/environments/backup.md), the mounts on that environment are backed up too

### Define a mount

To define a mount, use the following configuration:

```yaml  {location=".platform.app.yaml"}
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](https://fixed.docs.upsun.com/create-apps/troubleshoot-mounts.md#overlapping-folders).

| Name          | Type                          | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------- |-------------------------------| -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `source`      | `local`, `service`, or `tmp`  | Yes      | Specifies the type of the mount: - `local` mounts are unique to your app. They can be useful to store files that remain local to the app instance, such as application logs.  `local` mounts require disk space. To successfully set up a local mount, set the `disk` key in your app configuration. - `service` mounts point to [Network Storage](https://fixed.docs.upsun.com/add-services/network-storage.md) services that can be shared between several apps. - `tmp` mounts are local ephemeral mounts, where an external directory is mounted to the `/tmp` directory of your app.  The content of a `tmp` mount **may be removed during infrastructure maintenance operations**. Therefore, `tmp` mounts allow you to **store files that you’re not afraid to lose**, such as your application cache that can be seamlessly rebuilt.  Note that the `/tmp` directory has **a maximum allocation of 8 GB**. |
| `source_path` | `string`                      | No    | Specifies where the mount points **inside the external directory**. - If you explicitly set a `source_path`, your mount points to a specific subdirectory in the external directory.   - If the `source_path` is an empty string (`""`), your mount points to the entire external directory. - If you don't define a `source_path`, Upsun Fixed uses the <MOUNT_PATH> as default value, without leading or trailing slashes. For example, if your mount lives in the `/web/uploads/` directory in your app container, it will point to a directory named `web/uploads` in the external directory.     **WARNING:** Changing the name of your mount affects the `source_path` when it's undefined. See [how to ensure continuity](#change-name) and maintain access to your files.                       |
| `service`     | `string`                      |       | Only for `service` mounts: the name of the [Network Storage service](https://fixed.docs.upsun.com/add-services/network-storage.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

The accessibility to the web of a mounted directory depends on the [`web.locations` configuration](https://fixed.docs.upsun.com/create-apps/image-properties/web.md).
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

```yaml  {location=".platform.app.yaml"}
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](https://fixed.docs.upsun.com/add-services/network-storage.md).

### Ensure continuity when changing the name of your mount {#change-name}

Changing the name of your mount affects the default `source_path`.

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

```yaml  {location=".platform.app.yaml"}
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:

 ```yaml  {location=".platform.app.yaml"}
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:

```yaml  {location=".platform/applications.yaml"}
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:

```yaml  {location=".platform/applications.yaml"}
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.


