Composable image (#3879)

* first draft for composable image on Upsun side (only for now)

* report changes to platform folder

* some improvement on Upsun composable image

* adding multiple runtimes note + NixOs presentation draft

* adding note at the beginning of PHP doc page (draft)

* adding disclaimer on languages and align P.sh with Upsun composable

* removing  top level key from Upsun + reformat code + adding TODO block in the HTML

* Apply doc review and suggestions from Jerome

* missing replacement of built-in image

* split codetab for PHP ext and Python to separate section

* remaining built-in image

* remaining built-in image

* Move PHP-specific content and redorder side nav

* Remove extra space

* PHP extensions update

* Update PSH composable image page

* Update PSH section index page

* Reorder side nav for PSH

* Fix numbering

* Further review suggestions applied

* Fix links. Remove duplicated file on conflict resolution.

* Add redirect notes where relevant (for type and extensions).

* Add the sticky note option, even though its not yet enabled.

* Fix failing 'Check internal links' for platform docs.

* Match fixed links on upsun docs.

* Fix note.

* Fix platform config from using upsun config.

* Fix platform file name.

* socket_family/protocol for primary runtimes

* Update example configuration for PHP runtime config.

* Fix links post-merge.

* Link checks on builds.

* Fix side nav

---------

Co-authored-by: Anouck Colson <[email protected]>
Co-authored-by: chadcarlson <[email protected]>

Author: 3 people

sites/platform/src/add-services/_index.md

@@ -70,7 +70,7 @@ The following table presents the keys you can define for each service:
 | `disk`          | `integer`  | For some services | The size in [MB](/glossary.md#mb) of the [persistent disk](#disk) allocated to the service. Can't be set for memory-resident-only services such as `memcache` and `redis`. Limited by your plan settings. |
 | `size`          | `string`   |                   | How many CPU and memory [resources to allocate](#size) to the service. Possible values are `AUTO`, `S`, `M`, `L`, `XL`, `2XL`, and `4XL`. Limited by your plan settings.<BR><BR>When `AUTO` applies, available resources are automatically balanced out based on the number of containers on your plan, so that no container is oversized compared to the others. To view the actual sizes of your containers, check the **Environment Configuration** section in your deployment [activity logs](../increase-observability/logs/access-logs.md#activity-logs). |
 | `configuration` | dictionary | For some services | Some services have additional specific configuration options that can be defined here, such as specific endpoints. See the given service page for more details. |
-| `relationships` | dictionary | For some services | Some services require a relationship to your app. The content of the dictionary has the same type as the `relationships` dictionary for [app configuration](/create-apps/app-reference.md#relationships). The `endpoint_name` for apps is always `http`. |
+| `relationships` | dictionary | For some services | Some services require a relationship to your app. The content of the dictionary has the same type as the `relationships` dictionary for [app configuration](/create-apps/app-reference/single-runtime-image.md#relationships). The `endpoint_name` for apps is always `http`. |
 
 ##### Disk
 
@@ -90,7 +90,10 @@ Note that service containers in preview environments are always set to size `S`.
 
 ### 2. Connect the service
 
-To connect the service, use the following configuration:
+Once you have configured a service, you need to create a relationship to connect it to an app.
+This is done in your [app configuration for relationships](/create-apps/app-reference/single-runtime-image.md#relationships).
+
+The relationship follows this pattern:
 
 ```yaml {configFile="app"}
 # Other options...
@@ -105,12 +108,12 @@ relationships:
 You can define `<SERVICE_NAME>` as you like, so long as it's unique between all defined services 
 and matches in both the application and services configuration.
 
-The example above leverages [default endpoint](/create-apps/app-reference#relationships) configuration for relationships.
-That is, it uses default endpoints behind-the-scenes, providing a [relationship](/create-apps/app-reference#relationships)
+The example above leverages [default endpoint](/create-apps/app-reference/single-runtime-image#relationships) configuration for relationships.
+That is, it uses default endpoints behind-the-scenes, providing a [relationship](/create-apps/app-reference/single-runtime-image#relationships)
 (the network address a service is accessible from) that is identical to the _name_ of that service.
 
 Depending on your needs, instead of default endpoint configuration,
-you can use [explicit endpoint configuration](/create-apps/app-reference#relationships).
+you can use [explicit endpoint configuration](/create-apps/app-reference/single-runtime-image#relationships).
 
 An example relationship to connect to the databases given in the [example in step 1](#1-configure-the-service):
 

sites/platform/src/add-services/network-storage.md

@@ -5,7 +5,7 @@ weight: -30
 
 {{% vendor/name %}} supports internal "storage as a service" to provide a file store that can be shared between different application containers.
 
-The network storage service enables a new kind of [mount](../create-apps/app-reference.md#mounts)
+The network storage service enables a new kind of [mount](/create-apps/app-reference/single-runtime-image.md#mounts)
 that refers to a shared service rather than to a local directory.
 Your apps can use any combination of `local` and `service` mounts.
 
@@ -123,7 +123,7 @@ and the `done` mount refers to the same directory as the `web/uploads/done` dire
 
 ## Worker instances
 
-When defining a [worker](../create-apps/app-reference.md#workers) instance,
+When defining a [worker](/create-apps/app-reference/single-runtime-image.md#workers) instance,
 keep in mind what mount behavior you want.
 
 `local` mounts are a separate storage area for each instance,

sites/platform/src/add-services/redis.md

@@ -131,9 +131,9 @@ relationships:
 
 You can define `<SERVICE_NAME>` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.
 
-The example above leverages [default endpoint](/create-apps/app-reference#relationships) configuration for relationships. That is, it uses default endpoints behind-the-scenes, providing a [relationship](/create-apps/app-reference#relationships) (the network address a service is accessible from) that is identical to the name of that service.
+The example above leverages [default endpoint](/create-apps/app-reference/single-runtime-image#relationships) configuration for relationships. That is, it uses default endpoints behind-the-scenes, providing a [relationship](/create-apps/app-reference/single-runtime-image#relationships) (the network address a service is accessible from) that is identical to the name of that service.
 
-Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/create-apps/app-reference#relationships).
+Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/create-apps/app-reference/single-runtime-image#relationships).
 
 With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [`PLATFORM_RELATIONSHIPS` environment variable](/development/variables/use-variables#use-provided-variables).
 
@@ -247,9 +247,9 @@ relationships:
 
 You can define `<SERVICE_NAME>` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.
 
-The example above leverages [default endpoint](/create-apps/app-reference#relationships) configuration for relationships. That is, it uses default endpoints behind-the-scenes, providing a [relationship](/create-apps/app-reference#relationships) (the network address a service is accessible from) that is identical to the name of that service.
+The example above leverages [default endpoint](/create-apps/app-reference/single-runtime-image#relationships) configuration for relationships. That is, it uses default endpoints behind-the-scenes, providing a [relationship](/create-apps/app-reference/single-runtime-image#relationships) (the network address a service is accessible from) that is identical to the name of that service.
 
-Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/create-apps/app-reference#relationships).
+Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/create-apps/app-reference/single-runtime-image#relationships).
 
 With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [`PLATFORM_RELATIONSHIPS` environment variable](/development/variables/use-variables#use-provided-variables).
 

sites/platform/src/add-services/varnish.md

@@ -48,7 +48,7 @@ graph LR
 
 The `relationships` block defines the connection between Varnish and your app.
 You can define <code>{{< variable "RELATIONSHIP_NAME" >}}</code> as you like.
-<code>{{< variable "APP_NAME" >}}</code> should match your app's `name` in the [app configuration](../create-apps/app-reference.md).
+<code>{{< variable "APP_NAME" >}}</code> should match your app's `name` in the [app configuration](/create-apps/app-reference/single-runtime-image.md).
 
 The `configuration` block must reference a VCL file inside the `{{< vendor/configdir >}}` directory.
 The `path` defines the file relative to the `{{< vendor/configdir >}}` directory.
@@ -285,7 +285,7 @@ which provides access to some Varnish analysis and debugging tools.
 
 You can't use it from an app fronted by Varnish because of the restriction with [circular relationships](#circular-relationships).
 To access the stats, create a **separate app** (`stats-app`) with a relationship *to* Varnish, but not *from* it.
-Define [app configuration](../create-apps/app-reference.md) similar to the following:
+Define [app configuration](/create-apps/app-reference/single-runtime-image.md) similar to the following:
 
 ```yaml {configFile="apps"}
 # The name of the app container. Must be unique within a project.
@@ -340,5 +340,5 @@ To access the Varnish stats endpoint from the command line:
 
 1. Connect to your stats app [using SSH](../development/ssh/_index.md): `{{% vendor/cli %}} ssh --app stats-app`
    (replace `stats-app` with the name you gave the app).
-2. Display the [relationships array](../create-apps/app-reference.md#relationships) with `echo ${{< vendor/prefix >}}_RELATIONSHIPS | base64 -d | jq .`,
+2. Display the [relationships array](/create-apps/app-reference/single-runtime-image.md#relationships) with `echo ${{< vendor/prefix >}}_RELATIONSHIPS | base64 -d | jq .`,
 3. Query Varnish with `curl {{< variable "HOST" >}}:{{<variable "PORT" >}}/stats`, replacing `{{< variable "HOST" >}}` and `{{< variable "PATH" >}}` with the values from Step 2.

sites/platform/src/administration/cli/_index.md

@@ -211,8 +211,8 @@ eval $({{% vendor/cli %}} completion)
 ### Run commands on your container
 
 You can use the {{% vendor/name %}} CLI to run commands on your container.
-You can use any command you've added in [dependencies](../../create-apps/app-reference.md#dependencies)
-or a [hook](../../create-apps/app-reference.md#hooks).
+You can use any command you've added in [dependencies](/create-apps/app-reference/single-runtime-image.md#dependencies)
+or a [hook](/create-apps/app-reference/single-runtime-image.md#hooks).
 
 The syntax looks like the following:
 

sites/platform/src/administration/users.md

@@ -5,7 +5,7 @@ sidebarTitle: Users
 description: Manage user access and permissions across all your projects and organizations.
 ---
 
-{{% vendor/name %}} offers very granular and flexible user permissions across projects and organizations. 
+{{% vendor/name %}} offers very granular and flexible user permissions across projects and organizations.
 When a user is added to a project, they are automatically added to your organization.
 
 ## Manage project access
@@ -42,7 +42,7 @@ A user can have one of the following roles on an environment type which grants t
 | Contributor | Yes              | Yes       | Yes                | Yes        | No              | No              |
 | Viewer      | Yes              | No        | Yes                | No         | No              | No              |
 
-To customize which roles can use SSH, set [`access` in your app configuration](../create-apps/app-reference.md#access).
+To customize which roles can use SSH, set [`access` in your app configuration](/create-apps/app-reference/single-runtime-image.md#access).
 
 ### View a user's permissions across all of the projects in your organization
 
@@ -170,7 +170,7 @@ title=In the Console
 {{< /codetabs >}}
 
 To apply SSH access changes after you add a remove a user from a project or environment type,
-[trigger a redeploy](../development/troubleshoot.md#force-a-redeploy). 
+[trigger a redeploy](../development/troubleshoot.md#force-a-redeploy).
 
 ### Remove a user from a project
 
@@ -243,7 +243,7 @@ you can invite other users to your organization and grant them the following per
 
 Users with the **Manage users** (`members`) permission can add, edit, or remove _any_ user's permissions except their own.
 
-Users with the **Manage billing** (`billing`) permission automatically are granted **List projects** (`projects:list`) permission. 
+Users with the **Manage billing** (`billing`) permission automatically are granted **List projects** (`projects:list`) permission.
 That is, they are able to see all organization projects once given billing rights.
 
 {{< /note >}}

sites/platform/src/administration/web/configure-environment.md

@@ -41,7 +41,7 @@ There are also additional options:
 * **Code**
   * **CLI** for the command to get your project set up locally with the [{{% vendor/name %}} CLI](../cli/_index.md).
   * **Git** for the command to clone the codebase via Git.
-  
+
     If you're using {{% vendor/name %}} as your primary remote repository, the command clones from the project.
     If you have set up an [external integration](../../integrations/source/_index.md),
     the command clones directly from the integrated remote repository.
@@ -61,7 +61,7 @@ If this message isn't updated once your [default environment](../../environments
 follow these steps:
 
 1. Check that [you have defined routes](../../define-routes/_index.md) for your default environment.
-2. Verify that your [application](../../create-apps/app-reference.md), [services](../../add-services/_index.md), and [routes](../../define-routes/_index.md) configurations are correct.
+2. Verify that your [application](/create-apps/app-reference/single-runtime-image.md), [services](../../add-services/_index.md), and [routes](../../define-routes/_index.md) configurations are correct.
 3. Check that your default environment is [active](../../environments/deactivate-environment.md#reactivate-an-environment).
 
 ## Environment settings

sites/platform/src/create-apps/_index.md

@@ -16,7 +16,7 @@ Within a single project, you can have one or more apps and each app can have mul
 Instances are where the same code can be run with different configurations,
 such as one for external communication and one for background processes.
 All of the apps and instances are configured with the same syntax.
-You can find a [complete reference](./app-reference.md) of all possible settings.
+You can find a [complete reference](/create-apps/app-reference/single-runtime-image.md) of all possible settings.
 
 ## A minimal application
 
@@ -69,23 +69,23 @@ If you want to use one of the [databases or other services {{% vendor/name %}} p
 set it up by following these steps:
 
 1. Configure the service based on the documentation for that service.
-1. Use the information from that service inside your app's [`relationships` definition](./app-reference.md#relationships)
+1. Use the information from that service inside your app's [`relationships` definition](/create-apps/app-reference/single-runtime-image.md#relationships)
    to configure how your app communicates with the service.
 
 ## Control the build and deploy process
 
 Your app generally needs to undergo some steps to be turned from the code in your Git repository into a running app.
-If you're running a PHP or Node.js app, this starts with the [build flavor](./app-reference.md#build),
+If you're running a PHP or Node.js app, this starts with the [build flavor](/create-apps/app-reference/single-runtime-image.md#build),
 which runs a default set of tasks.
-Then any [global dependencies](./app-reference.md#dependencies) can be installed.
+Then any [global dependencies](/create-apps/app-reference/single-runtime-image.md#dependencies) can be installed.
 
 Once these optional tasks are done, you can run [hooks](./hooks/_index.md) at various points in the process.
 Hooks are places for your custom scripts to control how your app is built and deployed.
 
 ## Configure what's served
 
 Once your app is built, it needs a defined way to communicate with the outside world.
-Define its behavior with a [`web` instance](./app-reference.md#web).
+Define its behavior with a [`web` instance](/create-apps/app-reference/single-runtime-image.md#web).
 There you can set what command runs every time your app is restarted,
 how dynamic requests are handled, and how to respond with static files.
 

sites/platform/src/create-apps/app-reference/_index.md

@@ -0,0 +1,32 @@
+---
+title: "App reference"
+weight: 4
+description: Configure your app and control how it's built and deployed on {{% vendor/name %}}.
+layout: single
+---
+
+To define your app, you can either use one of {{% vendor/name %}}'s [single-runtime image](/create-apps/app-reference/single-runtime-image.md)
+or its [composable image (BETA)](/create-apps/app-reference/composable-image.md).
+
+## Single-runtime image
+
+{{% vendor/name %}} provides and maintains a list of single-runtime images you can use for each of your application containers.</br>
+See [all of the options you can use](/create-apps/app-reference/single-runtime-image.md) to define your app using a single-runtime image.
+
+## Composable image (BETA)
+
+The {{% vendor/name %}} composable image provides more flexibility than single-runtime images.
+When using a composable image, you can define a stack (or group of packages) for your application container to use.
+
+There are over 80,000 packages available from the [Nix Packages collection](https://search.nixos.org/) that you can add to your stack.
+You can add as many packages to your application container as you need.
+
+{{% note %}}
+
+{{% vendor/name %}} guarantees optimal user experience with the specific [set of packages](/create-apps/app-reference/composable-image.md#supported-nix-packages) it supports.
+You can use any other package available from the [Nix Packages collection](https://search.nixos.org/), including unstable ones,
+but NixOs is reponsible for their support.
+
+{{% /note %}}
+
+See [all of the options you can use](/create-apps/app-reference/composable-image.md) to define your app using the composable image.