diff --git a/sites/platform/src/create-apps/app-reference/composable-image.md b/sites/platform/src/create-apps/app-reference/composable-image.md index c3d555435d..b94beed02a 100644 --- a/sites/platform/src/create-apps/app-reference/composable-image.md +++ b/sites/platform/src/create-apps/app-reference/composable-image.md @@ -598,6 +598,60 @@ much like you would plug a hard drive into your computer to transfer data. {{% /note %}} +### Mount types + +Each mount type has a specific use case and understanding how to use each type effectively will help optimize your application. + +#### `storage` mount + +The `storage` mount is a shared network storage that is automatically added by the platform. It is required for applications that need to share files across multiple instances—such as user-uploaded media or shared assets. You can configure the size of this mount via the {{% vendor/name %}} UI. + +Pros: +- Shared across all app instances. +- Configurable size via the UI. +- Persistent across restarts and redeployments. + +Cons: +- Not suitable for high-throughput temporary operations. + +#### `tmp` mount + +The `tmp` mount uses the ephemeral disk of an instance and is intended for non-persistent, high-speed temporary storage. Data here may be lost during redeployments or infrastructure updates. Like `instance`, it is limited to 8GB and not configurable. + +Pros: +- Fastest available storage—ideal for caches or intermediate data. +- Great for temporary files that can be regenerated. + +Cons: +- Non-persistent data can be cleared at any time. +- Not shared across instances or with workers. +- Fixed size (8GB). + +#### `service` mount + +A `service` mount allows you to explicitly define and use a Network Storage service that can be shared between different apps or workers. Unlike the default `storage` mount, which is automatically provisioned per app, a service-based mount gives you greater flexibility and control over how shared storage is configured and accessed across your project. + +This is useful when multiple apps or services need access to the same set of files or data—for example, a frontend app and a background worker both reading from a shared media directory. + +Pros: +- Enables cross-app and cross-worker shared storage. +- Centralized configuration via a defined service. +- More control over lifecycle and visibility of the storage. + +Cons: +- Requires explicit setup and service configuration. +- Slightly more complex than default `storage` mounts. + +For setup instructions and more information, see the [Network Storage service documentation](/add-services/network-storage). + +#### Scaling + +When horizontally scaling your app (multiple instances of the same app), using the appropriate mount type is critical. For shared data, a `storage` or `service` mount is recommended. For local-only data, use `tmp` mounts. + +#### Sharing mounts + +If you need to share a mount between different apps, consider using a `service` mount. This must be added explicitly and is distinct from the default `storage` mount. Mounts can be shared with workers as well, provided the configuration includes them. + ### Define a mount To define a mount, use the following configuration: diff --git a/sites/platform/src/create-apps/app-reference/single-runtime-image.md b/sites/platform/src/create-apps/app-reference/single-runtime-image.md index f478a3452c..0f8f66eb6a 100644 --- a/sites/platform/src/create-apps/app-reference/single-runtime-image.md +++ b/sites/platform/src/create-apps/app-reference/single-runtime-image.md @@ -415,6 +415,76 @@ much like you would plug a hard drive into your computer to transfer data. {{% /note %}} +### Mount types + +Each mount type has a specific use case and understanding how to use each type effectively will help optimize your application. + +#### `storage` mount + +The `storage` mount is a shared network storage that is automatically added by the platform. It is required for applications that need to share files across multiple instances—such as user-uploaded media or shared assets. You can configure the size of this mount via the {{% vendor/name %}} UI. + +Pros: +- Shared across all app and worker instances. +- Configurable size via the UI. +- Persistent across restarts and redeployments. + +Cons: +- Lower performance due to network-based access. +- Not suitable for high-throughput temporary operations. + + +#### `instance` mount (`local`) + +The `instance` mount (also called `local`) provides dedicated local storage per instance. It's backed by a Ceph-mounted volume and is not shared across horizontally scaled instances. This is ideal for logs or intermediate files that are instance-specific. + +Pros: +- Lower latency than network storage. +- Persistent across redeployments (per instance). +- Suitable for app logs or instance-specific data. + +Cons: +- Not shared across instances. +- Fixed size (8GB). +- Unsuitable for applications that require shared state across scaled instances. + +#### `tmp` mount + +The `tmp` mount uses the ephemeral disk of an instance and is intended for non-persistent, high-speed temporary storage. Data here may be lost during redeployments or infrastructure updates. Like `instance`, it is limited to 8GB and not configurable. + +Pros: +- Fastest available storage—ideal for caches or intermediate data. +- Great for temporary files that can be regenerated. + +Cons: +- Non-persistent data can be cleared at any time. +- Not shared across instances or with workers. +- Fixed size (8GB). + +#### `service` mount + +A `service` mount allows you to explicitly define and use a Network Storage service that can be shared between different apps or workers. Unlike the default `storage` mount, which is automatically provisioned per app, a service-based mount gives you greater flexibility and control over how shared storage is configured and accessed across your project. + +This is useful when multiple apps or services need access to the same set of files or data—for example, a frontend app and a background worker both reading from a shared media directory. + +Pros: +- Enables cross-app and cross-worker shared storage. +- Centralized configuration via a defined service. +- More control over lifecycle and visibility of the storage. + +Cons: +- Requires explicit setup and service configuration. +- Slightly more complex than default `storage` mounts. + +For setup instructions and more information, see the [Network Storage service documentation](/add-services/network-storage). + +#### Scaling + +When horizontally scaling your app (multiple instances of the same app), using the appropriate mount type is critical. For shared data, a `storage` or `service` mount is recommended. For local-only data, use `instance` or `tmp` mounts. + +#### Sharing mounts + +If you need to share a mount between different apps, consider using a `service` mount. This must be added explicitly and is distinct from the default `storage` mount. Mounts can be shared with workers as well, provided the configuration includes them. + ### Define a mount To define a mount, use the following configuration: diff --git a/sites/upsun/src/create-apps/app-reference/composable-image.md b/sites/upsun/src/create-apps/app-reference/composable-image.md index 57e0606b01..f183bcb7cd 100644 --- a/sites/upsun/src/create-apps/app-reference/composable-image.md +++ b/sites/upsun/src/create-apps/app-reference/composable-image.md @@ -554,6 +554,60 @@ much like you would plug a hard drive into your computer to transfer data. {{% /note %}} +### Mount types + +Each mount type has a specific use case and understanding how to use each type effectively will help optimize your application. + +#### `storage` mount + +The `storage` mount is a shared network storage that is automatically added by the platform. It is required for applications that need to share files across multiple instances—such as user-uploaded media or shared assets. You can configure the size of this mount via the {{% vendor/name %}} UI. + +Pros: +- Shared across all app instances. +- Configurable size via the UI. +- Persistent across restarts and redeployments. + +Cons: +- Not suitable for high-throughput temporary operations. + +#### `tmp` mount + +The `tmp` mount uses the ephemeral disk of an instance and is intended for non-persistent, high-speed temporary storage. Data here may be lost during redeployments or infrastructure updates. Like `instance`, it is limited to 8GB and not configurable. + +Pros: +- Fastest available storage—ideal for caches or intermediate data. +- Great for temporary files that can be regenerated. + +Cons: +- Non-persistent data can be cleared at any time. +- Not shared across instances or with workers. +- Fixed size (8GB). + +#### `service` mount + +A `service` mount allows you to explicitly define and use a Network Storage service that can be shared between different apps or workers. Unlike the default `storage` mount, which is automatically provisioned per app, a service-based mount gives you greater flexibility and control over how shared storage is configured and accessed across your project. + +This is useful when multiple apps or services need access to the same set of files or data—for example, a frontend app and a background worker both reading from a shared media directory. + +Pros: +- Enables cross-app and cross-worker shared storage. +- Centralized configuration via a defined service. +- More control over lifecycle and visibility of the storage. + +Cons: +- Requires explicit setup and service configuration. +- Slightly more complex than default `storage` mounts. + +For setup instructions and more information, see the [Network Storage service documentation](/add-services/network-storage). + +#### Scaling + +When horizontally scaling your app (multiple instances of the same app), using the appropriate mount type is critical. For shared data, a `storage` or `service` mount is recommended. For local-only data, use`tmp` mounts. + +#### Sharing mounts + +If you need to share a mount between different apps, consider using a `service` mount. This must be added explicitly and is distinct from the default `storage` mount. Mounts can be shared with workers as well, provided the configuration includes them. + ### Define a mount To define a mount, use the following configuration: diff --git a/sites/upsun/src/create-apps/app-reference/single-runtime-image.md b/sites/upsun/src/create-apps/app-reference/single-runtime-image.md index 962d0c55f1..53407dff06 100644 --- a/sites/upsun/src/create-apps/app-reference/single-runtime-image.md +++ b/sites/upsun/src/create-apps/app-reference/single-runtime-image.md @@ -134,6 +134,7 @@ Console or the `{{% vendor/cli %}} resources:set` command. For more information, see how to [manage resources](/manage-resources.md). + ## Relationships To allow containers in your project to communicate with one another, @@ -359,15 +360,13 @@ You can decrease the size of an existing disk for an app. If you do so, be aware ## Mounts -After your app is built, its file system is read-only. -To make changes to your app's code, you need to use Git. +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, {{% vendor/name %}} 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. +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 %}} @@ -376,6 +375,76 @@ much like you would plug a hard drive into your computer to transfer data. {{% /note %}} +### Mount types + +Each mount type has a specific use case and understanding how to use each type effectively will help optimize your application. + +#### `storage` mount + +The `storage` mount is a shared network storage that is automatically added by the platform. It is required for applications that need to share files across multiple instances—such as user-uploaded media or shared assets. You can configure the size of this mount via the {{% vendor/name %}} UI. + +Pros: +- Shared across all app and worker instances. +- Configurable size via the UI. +- Persistent across restarts and redeployments. + +Cons: +- Lower performance due to network-based access. +- Not suitable for high-throughput temporary operations. + + +#### `instance` mount (`local`) + +The `instance` mount (also called `local`) provides dedicated local storage per instance. It's backed by a Ceph-mounted volume and is not shared across horizontally scaled instances. This is ideal for logs or intermediate files that are instance-specific. + +Pros: +- Lower latency than network storage. +- Persistent across redeployments (per instance). +- Suitable for app logs or instance-specific data. + +Cons: +- Not shared across instances. +- Fixed size (8GB). +- Unsuitable for applications that require shared state across scaled instances. + +#### `tmp` mount + +The `tmp` mount uses the ephemeral disk of an instance and is intended for non-persistent, high-speed temporary storage. Data here may be lost during redeployments or infrastructure updates. Like `instance`, it is limited to 8GB and not configurable. + +Pros: +- Fastest available storage—ideal for caches or intermediate data. +- Great for temporary files that can be regenerated. + +Cons: +- Non-persistent data can be cleared at any time. +- Not shared across instances or with workers. +- Fixed size (8GB). + +#### `service` mount + +A `service` mount allows you to explicitly define and use a Network Storage service that can be shared between different apps or workers. Unlike the default `storage` mount, which is automatically provisioned per app, a service-based mount gives you greater flexibility and control over how shared storage is configured and accessed across your project. + +This is useful when multiple apps or services need access to the same set of files or data—for example, a frontend app and a background worker both reading from a shared media directory. + +Pros: +- Enables cross-app and cross-worker shared storage. +- Centralized configuration via a defined service. +- More control over lifecycle and visibility of the storage. + +Cons: +- Requires explicit setup and service configuration. +- Slightly more complex than default `storage` mounts. + +For setup instructions and more information, see the [Network Storage service documentation](/add-services/network-storage). + +#### Scaling + +When horizontally scaling your app (multiple instances of the same app), using the appropriate mount type is critical. For shared data, a `storage` or `service` mount is recommended. For local-only data, use `instance` or `tmp` mounts. + +#### Sharing mounts + +If you need to share a mount between different apps, consider using a `service` mount. This must be added explicitly and is distinct from the default `storage` mount. Mounts can be shared with workers as well, provided the configuration includes them. + ### Define a mount To define a mount, use the following configuration: @@ -398,7 +467,7 @@ See how to [troubleshoot the warning](../troubleshoot-mounts.md#overlapping-fold | Name | Type | Required | Description | | ------------- | -------------------- | -------- | ----------- | -| `source` | `storage`, `instance`, `tmp` (also called `temporary`), or `service` | Yes | Specifies the type of the mount:

