Merge pull request #5252 from platformsh/5251-comp-img-links

catplat · web-flow · commit 0f44e58f7190 · 2025-12-09T11:23:59.000-05:00
Single/Composable image restructure: Fix remaining broken links
diff --git a/sites/platform/src/create-apps/app-reference/_index.md b/sites/platform/src/create-apps/app-reference/_index.md
@@ -38,7 +38,7 @@ Manually defining a stack in a composable image is typically simpler than adding
 
 Consider using a composable image when these factors are important:
 - Your application requires multiple runtimes and tools, or different versions of the same package.
-- You build your own services. See the [Building your own services](#building-services) section below.
+- You build your own services. 
 - You want the ability to install _all_ the packages you need in your application container, ensuring that an application works on any machine.<BR> 
     In a composable image, you can accomplish this by using supported Nix channels. This method ensures app consistency and helps to streamline the development, testing, and deployment processes.
     
@@ -62,11 +62,11 @@ Consider using a composable image when these factors are important:
 
 ## Keys used in each image type
 
-Only the single-runtime image supports the [``build``](/create-apps/app-reference/single-runtime-image.md#build), [``dependencies``](/create-apps/app-reference/single-runtime-image.md#dependencies), and [``runtime``](/create-apps/app-reference/single-runtime-image.md#druntime) keys. In a composable image, the equivalent is the [`stack`](/create-apps/app-reference/composable-image.md#stack) key. 
+Only the single-runtime image supports the [``build``](/create-apps/app-reference/single-runtime-image.md#build), [``dependencies``](/create-apps/app-reference/single-runtime-image.md#dependencies), and [``runtime``](/create-apps/app-reference/single-runtime-image.md#runtime) keys. In a composable image, the equivalent is the [`stack`](/create-apps/app-reference/composable-image.md#stack) key. 
 
 Otherwise, the same keys are available for both image types. Differences in syntax or meaning are noted in each key's topic - see the [Image properties](/create-apps/image-properties.md) section for the topics that describe each key.  
 
 ## Multi-app projects
-In a multiple application context, you can use a mix of single-runtime images and composable images. See the examples in the [single-runtime image](/create-apps/app-reference/single-runtime-image.md#combine-single-runtime-and-composable-images) topic and [composable](/create-apps/app-reference/composable-image.md#combine-single-runtime-and-composable-images) image topic.
+In a multiple application context, you can use a mix of single-runtime images and composable images. See the examples in the [single-runtime image](/create-apps/app-reference/single-runtime-image.md#combine-single-runtime-and-composable-images) topic and [composable image](/create-apps/app-reference/composable-image.md#combine-single-runtime-and-composable-images) topic.
 
 
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
@@ -212,3 +212,36 @@ The following table shows the properties that can be set in `sizing_hints`:
 | `reserved_memory` | `integer` | 70      | 70      | The amount of memory reserved in MB.           |
 
 See more about [PHP-FPM workers and sizing](/languages/php/fpm.md).
+
+## Combine single-runtime and composable images {#combine-single-runtime-and-composable-images}
+
+In a [multiple application context](/create-apps/multi-app/_index.md),
+you can use a mix of single-runtime images and [composable images](/create-apps/app-reference/composable-image.md).
+
+
+The following sample configuration includes two applications:
+- ``frontend`` – uses a single-runtime image
+- ``backend`` – uses a composable image<br>
+  In this app, PHP is the primary runtime and is started automatically (PHP-FPM also starts automatically when PHP is the primary runtime). For details, see the [PHP as a primary runtime](/create-apps/app-reference/composable-image.md#php-as-a-primary-runtime) section in the Composable image topic.
+
+
+```yaml {configFile="app"}
+applications:
+  frontend:
+    # this app uses the single-runtime image with a specific node.js runtime
+    type: 'nodejs:{{% latest "nodejs" %}}'
+  backend:
+    # this app uses the composable image and specifies two runtimes
+    type: "composable:8.4"
+    stack:
+      runtimes:
+        - "php@8.4":
+            extensions:
+              - apcu
+              - sodium
+              - xsl
+              - pdo_sqlite
+        - "python@3.13"
+      packages:
+        - "python313Packages.yq" # python package specific
+```
diff --git a/sites/platform/src/create-apps/image-properties/crons.md b/sites/platform/src/create-apps/image-properties/crons.md
@@ -86,7 +86,7 @@ applications:
 
 {{< /codetabs >}}
 
-In this example configuration, the crons [`spec`](#crons) uses the `H` syntax.
+In this example configuration, the crons `spec` key uses the `H` syntax.
 
 Note that this syntax is only supported on Grid projects.
 On {{% names/dedicated-gen-2 %}} projects, use the [standard cron syntax](https://en.wikipedia.org/wiki/Cron#Cron_expression).
diff --git a/sites/platform/src/create-apps/image-properties/disk.md b/sites/platform/src/create-apps/image-properties/disk.md
@@ -10,7 +10,7 @@ Optional in [single-runtime](/create-apps/app-reference/single-runtime-image.md#
 
 The maximum total space available to all apps and services is set by the storage in your plan settings.
 When deploying your project, the sum of all `disk` keys defined in app and service configurations
-must be *equal or less* than the plan storage size.
+cannot exceed the available storage in your plan.
 
 So if your *plan storage size* is 5&nbsp;GB, you can, for example, assign it in one of the following ways:
 
@@ -23,7 +23,10 @@ You need to either increase your plan's storage or decrease the `disk` values yo
 
 You configure the disk size in [MB](/glossary/_index.md#mb). Your actual available disk space is slightly smaller with some space used for formatting and the filesystem journal. When checking available space, note whether it’s reported in MB or MiB.
 
-### Altering `disk` values
+If you need more storage to fit the sum of all `disk` keys, it is necessary to [switch plans](/administration/pricing.md#switch-plans). This can only be done by people with the [manage plans permission](/administration/users.md#organization-permissions).
+
+
+### Backups and altering `disk` values
 
 It's a best practice to [back up your environment](/environments/backup.md) **before and after** you increase **or** decrease the `disk` value (the amount of allocated storage space) of an app or service.
 
diff --git a/sites/platform/src/create-apps/image-properties/workers.md b/sites/platform/src/create-apps/image-properties/workers.md
@@ -57,7 +57,7 @@ title=Composable image
 
 The keys of the `workers` definition are the names of the workers.
 You can then define how each worker differs from the `web` instance using
-the [top-level properties](#primary-application-properties).
+the [top-level properties](/create-apps/app-reference/composable-image.md#top-level-properties).
 
 Each worker can differ from the `web` instance in all properties _except_ for:
 
diff --git a/sites/platform/src/create-apps/troubleshoot-disks.md b/sites/platform/src/create-apps/troubleshoot-disks.md
@@ -23,7 +23,7 @@ Error: Resources exceeding plan limit; disk: 8192.00MB > 5120.00MB; try removing
 To fix the error, do one of the following:
 
 * Lower the `disk` parameters to a value within your plan's storage limits.
-  Note the [limits to downsizing disks](/create-apps/app-reference/single-runtime-image.md#downsize-a-disk).
+  Note the [limits to downsizing disks](/create-apps/image-properties/disk.md).
 * Increase your plan's storage limits.
   This can only be done by people with the [manage plans permission](/administration/users.md#organization-permissions).
 
diff --git a/sites/platform/src/create-apps/troubleshoot-mounts.md b/sites/platform/src/create-apps/troubleshoot-mounts.md
@@ -42,7 +42,7 @@ You can then put the mount back in place.
 ## Mounted files not publicly accessible
 
 If you've set up mounts to handle files like user uploads, you want to make sure the files are accessible.
-Do so by managing their [location](/create-apps/app-reference/single-runtime-image.md#locations).
+Do so by managing their [location](/create-apps/image-properties/web.md#locations).
 
 This example defines two mounts, one named `private` and one `upload`:
 
diff --git a/sites/platform/src/create-apps/web/static.md b/sites/platform/src/create-apps/web/static.md
@@ -41,7 +41,7 @@ web:
 See more information on the required minimal settings:
 - [Top-level properties](/create-apps/app-reference/single-runtime-image.md#top-level-properties).
 - [`web` property](/create-apps/image-properties/web.md).
-- [`locations` properties](/create-apps/app-reference/single-runtime-image.md#locations).
+- [`locations` properties](/create-apps/image-properties/web.md#locations).
 
 ## Add more features
 
@@ -62,7 +62,7 @@ web:
       allow: true
 ```
 
-See more information on [`locations` properties](/create-apps/app-reference/single-runtime-image.md#locations).
+See more information on [`locations` properties](/create-apps/image-properties/web.md#locations).
 
 ### Create cache rules
 
diff --git a/sites/platform/src/dedicated-environments/dedicated-gen-2/environment-differences.md b/sites/platform/src/dedicated-environments/dedicated-gen-2/environment-differences.md
@@ -103,7 +103,7 @@ The following settings require a [support ticket](/learn/overview/get-support.md
 * Increasing storage
 * Allocating storage among mounts and services
 * [PHP extensions](/languages/php/extensions.md)
-* Web server configuration (the [`web.locations` section of your app configuration](/create-apps/app-reference/single-runtime-image.md#locations))
+* Web server configuration (the [`web.locations` section of your app configuration](/create-apps/image-properties/web.md#locations))
 
 ## Logs
 
diff --git a/sites/platform/src/define-routes/_index.md b/sites/platform/src/define-routes/_index.md
@@ -485,7 +485,7 @@ which is a requirement for the router caching.
     enabled: false
 ```
 
-2. [Disable request buffering](/create-apps/app-reference/single-runtime-image.md#locations) in your app configuration.
+2. [Disable request buffering](/create-apps/image-properties/web.md#locations) in your app configuration.
 
 ```yaml {configFile="app"}
 web:
diff --git a/sites/platform/src/development/troubleshoot.md b/sites/platform/src/development/troubleshoot.md
@@ -311,7 +311,7 @@ and [cookie entry](/define-routes/cache.md#cookies).
 Because the router cache follows cache headers from your app,
 your app needs to send the correct `cache-control` header.
 
-For static assets, set cache headers using the `expires` key in your [app configuration](/create-apps/app-reference/single-runtime-image.md#locations).
+For static assets, set cache headers using the `expires` key in your [app configuration](/create-apps/image-properties/web.md#locations).
 
 ## Language-specific troubleshooting
 
diff --git a/sites/platform/src/environments/search-engine-visibility.md b/sites/platform/src/environments/search-engine-visibility.md
@@ -58,7 +58,7 @@ It's automatically on for all `{{% vendor/cli %}}.site` domains, and it's automa
 
 You can also send instructions to search engine indexers using a `robots.txt` file.
 Your app can serve this as a static file from its disk or as a dynamic response from its `passthru`.
-Control either with the [`location` section of your app configuration](/create-apps/app-reference/single-runtime-image.md#locations).
+Control either with the [`location` section of your app configuration](/create-apps/image-properties/web.md#locations).
 
 If your `robots.txt` file includes instructions to ignore a page,
 search engine indexers may ignore it even if you have configured {{% vendor/name %}} to not send the header.
diff --git a/sites/platform/src/guides/drupal/faq.md b/sites/platform/src/guides/drupal/faq.md
@@ -41,4 +41,4 @@ For Drupal sites, the name of the session cookie is based on a hash of the domai
 If you see a bare "File not found" error when accessing your Drupal site with a browser,
 you've pushed your code as a vanilla project but no `index.php` has been found.
 
-Make sure your repository contains an `index.php` file in the [web location root](/create-apps/app-reference/single-runtime-image.md#locations).
+Make sure your repository contains an `index.php` file in the [web location root](/create-apps/image-properties/web.md#locations).
diff --git a/sites/platform/src/languages/php/_index.md b/sites/platform/src/languages/php/_index.md
@@ -78,7 +78,7 @@ type: 'php:{{% latest "php" %}}'
 ```
 ### 2. Serve your app
 
-To serve your app, define what (and how) content should be served by setting the [`locations` parameter](/create-apps/app-reference/single-runtime-image.md#locations).
+To serve your app, define what (and how) content should be served by setting the [`locations` parameter](/create-apps/image-properties/web.md#locations).
 
 Usually, it contains the two following (optional) keys:
 
@@ -663,9 +663,22 @@ See the example below for more details.
 | `extensions`                | List of `string`s OR [extensions definitions](/create-apps/app-reference/composable-image.md#stack) | [PHP extensions](/languages/php/extensions.md) to enable.                                               |
 | `disabled_extensions`       | List of `string`s                                                                                                                | [PHP extensions](/languages/php/extensions.md) to disable.                                              |
 | `request_terminate_timeout` | `integer`                                                                                                                        | The timeout (in seconds) for serving a single request after which the PHP-FPM worker process is killed. |
-| `sizing_hints`              | A [sizing hints definition](/create-apps/app-reference/composable-image.md#sizing-hints)                                         | The assumptions for setting the number of workers in your PHP-FPM runtime.                              |
+| `sizing_hints`              | A [sizing hints definition](#sizing-hints)                                         | The assumptions for setting the number of workers in your PHP-FPM runtime.                              |
 | `xdebug`                    | An Xdebug definition                                                                                                             | The setting to turn on [Xdebug](/languages/php/xdebug.md).                                              |
 
+### PHP-FPM service sizing hints {#sizing-hints}
+
+The following table shows the properties that can be set in `sizing_hints`:
+
+| Name              | Type      | Default | Minimum | Description                                    |
+|-------------------|-----------|---------|---------|------------------------------------------------|
+| `request_memory`  | `integer` | 45      | 10      | The average memory consumed per request in MB. |
+| `reserved_memory` | `integer` | 70      | 70      | The amount of memory reserved in MB.           |
+
+See more about [PHP-FPM workers and sizing](/languages/php/fpm.md).
+
+### Example PHP configuration {#example-php-configuration}
+
 Here is an example configuration:
 
 ```yaml {configFile="app"}
diff --git a/sites/platform/src/security/web-application-firewall/waf.md b/sites/platform/src/security/web-application-firewall/waf.md
@@ -95,15 +95,15 @@ The WAF enforces a file upload limit.
 By default, this limit is set at 250&nbsp;MB.
 
 You can customize the file upload limit by amending your [app configuration](/create-apps/_index.md).
-In the [`web.locations` dictionary](/create-apps/app-reference/single-runtime-image.md#locations),
+In the [`web.locations` dictionary](/create-apps/image-properties/web.md#locations),
 add your desired value for the `max_request_size` property.
 
 ### File extension restriction
 
 The WAF enforces any file extension restriction you may have defined in your [app configuration](/create-apps/_index.md).
 
 To set up a file extension restriction,
-adjust the [`web.locations` dictionary](/create-apps/app-reference/single-runtime-image.md#locations).
+adjust the [`web.locations` dictionary](/create-apps/image-properties/web.md#locations).
 Set up [rules](/create-apps/image-properties/web.md#rules) to allow only certain file extensions on a given path.
 
 ### Disallowed requests and headers
diff --git a/sites/upsun/src/create-apps/app-reference/_index.md b/sites/upsun/src/create-apps/app-reference/_index.md
@@ -65,7 +65,7 @@ Only the single-runtime image supports the [``build``](/create-apps/app-referenc
 Otherwise, the same keys are available for both image types. Differences in syntax or meaning are noted in each key's topic - see the [Image properties](/create-apps/image-properties.md) section for the topics that describe each key.
 
 ## Multi-app projects
-In a multiple application context, you can use a mix of single-runtime images and composable images. See the examples in the [single-runtime image](/create-apps/app-reference/single-runtime-image.md#combine-single-runtime-and-composable-images) topic and [composable](/create-apps/app-reference/composable-image.md#combine-single-runtime-and-composable-images) image topic.
+In a multiple application context, you can use a mix of single-runtime images and composable images. See the examples in the [single-runtime image](/create-apps/app-reference/single-runtime-image.md#combine-single-runtime-and-composable-images) topic and [composable image](/create-apps/app-reference/composable-image.md#combine-single-runtime-and-composable-images) topic.
 
 
 
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
@@ -109,38 +109,6 @@ applications:
     type: 'php:{{% latest "php" %}}'
 ```
 
-### Combine single-runtime and composable images {#combine-single-runtime-and-composable-images}
-
-In a [multiple application context](/create-apps/multi-app/_index.md),
-you can use a mix of single-runtime images
-and [composable images](/create-apps/app-reference/composable-image.md).
-
-
-The following sample configuration includes two applications:
-- ``frontend`` – uses a single-runtime image
-- ``backend`` – uses a composable image<br>
-
-```yaml {configFile="app"}
-applications:
-  frontend:
-    # this app uses the single-runtime image with a specific node.js runtime
-    type: 'nodejs:{{% latest "nodejs" %}}'
-  backend:
-    # this app uses the composable image and specifies two runtimes
-    type: "composable:{{% latest composable %}}"
-    stack:
-      runtimes:
-        - "php@8.4":
-            extensions:
-              - apcu
-              - sodium
-              - xsl
-              - pdo_sqlite
-        - "python@3.13"
-      packages:
-        - "python313Packages.yq" # python package specific
-```
-
 ## `build` {#build}
 
 The only property of the `build` dictionary is `flavor`, which specifies a default set of build tasks to run.
@@ -292,3 +260,36 @@ Related topics:
 You can reduce the target disk size of an app. Keep in mind:
 - Backups created before the downsize are incompatible and cannot be used; you must [create new backups](/environments/backup.md).
 - The downsize will fail if the disk contains more data than the target size.
+
+### Combine single-runtime and composable images {#combine-single-runtime-and-composable-images}
+
+In a [multiple application context](/create-apps/multi-app/_index.md),
+you can use a mix of single-runtime images
+and [composable images](/create-apps/app-reference/composable-image.md).
+
+
+The following sample configuration includes two applications:
+- ``frontend`` – uses a single-runtime image
+- ``backend`` – uses a composable image<br>
+  In this app, PHP is the primary runtime and is started automatically (PHP-FPM also starts automatically when PHP is the primary runtime). For details, see the [PHP as a primary runtime](/create-apps/app-reference/composable-image.md#php-as-a-primary-runtime) section in the Composable image topic.
+
+```yaml {configFile="app"}
+applications:
+  frontend:
+    # this app uses the single-runtime image with a specific node.js runtime
+    type: 'nodejs:{{% latest "nodejs" %}}'
+  backend:
+    # this app uses the composable image and specifies two runtimes
+    type: "composable:{{% latest composable %}}"
+    stack:
+      runtimes:
+        - "php@8.4":
+            extensions:
+              - apcu
+              - sodium
+              - xsl
+              - pdo_sqlite
+        - "python@3.13"
+      packages:
+        - "python313Packages.yq" # python package specific
+```
diff --git a/sites/upsun/src/create-apps/image-properties/crons.md b/sites/upsun/src/create-apps/image-properties/crons.md
@@ -78,8 +78,7 @@ applications:
 
 {{< /codetabs >}}
 
-
-In this example configuration, the [cron specification](https://en.wikipedia.org/wiki/Cron#Cron_expression) uses the `H` syntax.
+In this example configuration, the crons `spec` key uses the `H` syntax.
 
 ### Single-runtime image: Example cron jobs
 
diff --git a/sites/upsun/src/create-apps/image-properties/web.md b/sites/upsun/src/create-apps/image-properties/web.md
@@ -110,7 +110,7 @@ applications:
 {{< /codetabs >}}
 
 
-### Upstream
+### `upstream` {#upstream}
 
 {{< codetabs >}}
 
@@ -186,7 +186,7 @@ Where to listen depends on your setting for `web.upstream.socket_family` (defaul
 If your application isn't listening at the same place that the runtime is sending requests,
 you see `502 Bad Gateway` errors when you try to connect to your website.
 
-### Locations
+### `locations` {#locations}
 
 Each key in the `locations` dictionary is a path on your site with a leading `/`.
 For `example.com`, a `/` matches `example.com/` and `/admin` matches `example.com/admin`.
diff --git a/sites/upsun/src/create-apps/image-properties/workers.md b/sites/upsun/src/create-apps/image-properties/workers.md