- By design, `storage` mounts can be shared between instances of the same app. You can also configure them so they are [shared between different apps](#share-a-mount-between-several-apps).

-`instance` mounts are local mounts. Unique to your app, they are useful to store files that remain local to the app instance, such as application logs.

- `tmp` (or `temporary`) 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**.

- `service` mounts can be useful if you want to explicitly define and use a [Network Storage](/add-services/network-storage.md) service to share data between different apps (instead of using a `storage` mount).| +| `source` | `storage`, `instance`, `tmp`, or `service` | Yes | Specifies the type of the mount:

- `storage` mounts can be shared between instances of the same app. You can also configure them so they are [shared between different apps](#share-a-mount-between-several-apps).

-`instance` mounts are local mounts. **They are only available for [Single-runtime image](/create-apps/app-reference/single-runtime-image).** Unique to your app, they are useful to store files that remain local to the app instance, such as application logs.

- `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**.

- `service` mounts can be useful if you want to explicitly define and use a [Network Storage](/add-services/network-storage.md) service to share data between different apps (instead of using a `storage` mount).| | `source_path` | `string` | No | Specifies where the mount points **inside the [external directory](#mounts)**.

- 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`, {{% vendor/name %}} uses the {{< variable "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](#ensure-continuity-when-changing-the-name-of-your-mount) and maintain access to your files. | | `service` | `string` | | The purpose of the `service` key depends on your use case.

In a multi-app context where a `storage` mount is shared between apps, `service` is required. Its value is the name of the app whose mount you want to share. See how to [share a mount between several apps](#share-a-mount-between-several-apps).

In a multi-app context where a [Network Storage service](/add-services/network-storage.md) (`service` mount) is shared between apps, `service` is required and specifies the name of that Network Storage. | @@ -1336,6 +1405,7 @@ Run the following command: {{< /codetabs >}} + ## Runtime The following table presents the various possible modifications to your PHP or Lisp runtime: @@ -1403,6 +1473,7 @@ The following table shows the properties that can be set in `sizing_hints`: See more about [PHP-FPM workers and sizing](/languages/php/fpm.md). + ## Source The following table shows the properties that can be set in `source`: @@ -1445,4 +1516,4 @@ applications: web.example.com: "203.0.113.42" ``` -This is equivalent to adding the mapping to the `/etc/hosts` file for the container. +This is equivalent to adding the mapping to the `/etc/hosts` file for the container. \ No newline at end of file